Deploy a NextJS app on Github Pages with Github Actions

👉 View the deployed app

Table of Contents

Update
Introduction
Getting Started
Generate Deploy Key
- Public Key
- Private Key
Github Actions
Github Pages
Wrap up

Update

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.

Introduction

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.

Getting Started

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.

Generate Deploy Key

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.

Public Key

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

Private 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.

Github Actions

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 the ACTIONS_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

Github Pages

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/

Wrap up

Thanks for reading and I hope this helps. If you noticed someting wrong, please file an issue. Good luck!

-Greg

License

jlintag/nextjs-github-pages

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages