This guide takes you through how to deploy a Node app with GitHub Actions so that the static output can be served as GH Pages. This works well for Single-Page Applications, such as if using React or Vue.
Submission category
This is my submission to GitHub Actions Hackathon under DIY Deployments.
How it works
- My workflow will be triggered by any pushes to
master
and any Pull Requests againstmaster
. Any changes to thedocs
directory will not trigger the workflow, as there is no point in rebuilding the app in that case. - The GitHub Actions environment already includes Node and Yarn, so if you don't care about the specific versions needed, you can leave out setup steps. For more control, see Node workflows.
- There are shell steps to install NPM dependencies, run checks (linting and formatting) and then build the app. You can use
npm
oryarn
in the steps. - The final step uses an Action which will take the unversioned output in the
dist
directory and commit it to the root of thegh-pages
branch. For Vue,dist
is typical, while React projects usebuild
.
The repo should configured to serve the gh-pages
branch as a site.
Sample YAML file
Create a workflow as .github/workflows/main.yml
in your repo.
name: Deploy GH Pages
on:
push:
branches: master
paths-ignore:
- "docs/**"
pull_request:
branches: master
paths-ignore:
- "docs/**"
jobs:
build-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout ποΈ
uses: actions/checkout@master
with:
persist-credentials: false
- name: Install π§
run: yarn install # OR npm install
- name: Lint π§
run: yarn lint:check # OR npm run lint:check
- name: Build ποΈ
run: yarn build # OR npm run build
env:
NODE_ENV: production
- name: Deploy to GH Pages π
if: ${{ github.event_name != 'pull_request' }}
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: dist
Note that you don't have to generate or set a token - a token will be generated for you by GH Actions. A token which only has access to the current repo and no human will need to interact with the token.
After committing the above file, check your Actions tab and wait for the workflow to run.
After it is successful, go to repo settings and enable Pages against the root of your gh-pages
branch, to serve that as a GH Pages site.
Then check the Environment section to see it deployed.
Note also that the actual deploy step only runs against master
commits directly and not on a Pull Request. So you can safely have your test and build steps run against a feature branch on a Pull Request for quality control, without actually deploying anything until the PR gets merged.
Workflows in use
Vue
I have a vue-quickstart
repo which was generated with Vue CLI and then extended with documentation, CI/CD, and demo site.
MichaelCurrin / vue-quickstart
Starter template for a Vue 2 site - including docs and CI deploy to GH Pages
Vue Quickstart
Starter template for a Vue 3 site - including docs and CI deploy to GH Pages
Preview
Use this project
After you've looked at the demo screenshot and site, you are welcome to create your own using the template button. This will copy this project and add it to your repos (no forking needed, but please star the original repo).
Documentation
How to install and run the app locally and deploy it to GH Pages
About
What is Vue?
Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Why not React?
Vue is intended to be more beginner-friendly (I agree it is) and the vue repo has more GH stars than the react repo, if that is any indication of adoption by the community.
Vue is open-source and was created by one person originally. React was created at Facebook.
Resources
Need are some resourcesβ¦
See main.yml there.
React
I did the same thing for React:
MichaelCurrin / react-quickstart
Starter template for a React app - including docs, CI, and hosting β π¦
React Quickstart βοΈ π¦
Starter template for a React app - including docs, CI, and hosting
Preview
Create a new React app
Use this project as a template:
If you need something more minimal, see this Minimal app recipe.
Documentation
To install, run and deploy the app, see this project's docs:
To learn how to use this project and see how a React project works, see the Template notes section of the docs.
License
Released under MIT by @MichaelCurrin.
This project is based on the template from the React CLI. I have added my own docs, the deploy flow, made minor changes to the app, plus some additions to components.
See main.yml there.
Resources
On Code Cookbook
I have a ton of GH Actions workflows you can browse here:
On my Dev Resources site
- Node resources
- GH Actions resources
- GH Pages resources
- Vue resources
- React resources
More template repos
No Node or CI needed here! These use CDN URLs to load React or Vue in the browser and that static HTML gets served directly on GH Pages without a build step.
Credits
Photo by Andrik Langfield on Unsplash
Top comments (1)
Very nice bro thank you very much)