Vercel has since published an official example for using Github pages. While the content below could still be useful as a reference, I recommend using their official example for the actual implementation.
Vercel promotes itself as "The easiest way to deploy your Next.js app"...and it's really great. You could totally use it. Netlify offers a similar service for building modern web apps which is also amazing.
However, I feel like Vercel and Netlify really want you on their SaaS. If you're interested in owning your own data (like I am), hosting on a SaaS could be problem. I've also found almost no current documentation around deploying a static NextJS app to Github Pages. Well, I figured it out and I'm sharing my findings with you.
I'm going to gloss over this part, because I assume you already know how to create a Github repo and generate a NextJS app. You'll also need to place a .nojekyll
file in /public
to bypass Github Pages from trying to auto-generate a static Jekyll site.
Before Github Actions can commit and push to your github-pages
branch, it needs to authenticate with itself (sorry, I find this hilarous π). You'll need to generate new Public and Private keys. Don't worry, these new keys wont override your personal SSH keys.
In your app directory, run the following command:
ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""
Now open the keys in your code editor. In just a minute, you're going to copy and paste the contents into your Github repository settings.
In your Github repository:
- Go to Settings --> Deploy Keys
- Title:
Public key of ACTIONS_DEPLOY_KEY
- Key: (copy and paste the public key)
- Check: Allow write access
- Click: Add key
In your Github repository:
- Go to Settings --> Secrets
- Click: Add a new secret
- Name:
ACTIONS_DEPLOY_KEY
- Value: (copy and paste the private key)
- Click: Add key
Now Github Actions will be able to authenticate with your Github repository. You can safely delete the two keys from your computer.
This is where the magic happens. The workflow file is running a few commands to deploy the app.
Here are the steps:
- Check out
/main
branch - Setup Node LTS
- Get NPM's cache from the last build π
- Build the app
- Deploy the app to the
/github-pages
branch (using a theACTIONS_DEPLOY_KEY
you generated earlier).
My Github Action workflow uses this action to handle the actual deployment. I went with a third-party action, because I don't want to have to maintain it.
Here's the workflow in .yml
:
name: Deploy to github pages
on:
pull_request:
branches: [main]
workflow_dispatch:
jobs:
deploy:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [14.x]
steps:
- uses: actions/checkout@v2
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v1
with:
node-version: ${{ matrix.node-version }}
- name: Cache dependencies
uses: actions/cache@v2
with:
path: ~/.npm
key: ${{ runner.OS }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.OS }}-node-
${{ runner.OS }}-
- name: Build
run: |
npm ci
npm run build
npm run export
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
publish_dir: ./out
This is the easiest step, because as soon as Github recognizes there's a /gh-pages
branch, it'll automatically activate the Github Pages feature.
You should be able to see your app right away at https://your-username.github.io/your-repo-name/
Thanks for reading and I hope this helps. If you noticed someting wrong, please file an issue. Good luck!
-Greg