Serve HTML widgets and reports to a remote browser

Writes an HTML widget to disk and serves it over HTTP so it can be opened in a browser on another device, such as an iPad running a terminal over SSH or mosh. Handles mapview maps, any htmlwidget (leaflet, plotly, DT, gt), and HTML files that are already on disk, such as a rendered R Markdown or Quarto report.

serve_html(
  x,
  host = NULL,
  name = NULL,
  port = NULL,
  bind = "0.0.0.0",
  quiet = FALSE
)

Arguments

x

A mapview object, an htmlwidget, an sf object (rendered with mapview::mapview()), or a path to an existing .html file.

host

Hostname to advertise in the URL. If NULL, resolved the same way as in serve_plots().

name

Optional label used in the file name, to tell several served pages apart. Non-alphanumeric characters are replaced with -.

port

Port to bind. If NULL, a running session server is reused, otherwise a random free port is chosen.

bind

Address to bind the server to. Defaults to "0.0.0.0" so the server answers on every interface; use "127.0.0.1" to keep it local.

quiet

If TRUE, do not message the URL.

Value

The page URL, invisibly, as a character scalar.

Details

One static server is started per R session and reused by later calls, so every URL handed out stays valid and several pages can be compared in different browser tabs. Files are served from a session directory below tempdir() and are removed when R exits. Call serve_html_stop() to shut the server down earlier.

Pages are served on a background thread, so they stay reachable while R is busy computing.

The URL is messaged on a line of its own and probed once before it is returned, for the same reasons given under Troubleshooting a 404 in serve_plots().

Unlike serve_plots(), a static server has no access token. Page names carry a random component instead, and directory listing is disabled, so a URL cannot be guessed from the port alone. Binding to 0.0.0.0 still exposes the server to every machine that can reach this host, so prefer bind = "127.0.0.1" on untrusted networks.

Interactive maps load their base tiles from the internet, so the remote device needs network access beyond the tunnel to this machine.

See also

serve_map(), serve_html_stop(), serve_plots()

Other data-viewers: serve_html_stop(), serve_map(), serve_plots(), serve_plots_url(), tad_view(), view_excel(), view_in(), view_qgis(), view_vd(), view_vd_nonint()

Examples

# \donttest{
if (interactive()) {
  # a rendered report
  serve_html("output/report.html")

  # any htmlwidget (leaflet, plotly, DT, gt, ...)
  serve_html(leaflet::leaflet())
}
# }