Installing R Packages

WebR supports the loading of R packages that have been pre-compiled targeting WebAssembly.

WebR packages must be installed before use, which in practice means copying binaries into the webR virtual filesystem in some way, either as part of the webR build process or during runtime by downloading packages from a repository or mounting filesystem data.

Downloading packages from a webR binary repository

A collection of supported packages are publicly hosted via a CDN in a CRAN-like repository with URL,

https://repo.r-wasm.org/

The public CDN build of webR has been distributed with a pre-installed webr support package. This R package provides a helper function install(), which can be used to install further R packages from a compatible webR binary repository.

The repository URL is set using the repos argument and the public build of webR defaults this argument to the repository URL shown above1.

Example: Installing the Matrix package

Run the following R code in a running webR session, such as the webR REPL demo,

webr::install("Matrix")

If the package is available for webR and downloads successfully, you can then load the package in the usual way.

library("Matrix")

Shimming install.packages() for webR

The webr support package includes the function shim_install() which optionally replaces specific base R functions with implementations that work in the webR environment. Once executed, the base R install.packages() function can be used to install webR packages.

webr::shim_install()
install.packages("Matrix")

The webR REPL demo performs this base R function replacement as part of its startup procedure.

Interactively installing packages

The install() and require() base R functions can be shimmed by the function shim_install() so that when a package is missing it is downloaded from the default webR binary package repository.

An interactive prompt may be shown, asking the user if they would like to download the package. To enable the interactive menu, the webr.show_menu global option should be set to TRUE. Otherwise, the user will not be prompted and the package will be downloaded automatically.

webr::shim_install()
options(webr.show_menu = `TRUE`)

Once the menu has been enabled, it is possible to install and load packages interactively via a prompt. The process looks as follows,

library(Matrix)
Failed to load package "Matrix". Do you want to try downloading
it from the webR binary repo?
  1: Yes
  2: No
Selection: 1
Downloading webR package: lattice
Downloading webR package: Matrix

After the package has been downloaded and installed, the original library() or require() function will be invoked to continue loading the package as usual.

Handling missing packages using a global handler function

An optional global handler is also provided that can be used to automatically download packages if loading fails. The handler can be installed with global_prompt_install() and allows packages to be automatically downloaded without explicitly loading them with library() or require(). When using the global handler, prompting the user with an interactive menu is also controlled by the webr.show_menu global option.

options(webr.show_menu = FALSE)
webr::global_prompt_install()
cli::cli_alert_success("The cli package is working!")
Downloading webR package: cli
✔ The cli package is working!
Note

When the global handler is installed from JavaScript the R code must be evaluated without any other calling handlers on the stack. This can be arranged by setting the withHandlers option to false2.

await webR.evalR(`
  webr::global_prompt_install()
  cli::cli_alert_success('The cli package works!')
`, { withHandlers: false });

Installing packages from JavaScript

The webR JavaScript API provides the function WebR.installPackages(). This convenience function takes an array of packages as its only argument and for each calls install() with the default webR binary package repository.

await webR.installPackages(['Matrix', 'cli'])

Once the promise returned by WebR.installPackages() has resolved, the packages can be loaded in the usual way using library().

Mounting an R library filesystem image

R libraries that have been packaged with Emscripten’s file_packager tool may be loaded into the webR virtual filesystem (VFS) by mounting the image using webr::mount(). When using webR in a browser, type = "WORKERFS" (the default) should be used so that the filesystem image is downloaded from the URL given by source and mounted on the VFS at mountpoint.

webr::mount(
  mountpoint = "/library",
  source = "https://example.com/library.data"
)

Once the library filesystem image has been mounted, the base R .libPaths() function should be used to ensure mountpoint is included in R’s package library search path.

.libPaths(c(.libPaths(), "/library"))

Packages that exist in the R library filesystem image can then be loaded as normal.

library(mypackage)

Details on how to build a WebAssembly R package library can be found in the Building R Packages section, and further information about mounting data to the VFS (including when running under Node.js) can be found in the Mounting Filesystem Data section.

Footnotes

  1. Other R package repositories providing WebAssembly binaries are also available, such as R-universe.↩︎

  2. When evaluating R code in this way R error conditions cannot easily be captured. An alternative is to use shim_install() and explicitly load R packages using library() or require().↩︎