Example of Shinylive application deployed on GitHub Pages
This repository demonstrates how to deploy Shinylive applications to GitHub Pages.
Shiny for Python applications can be deployed with Shinylive, which lets them run entirely within the browser without the need for Python running on a server. Instead, Python runs in the web browser, using Pyodide, which is a version of Python compiled to WebAssembly.
See the deployed application:
See the application with an interactive editor: (Note that editing the code on this page will only modify the copy running in the user's browser; it will not modify the deployed application.)
First, make sure you have recent versions of the shiny
and shinylive
Python packages:
pip install shiny shinylive --upgrade
Next, create a directory for your project:
mkdir shinylive-example
cd shinylive-example
git init
Then create a Shiny application in myapp/
:
shiny create myapp
After editing the application, commit it to the repository:
git add myapp
git commit -m"Add application"
At this point, you can create the repository on GitHub. After you do that, it will show how to push to the repository, with instructions like these (but with different values for <username>
and <repo>
). Run those commands to push to the repository:
git remote add origin https://github.com/<username>/<repo>
git branch -M main
git push -u origin main
Now you can use shinylive export
locally to make sure that your application will work correctly when deployed as a Shinylive application. We'll put the result in a directory named docs/
, then serve up those files and view them in a web browser:
shinylive export myapp docs/
python3 -m http.server --directory docs --port 8008
The commands above will serve the site. You can visit it in your web browser at http://localhost:8008/. When you're done, go back to the terminal and press Ctrl-C to stop serving the files.
At this point, you have some options for deploying the application to GitHub Pages. Here are two ways of doing it:
docs/
directory and push to GitHub.docs/
, and instead use GitHub Actions to run shinylive export
and deploy to GitHub Pages.The advantage of (1) is that you can be sure that the files served on website are exactly the same as the ones on your local system. You can also be sure that you can always retrieve those exact files in the future if you need them for some reason. The drawback is that the files in docs/
may be large, because that directory contains Pyodide as well as Python packages used by the application. This is at least 28MB, for a minimal set of packages. If you update to a new version of the Shinylive web assets, it will commit new versions of these files, which can cause the repository to become quite large over time.
The main advantage of (2) is that the repository can remain very small. It will also be rebuilt every time you push commits to GitHub, so you can be sure that the resulting web site is up-to-date with minimal effort. The drawback is that the docs/
directory is not committed to the repository, so you cannot easily see the exact files that are deployed, nor can you retrieve old versions of the deployed files from the repository.
This example repository uses option (2) to deploy this site: https://wch.github.io/shinylive-example/
docs/
GitHub Pages websites can serve files directly from a branch of a repository. To do this, first go to your repository page, then click on Settings, then click on Pages in the sidebar. Under Build and Deployment > Source, it should say Deploy from a branch. Under Branch, make sure the main
branch is selected, and set the folder to /docs
. Then click the Save button.
The commit and push the docs/
directory.
git add docs
git commit
git push
After a short time, the website will be published at http://<username>.github.io/<repo>
. For example, this repository's website is at https://wch.github.io/shinylive-example/.
docs/
, and build using GitHub ActionsYou can use GitHub Actions to publish to GitHub Pages. (Note that this feature is currently in beta as of 2022-09).
To enable this feature, first go to your repository page, then click on Settings, then click on Pages in the sidebar. Click on Build and Deployment > Source, and change it from Deploy from a branch to GitHub Actions.
The next step is to configure a GitHub Action to automatically (1) run shinylive export
and (2) publish the result to GitHub Pages. To do this, copy the .github/workflows/deploy.yml file from this repository, and add it your repository in the same path.
It is also a good idea to add a .gitignore
file with the following:
docs/
This will prevent you from accidentally committing your local copy of docs/
(which is generated when you run shinylive export
locally).
After you commit these files and push, the GitHub action should automatically run. You can see the progress in the Actions tab of your repository. It will look something like this:
If and when it runs successfully, the website will be published at http://<username>.github.io/<repo>
. For example, this repository's website is at https://wch.github.io/shinylive-example/.