joe-chelladurai/quarto-webr

Quarto extension to embed webr for html documents

webR Code Extension for Quarto HTML Documents

This extension enables the webR code cell in a Quarto HTML document.

The goal of webR is to:

run R code in the browser without the need for an R server to execute the code

For more details on webR, please see:

• webR Documentation
• webR Source Code

Installation

To use this extension in a Quarto project, install it from within the project's working directory by typing into Terminal:

quarto add coatless/quarto-webr

Usage

For each document, place the the webr filter in the document's header:

filters:
  - webr

Then, place the code for webr in a code block marked with {webr}

---
title: WebR in Quarto HTML Documents
format: html
engine: knitr
filters:
  - webr
---

This is a webr-enabled code cell in a Quarto HTML document.

```{webr}
fit = lm(mpg ~ am, data = mtcars)
summary(fit)
```

When quarto render or quarto preview is called, the filter will execute under the jupyter compute engine if engine: knitr is not specified. During the execution, the filter adds two files to the working directory: webr-worker.js and webr-serviceworker.js. These files allow for the webR session to be started and must be present with the rendered output.

Packages

By default, the quarto-webr extension avoids loading or requesting additional packages. Additional packages can be added by including:

webr::install("package")

For example, to install ggplot2, you would need to use:

webr::install("ggplot2")

You can view what packages are available by either executing the following R code (either with WebR or just R):

available.packages(repos="https://repo.r-wasm.org/", type="source")

Or, by navigating to the WebR repository:

https://github.com/r-wasm/webr-repo/blob/main/repo-packages

Known Hiccups

As this is an exciting new frontier, we're learning as we go. Or as my friend Lawrence says, "I like to build airplanes in the air-". Please take note of the following issues:

Stuck at Loading webR...

If webr-worker.js or webr-serviceworker.js are not found when the document loads either at the root / or relative directory, then Loading webR... will appear above the code cell instead of Run code. Please make sure the files are at the same location as the quarto document. For example, the following structure will work:

.
├── demo-quarto-webr.qmd
├── webr-serviceworker.js
└── webr-worker.js

Directly accessing rendered HTML

When using quarto preview or quarto render, the rendered HTML document is being shown by mimicking a server running under https://localhost/. Usually, everything works in this context assuming the above directory structure is followed. However, if you directly open the rendered HTML document, e.g. demo-quarto-web.html, inside of a Web Browser, then the required WebR components cannot be loaded for security reasons. You can read a bit more about the problem in this StackOverflow answer.

There are a few possible solutions to avoid requiring quarto on a local computer to directly open the rendered file:

• Use Chrome's --allow-file-access-from-files access
• Use the WebServer for Chrome extension
• Or, use NPM to obtain local-web-server

Speed up webR

When serving webR documents, please try to ensure the COOP and COEP HTTP headers are set to speed up the process:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

For users who host their website with Netlify, add to the netlify.toml configuration file:

[[headers]]
  for = "/directory/with/webr/content/*"

  [headers.values]
    Cross-Origin-Opener-Policy = "same-origin"
    Cross-Origin-Embedder-Policy = "require-corp"

For users who deploy their site with GitHub Pages, please hang tight! By default, GitHub Pages does not allow for headers to be modified. There have been notable efforts by the GitHub Pages community to circumvent this limitation by using coi-servicworker. We're currently testing it out.

For users who administer a server with nginx, the add_header directive can be used to add headers into the configuration file at /etc/nginx/nginx.conf.

server {
  # Enable headers for the webr directory
  location ^~ /directory/with/webr/content {
    add_header "Cross-Origin-Opener-Policy" "same-origin";
    add_header "Cross-Origin-Embedder-Policy" "require-corp";
  }
}

More information may be found in nginx's Serving Static Content.

For additional justificaiton on why the headers are required, please see webR's documentation page for Serving Pages with WebR.

Engine Registration

If using the knitr engine instead of the jupyter engine, there is a known warning that will appear in the render processing output of:

Warning message:
In get_engine(options$engine) :
  Unknown language engine 'webr' (must be registered via knit_engines$set()).

This warning does not prevent or impact the ability of the webr filter to function. Though, we would like to address it at some point since it is not aesthetically pleasing.

Acknowledgements

We appreciate the early testing feedback from Eli E. Holmes and Bob Rudis.

This repository builds ontop of the initial proof of concept for a standalone Quarto HTML document in:

https://github.com/coatless-r-n-d/webR-quarto-demos

The proof of concept leaned heavily on the webR developers public-facing examples:

• Source of Tidyverse Blog Post and Minor fix
• webR documentation landing page (Live page)

For the extension, we greatly appreciated insights from:

• Extensions
  • quarto-ext/shinylive
  • mcanouil/quarto-elevator
  • shafayetShafee/downloadthis
• Quarto Documentation
  • Filters Documentation
  • Lua Development Tips
  • Lua API
• Pandoc Documentation
  • Example Filters
  • CodeBlock