parmsam / r-shinylive

shinylive

This repository contains an R package for exporting Shiny applications as Shinylive applications.

This repository is not the same as the https://github.com/posit-dev/shinylive repository. That repository is used to generate the Shinylive assets distribution, which is a bundle containing HTML, JavaScript, CSS, and wasm files. The R package in this repository downloads the assets and uses them to create Shinylive applications.

Twin shinylive python package: https://github.com/posit-dev/py-shinylive

Installation

You can install the released version of shinylive from CRAN via:

install.packages("shinylive")

You can install the development version of shinylive from GitHub via:

# install.packages("pak")
pak::pak("posit-dev/r-shinylive")

Usage

(Optional) Create a basic shiny application in a new directory myapp/:

# Copy "Hello World" from `{shiny}`
system.file("examples", "01_hello", package="shiny") |>
    fs::dir_copy("myapp", overwrite = TRUE)

Once you have a Shiny application in myapp/ and would like turn it into a Shinylive app in site/:

shinylive::export("myapp", "site")

Then you can preview the application by running a web server and visiting it in a browser:

httpuv::runStaticServer("site/")

At this point, you can deploy the site/ directory to any static web hosting service.

Multiple applications

If you have multiple applications that you want to put on the same site, you can export them to subdirectories of the site, so that they can all share the same Shinylive assets. You can do this with the --subdir option:

shinylive::export("myapp1", "site", subdir = "app1")
shinylive::export("myapp2", "site", subdir = "app2")

GitHub Pages

posit-dev/r-shiny has a workflow to automatically deploy your Shiny app from the root directory in your GitHub repository to its GitHub Pages. To add this workflow to your repository, call usethis::use_github_action(url="https://github.com/posit-dev/r-shinylive/blob/actions-v1/examples/deploy-app.yaml").

For more information, see the examples folder.

R package availability

The {shinylive} web assets will statically inspect which packages are being used via {renv}.

If you need a package that can not be found by {renv}, add an impossible-to-reach code within your Shiny application that has a library call to that R package. For example:

if (FALSE) {
  library(HIDDEN_CRAN_PKG)
}

If you'd rather handle it manually, call webr::install("CRAN_PKG") in your Shiny application before calling library(CRAN_PKG) or require("CRAN_PKG").

If an R package has trouble loading, visit https://repo.r-wasm.org/ to see if it is able to be installed as a precompiled WebAssembly binary.

Note from {webr}:
It is not possible to install packages from source in webR. This is not likely to change in the near future, as such a process would require an entire C and Fortran compiler toolchain to run inside the browser. For the moment, providing pre-compiled WebAssembly binaries is the only supported way to install R packages in webR.

Shinylive asset management

Each version of the Shinylive R package is associated with a particular version of the Shinylive web assets. (See the releases here.)

To see which version of this R package you have, and which version of the web assets it is associated with, simply run shinylive::assets_info() in your R session. It will also show which asset versions you have already installed locally:

shinylive::assets_info()
#> shinylive R package version:  0.1.0
#> shinylive web assets version: 0.2.1
#>
#> Local cached shinylive asset dir:
#>     /Users/username/Library/Caches/shinylive
#>
#> Installed assets:
#>     /Users/username/Library/Caches/shinylive/0.2.1
#>     /Users/username/Library/Caches/shinylive/0.2.0

The web assets will be downloaded and cached the first time you run shinylive::export(). Or, you can run shinylive::assets_download() to fetch them manually.

shinylive::assets_download("0.1.5")
#> Downloading shinylive v0.1.5...
#> Unzipping to /Users/username/Library/Caches/shinylive/

You can remove old versions with shinylive::assets_cleanup(). This will remove all versions except the one that the Python package wants to use:

shinylive::assets_cleanup()
#> Keeping version 0.2.1
#> Removing /Users/username/Library/Caches/shinylive/0.2.0
#> Removing /Users/username/Library/Caches/shinylive/0.1.5

To remove a specific version, use shinylive::assets_remove():

shinylive::assets_remove("0.2.1")
#> Removing /Users/username/Library/Caches/shinylive/0.2.1

Known limitations

• Note from {webr}:

  • It is not possible to install packages from source in webR. This is not likely to change in the near future, as such a process would require an entire C and Fortran compiler toolchain to run inside the browser. For the moment, providing pre-compiled WebAssembly binaries is the only supported way to install R packages in webR.

Development

Setup - shinylive assets

Works with latest GitHub version of posit-dev/shinylive (>= v0.2.1).

Before linking the shinylive assets to the asset cache folder, you must first build the shiny live assets:

## In your shinylive assets repo
# cd PATH/TO/posit-dev/shinylive

# Generate the shiny live assets
make submodules all

Then link the assets (using the {shinylive} R package) to the asset cache folder so that changes to the assets are automatically in your cached shinylive assets:

# Link to your local shinylive repo
shinylive::assets_install_link("PATH/TO/posit-dev/shinylive")

Setup - quarto

In your quarto project, call the following lines in the terminal to install the updated shinylive quarto extension:

# Go to the quarto project directory
cd local/quarto

# Install the updated shinylive quarto extension
quarto add quarto-ext/shinylive

By default, the extension will used the installed {shinylive} R package. To use the local {shinylive} R package, run the following in your R session to update the quarto extension locally:

if (!require("pkgload")) install.packages("pkgload")

shinylive_lua <- file.path("local", "quarto", "_extensions", "quarto-ext", "shinylive", "shinylive.lua")
shinylive_lua |>
    brio::read_file() |>
    sub(
        pattern = "shinylive::quarto_ext()",
        replacement = "pkgload::load_all('../../', quiet = TRUE); shinylive::quarto_ext()",
        fixed = TRUE
    ) |>
    brio::write_file(shinylive_lua)

Execute - export()

Export a local app to a directory and run it:

library(httpuv) # >= 1.6.12
pkgload::load_all()

# Delete prior
unlink("local/shiny-apps-out/", recursive = TRUE)
export("local/shiny-apps/simple-r", "local/shiny-apps-out")

# Host the local directory
httpuv::runStaticServer("local/shiny-apps-out/")