Deploy Shinylive R App on Github Pages

This repo provides a step-by-step guide for deploying an R Shinylive app to Github Pages. This tutorial is also available on Medium.

For deploying a Python Shinylive app to Github Actions check this tutorial.

Last update: 2024-01-16

Table of Content

• Introduction
• Prerequisites
• Render the Shiny App
• Deploy App on Github Pages
• Resources
• License

Introduction

Shinylive is a serverless version of Shiny, which enables running Shiny applications in a web browser without needing a backend server. It was first introduced for Python during Posit Conf 2022 using WebAssembly and Pyodide, and its R version during the Posit Conf 2023 using WebR.

Figure 1 - Shinylive archticture, source: Joe Cheng "Running Shiny without a server"

Currently, there are three methods (or formats) to use Shinylive applications:

• Render a Shiny app into HTML static file using the shinylive package
• Host a Shiny app in Fiddle - a built-in web application to run Shiny R and Python applications
• Embed Shiny app in Quarto documentation using the quarto-shinylive extension for Quarto

In this tutorial, we will focus on the first option above, using the shinylive package to render the app into an HTML file and deploy it as a static website to Github Pages. We will use the Forecasting Sandbox with a Shiny app to demonstrate the deployment process. The app provides a sandbox for three simple forecasting models - Linear regression, ARIMA, and Holt-Winters, enabling the user to modify the model's parameters and explore the change in the output interactively.

Prerequisites

The main prerequisite for this tutorial is the shinylive and httpuv packages, which can be installed directly from CRAN:

install.packages(c("shinylive", "httpuv"))

Those are the package versions used in this tutorial:

 packageVersion("shinylive")
[1] ‘0.1.1’

packageVersion("httpuv")
[1] ‘1.6.13’

And, of course, you will have to have a Shiny app file. In this tutorial, we use a simple Shiny app located under the myapp folder:

.
└── myapp
    └── app.R

Using Docker

If you use VScode, the repository contains the Dev Containers settings for running this tutorial inside a dockerized environment. That includes the following files:

.devcontainer
├── devcontainer.json
├── Dockerfile
├── Dockerfile.dev
├── install_packages.R
├── packages.json
└── requirements.txt

Where the devcontainer.json is the Dev Containers setting file, the Dockerfile.dev and Dockerfile are the dev and prod dockerfiles. The install_packages.R and packages.json files define the R requirements (e.g., packages to install), and the requirements.txt file defines the Python requirements (which are needed to run R with radian). For more details on setting up an R dockerized development environment with VScode and the Dev Containers extension, please check the following tutorial.

Render the Shiny App

Once the above prerequisites are set, it is straightforward to deploy the app on Github Pages. First, let's render the app into an HTML file using the export function:

shinylive::export(appdir = "myapp", destdir = "docs")

The appdir argument defines the app folder (in this case, under the myapp folder). The destdir argument defines the output of the rendered site (in this case, defined as docs).

The function will render the app into a website structure, setting the index.html file and its assets into the docs folder.

Why docs? We set the destdir argument to docs as the Github Pages' setting required the website files to either be in the repository root folder or the docs folder. The latter, having the site under a folder, is a cleaner option than having it under the root folder.

You should expect to have under the docs folder the edit and shinylive folders:

.
└── docs
    ├── edit
    └── shinylive

You can check if the rendering process was successful using the runStaticServer function from the httpuv package:

httpuv::runStaticServer("docs/", port=8008)

That should launch the app on your default browser:

Figure 2 - Testing the app on your local browser using the runStaticServer function from the httpub package

Note: The runStaticServer function is available on the latests CRAN version of the package, make sure you have version 1.6.13 installed or above.

Alternatively, you can test that your code works as expected on the browser using the Shinylive code editor.

Deploy App on Github Pages

Before deploying the app to Github Pages, commit and push the changes (e.g., the rendered website). You can verify on the Github repository that you have the docs folder.

Last but not least, we will set up the Github Pages website. On the repository main menu, go to settings (pink rectangle on the screenshot below), select the Pages option (blue rectangle), and select the branch you want to use and the folder website files are located. In this case, we will select the docs folder (yellow rectangle). Once you complete those steps, you should get the link for the Github Pages website (brown rectangle). It might take a few minutes until the website is ready and accessible.

Figure 3 - Deploying the Shiny app on the Github Pages website

That's it! The website is now ready!

https://ramikrispin.github.io/shinylive-r/

Resources

• Joe Cheng's Running Shiny without a server presentation at the Posit Conf 2023
• Shinylive R and Python dev version packages
• Shinylive web R and Python code editor
• Shinylive examples R and Python examples

License

This tutorial is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.