Skip to contentGreg Rickaby

Greg Rickaby

Web Development

Next.js Github Pages

Author
Greg Rickaby

Vercel promotes itself as “The easiest way to deploy your Next.js app” and Netlify offers a similar service. However, both Vercel and Netlify really want you on their platforms. I’m interested in owning my own data and wanted to see if I could deploy a Next.js app to Github Pages.

During my research, I’ve found very little documentation around deploying a static Next.js app to Github Pages. I spent an entire Saturday working through it and want to share what I learned with you.

👉 View the deployed app or ⭐️ Star the Github repo

Update: Vercel has since published an official example. I recommend you take a look at the official example before making any major decisions.


Configure Next.js

In order to get images to display correctly, you’ll need to prefix your assets directory. This is required so assets served from /_next/static work correctly. Next.js has a setting for this!

  1. Create next.config.js file
  2. Add the following:
// next.config.js
const isProd = process.env.NODE_ENV === 'production'

module.exports = {
  assetPrefix: isProd ? '/your-github-repo-name/' : ''
}
  1. Save the next.config.js
  2. Finally, place a .nojekyll file in the /public directory to disable Github Pages from trying to create a Jekyll website.
.
├── pages
├── public
│   └── .nokjekyll
├── styles
├── next.config.js

Perfect! This is all you need to configure Next.js to work on Github Pages.

Heads up! Github Pages does not support serverless functions. This means dynamic functionality (such as API Routes and Image Optimization) will be disabled.

Learn more


Setup Github Repository

Now setup Github by adding some deploy keys and setting up a Github Action for automated deployments.

Generate Deploy Keys

Before Github Actions can commit and push to the gh-pages branch, it needs to authenticate. You’ll need to generate new Public and Private keys. Don’t worry, these new keys won’t override your personal SSH keys.

In your Next.js 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.

Setup Deploy Key

In your Github repository:

  1. Go to Settings –> Deploy Keys
  2. Add Title: Public key of ACTIONS_DEPLOY_KEY
  3. Add Key: (copy and paste the public key)
  4. Check: Allow write access
  5. Click: Add key

Setup Private Key

In your Github repository:

  1. Go to Settings –> Secrets
  2. Add Click: Add a new secret
  3. Add Name: ACTIONS_DEPLOY_KEY
  4. Add Value: (copy and paste the private key)
  5. Click: Add key

Now Github Actions will be able to authenticate with your repository. You can safely delete the two keys from the Next.js app directory.

Github Actions

This is where the magic happens! The workflow file is running a few commands to automatically deploy the app when you push to the main branch.

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 are the Workflow steps:

  1. Check out main branch
  2. Setup Node LTS
  3. Get NPM’s cache from the last build 🚀
  4. Build the app
  5. Deploy the app to the /gh-pages branch (using a the ACTIONS_DEPLOY_KEY you generated earlier).

Here’s the workflow in .yml:

name: Deploy to Github Pages

on:
  push:
    branches:
      - main

  workflow_dispatch:

jobs:
  deployment:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 'lts/*'
          cache: 'npm'

      - name: Build
        run: |
          npm i
          npm run build
          npm run export

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          publish_dir: ./out

Activate 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!

In a moment, you should be able to see your Next.js app 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!

Start a discussion!

    Basic HTML tags such as <strong>, <em>, <pre>, <code> are allowed. Press enter twice to create a new paragraph.