GitHub Action for an Org webR WASM R Package Repository

Introduction

This repository serves as an example of the recommended setup for creating a mini-CRAN repository for webR R WASM Package binaries. It aligns closely with the guidance provided in the webR project’s Build R packages using GitHub Actions documentation.

This repository is part of a series exploring three different approaches:

• Org-focused webR/WASM Package Repository without a {pkgdown} website [This repository]
  • This repository serves as an example implementation of the webR Project’s Build R packages using GitHub Actions documentation. It focuses on creating an organizational webR/WASM Package Repository without the inclusion of a {pkgdown} website that is meant to be triggered through workflow dispatches or changes to a packages file. Explore this repository for insights into structuring your own organization-centric webR package repository using GitHub Actions.
• Unified GitHub Action Deployment using artifacts of R WASM Package binaries and {pkgdown} website
  • This repository introduces a unified approach to GitHub Action deployment by using artifacts. Unlike the previous strategy, this allows for the simultaneous deployment of R WASM binaries and the associated {pkgdown} website by using artifacts. This approach helps prevent a continuous increase in repository size. Explore this repository to understand how the use of artifacts can streamline your deployment process while maintaining a clean and efficient version control history.
• Separate GitHub Action Deployment onto gh-pages branch of R WASM Package binaries and {pkgdown} website
  • This repository adopts a workflow approach familiar to R package developers using usethis. It employs separate GitHub Actions for generating the R WASM package binaries and {pkgdown} website. The key aspect of this approach is the merging and deployment of both outputs through the gh-pages branch. This strategy enhances clarity in tracking file changes and provides a transparent view of the deployed content. Explore this repository to understand how this approach can streamline your R package deployment workflow.

Another approach would be to use r-universe.dev to automatically build and supply R WASM package binaries.

Key Contents

Here’s a quick summary of what you can find in the repository:

• .github/workflows/deploy.yml: A replicate of the r-wasm/actions’ deploy-cran-repo.yml workflow.
• packages: A list of R packages that adheres to package reference values supported by pak.

Setup packages

When trying to setup an environment for your own packages, please make sure to modify the packages file to contain the appropriate package reference value supported by pak. In the case of generating R WASM package binaries from GitHub, you can achieve this with:

gh-username/reponame

Or, more formally with:

github::gh-username/reponame

Need a package from CRAN? This can be specified as:

pkgname

So, the example packages file contains three lines where 2 are dedicate to install a package on GitHub as well as CRAN and the last line is an empty line:

coatless-rpkg/drawr
visualize

Note: Not leaving an empty line will result in a warning message during the “Retrieve packages from ./packages file” step.

Warning message:
In readLines("./packages") : incomplete final line found on './packages'

Setup Github Pages on the Repository

After the desired packages are specified, the next step is to enable GitHub Pages for the repository.

1. Click on the Settings tab for the repository
2. Under “Code and automation”, select the Pages menu item.
3. Under the “Source” option select GitHub Action from the drop down.
4. In the “Custom Domain” settings, make sure that Enforce HTTPS is checked.

Trigger a build

The R WASM Package binaries are either built by updating/committing files in the repository or by manually triggering a workflow deploy.

You can trigger a workflow deploy by:

1. Go to the Actions tab of the repository
2. Select the Build and deploy wasm R package repository workflow
3. Click on Run workflow dropdown
4. Press the green Run workflow button.

Observing Data Uploaded

When the workflow completes, the packages and repository structure is uploaded onto GitHub Pages through an artifact. The artifacts are stored for 90 days (by default) and can be found under the workflow summary:

1. Click on the Actions tab for the repository
2. Select a completed build
3. Press the Summary option
4. Under “Artifacts”, click on github-pages to download the built repository

Note: The size of the repository with only two R-based packages requires 1.52 MB of compressed space.

If you have permissions to the repository, you should be able to download the github-pages artifact by clicking on the name above. This will trigger the download of artifact.zip that when extracted will have the form of:

├── bin
│   └── emscripten
│       └── contrib
│           └── 4.3
│               ├── PACKAGES
│               ├── PACKAGES.gz
│               ├── PACKAGES.rds
│               ├── mypackage_1.0.0.data
│               ├── mypackage_1.0.0.js.metadata
│               └── mypackage_1.0.0.tgz
└── src
    └── contrib
        ├── PACKAGES
        ├── PACKAGES.gz
        ├── PACKAGES.rds
        └── mypackage_1.0.0.tar.gz

where mypackage_1.0.0 should resemble the names of the packages specified in the packages file setup above.

Usage inside webR

Accessing Binaries

In a webR session, access the built binaries using the repository’s GitHub Pages URL, for example:

https://gh-username.github.io/repo-name

Depending on where you are using the custom R WASM package binary, you can register this repository in different ways:

1. Using the repos key inside of the quarto-webr extension;
2. Using options() to set values for both repos and webr_pkg_repos; or,
3. Using the repos parameter in each webr::install() call.

repos Document key in {quarto-webr}

With version v0.4.0 of the {quarto-webr} extension, the repository can be included by using the repos key in the document header:

---
webr:
  packages: ['pkgname']
  repos:
    - https://gh-username.github.io/repo-name
filters:
 - webr
---

Specifying repo urls with options()

To define the location webR should search for in options(), we need to set both repos and webr_pkg_repos.

## Run once at the start of the session

# Specify where to search for the R WASM packages
list_of_repos = c(
    "https://gh-username.github.io/repo-name", 
    "https://other-gh-username.github.io/another-repo", 
    "https://username.r-universe.dev", 
    "https://repo.r-wasm.org/"
  )

# Set the repository URLs
options(
  repos = list_of_repos,
  webr_pkg_repos = list_of_repos
)

# Install the R WASM Package
webr::install("pkgname")

Note

This is different than the repos option one would usually set since webR only checks the webr_pkg_repos key; however, other R functions like available.packages() check the repos parameter.

Specifying repos in webr::install()

The repos parameter may also be specified in the webr::install() command each time you need to install a package from a custom location:

webr::install("pkgname", repos = "https://gh-username.github.io/repo-name")

webr::install("pkgname", repos = list_of_repos)

Important

Ensure the repository’s GitHub Pages website is available over HTTPS (not HTTP). Verify this option in the repository’s Settings page under Code and automation > Pages > Enforce HTTPS.

Otherwise, you might encounter an error:

Warning: unable to access index for repository http://gh-username.github.io/repo-name/bin/emscripten/contrib/4.3

Verify

Go to the webR REPL Editor (pinned to v0.2.2) and run the following:

# Check if package `{drawr}` is installed
"drawr" %in% installed.packages()[,"Package"]
# Install the binary from a repository
webr::install(
  "drawr", 
  repos = "https://tutorials.thecoatlessprofessor.com/webr-org-gh-action/"
)
# Check to see if the function works
mat_2x2 <- matrix(1:4, nrow = 2)
drawr::draw_matrix(mat_2x2, show_indices = "cell")
# View help documentation
?drawr::draw_matrix

You should receive: