Customization Options

Fine-Tuning quarto-webr with Powerful Configuration Options

Author

James Joseph Balamuta

Published

September 14, 2023

Modified

April 26, 2024

The quarto-webr extension empowers you to tailor your webR environment to meet your unique requirements. By configuring various options in your document’s YAML header or _quarto.yml file, you can structure the webR experience on a per-page or per-project basis. Below, we explore these customization options and how to implement them.

Customization Options

Enhance your webR experience by customizing its behavior through the webr key. This key should be added before listing the filter statement.

Document YAML

To fine-tune webR to the specific needs of a document, place inside your document’s YAML header the webr key. Specifying options this way allows webR to be setup with unique options confined to only that document.

---
title: webR in Quarto HTML Documents
format: html
engine: knitr
webr: 
  show-startup-message: false    # Disable displaying status of webR initialization
  packages: ['ggplot2', 'dplyr'] # Install R packages on document open
filters:
  - webr
---

Global Configuration

If you have multiple pages that use webR, we suggest setting global options inside of the _quarto.yml file. This option is appropriate for Websites, Blogs, or Books. For instance, if you have a book project, the _quarto.yml should look like:

project:
  type: book

book:
  title: "Sample quarto-webr Book Project"
  # ... more options

# Set default options for every bookpage that may or may not include webR.
webr: 
  show-startup-message: false    # Disable displaying status of webR initialization
  packages: ['ggplot2', 'dplyr'] # Install R packages on document open

# Attach webR extension for the project
filters:
  - webr

Note

If a webR code cell is not present on a website, blog, or book page, then the quarto-webr extension will not setup webR on the page.

You can see full examples of setting a global option under the Deployment Templates page.

webR options

By specifying various WebROptions options in the document YAML, you can create a personalized webR experience

`home-dir`

Description: Set the WebAssembly user’s home directory and initial working directory.
Default Value: '/home/web_user'
Documentation: homeDir

`base-url`

Description: Define the base URL for downloading R WebAssembly binaries.
Default Value: 'https://webr.r-wasm.org/[version]/'
Documentation: baseUrl

`channel-type`

Description: Specify the communication channel type to interact with webR.
Default Value: "automatic" (0)
Possible Values: "automatic" (0), "shared-array-buffer" (1), "service-worker" (2), "post-message" (3).
Documentation: channelType

Note

We recommend using the "post-message" channel when GitHub Pages or Quarto Pub serve the webR-enabled document. Note that this option prevents the interruption of running R code and the use of nested R REPLs (readline(), menu(), browser(), etc.). For more details, please see Communication Channels

`service-worker-url`

Description: Set the base URL for loading JavaScript worker scripts when using the ServiceWorker communication channel mode.
Default Value: ''
Documentation: serviceWorkerUrl

Native Extension Options

The extension also provides native options that affect its behavior:

`show-startup-message`

Description: Controls the display of the WebR initialization state in the document header.
Default Value: true
Demo Document: Setting Options in Document Header

`show-header-message`

Description: Determines whether COOP and COEP headers are in use for faster page loads.
Default Value: false
Demo Document: Setting Options in Document Header

`cell-options`

Description: Modifies default cell options for {webr-r} cells.
Default Value: Please see Code Cell Options for individual cell option defaults.
Demo Document: Set Global Cell Options
Example:

webr:
  cell-options:
    autorun: true
    fig-height: 400
    fig-width: 300

This modifies the default cell options for autorun, fig-width, and fig-height for all cells in the document.

`repos`

Description: Specify the repository locations to search for R packages when trying to install them in array form. Regardless of values specified, we will always conclude by checking to see if the package is present in the main webR repository: https://repo.r-wasm.org/.
Default Value: ['https://repo.r-wasm.org/']
Demo Document: Custom R WASM Package Repository
Example: ['https://username.r-universe.dev', 'https://username.github.io/reponame'] will cause webR to first look for the package on r-universe.dev, then move to looking at the package on GitHub Pages, before finally landing on the official repository.

`packages`

Description: Specifies R packages to install automatically when the document opens.
Default Value: []
Demo Document: Setting Options in Document Header
Example: ['ggplot2', 'dplyr'] will cause ggplot2 and dplyr to be installed.

`autoload-packages`

Description: The autoload-packages option allows you to control whether R packages specified in the packages document option will be automatically loaded using library() calls when the document opens. By default, this option is set to true, meaning that packages listed in the packages option will be automatically loaded. If you set it to false, you will need to include a code cell with library(package) function calls for each package in packages.
Default Value: true
Demo Document: Setting Options in Document Header