Welcome to this tutorial on automating separate build processes for
compiling an R package for webR
and creating a {pkgdown}
website using GitHub Actions. In this guide,
you will find sample GitHub Action workflows designed to generate
developmental webR/R WASM Package binaries alongside a {pkgdown}
website. If you’re eager to streamline the process of building and
deploying your R packages for webR while also creating a {pkgdown}
website, you’ve come to the right place.
This repository is part of a series exploring three different approaches:
- Org-focused webR/WASM Package Repository without a
{pkgdown}
website- 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 apackages
file. Explore this repository for insights into structuring your own organization-centric webR package repository using GitHub Actions.
- 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
- 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.
- 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
- Separate GitHub Action Deployment onto
gh-pages
branch of R WASM Package binaries and {pkgdown} website [This repository]- 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 thegh-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.
- This repository adopts a workflow approach familiar to R package
developers using
Another approach would be to use r-universe.dev to automatically build and supply R WASM package binaries.
Here’s a quick summary of what you can find in the repository:
.github/workflows/deploy-cran-repo.yml
: A heavily modified version ofr-wasm/actions
’ deploy-cran-repo.yml, leveraging ther-wasm/actions/build-rwasm
action to create R WASM packages andJamesIves/github-pages-deploy-action
to deploy the packages onto a GitHub Pages branch..github/workflows/pkgdown.yml
: Standard{pkgdown}
GitHub Action fromr-lib/actions/examples/pkgdown.yaml
._pkgdown.yml
: Usual configuration for a{pkgdown}
website.DESCRIPTION
: Contains usual meta data information for an R package.R/in-webr.R
: A script designed to check if the R package is being run inside a webR environment.
The deployment strategy for this repository involves pushing built R
WASM Packages and the associated {pkgdown}
website directly into the
gh-pages
branch. You can view the pushed webR package binary parts by
looking at the
gh-pages
branch of the repository. Specifically, we can see binary package data
bin/emscripten/contrib/4.3
and the package information in
src/contrib
.
The other files form the basis for the {pkgdown}
website. You can
learn more about package repositories that are CRAN-like in the R
Administration: 6.6 Setting up a package
repository.
It’s essential to note that a potential drawback to this approach is the
gradual increase in the repository size with each commit. This expansion
occurs as the webR binary for the package, along with its dependencies,
is stored in the gh-pages
branch. On the positive side, utilizing
version control tools allows for clear visibility into the changes
between deployments.
For the setup, we’re going to aim to use {usethis}
R
package to enable GitHub Pages and
retrieve a workflow for building R WASM packages.
We can enable GitHub pages directly from usethis
with:
if(!requireNamespace("usethis", quietly = TRUE)) {
install.packages("usethis")
}
# Ensure GitHub Pages is set up
usethis::use_github_pages()
Another option is directly enabling GitHub Pages on the repository by following:
- Click on the Settings tab for the repository
- Under “Code and automation”, select the Pages menu item.
- Under the “Source” option select Deploy from branch from the drop down.
- Under the “Branch” option, select the
gh-pages
branch with the deploy directory of/ (root)
and press Save. - In the “Custom Domain” settings, make sure that Enforce HTTPS is checked.
Next, obtain a copy of the modified GitHub Action workflow that compiles
the R WASM package binaries and deploys them onto GitHub Pages by
committing into the gh-pages
branch with the following R code:
# Obtain the modified version of the rwasm repo setup
usethis::use_github_action(
"https://github.com/coatless-tutorials/webr-github-action-wasm-binaries/blob/main/.github/workflows/deploy-cran-repo.yml"
)
Or, you can re-create what usethis
is doing by using:
# Create the GitHub workflows directory if not present
dir.create(".github/workflows", showWarnings = FALSE, recursive = TRUE)
# Download the GitHub Action workflow into the repository
download.file(
url = "https://github.com/coatless-tutorials/webr-github-action-wasm-binaries/blob/main/.github/workflows/deploy-cran-repo.yml",
destfile = ".github/workflows/deploy-cran-repo.yml"
)
# Block R build from including the GitHub folder
writeLines(
text = "^\.github$",
con = file(".Rbuildignore", "a")
)
That’s it! Binaries will now be automatically built upon each new commit and published on the repository’s website served by GitHub Pages.
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:
- Using the
repos
key inside of thequarto-webr
extension; - Using
options()
to set values for bothrepos
andwebr_pkg_repos
; or, - Using the
repos
parameter in eachwebr::install()
call.
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
---
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.
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
Visit the webR REPL Editor (pinned to v0.2.2) and run the following:
# Check if package `{demorwasmbinary}` is installed
"demorwasmbinary" %in% installed.packages()[,"Package"]
# Install the binary from a repository
webr::install(
"demorwasmbinary",
repos = "https://tutorials.thecoatlessprofessor.com/webr-github-action-wasm-binaries/"
)
# Check if the function works
demorwasmbinary::in_webr()
# View help documentation
?demorwasmbinary::in_webr
You should receive: