Next.js GitHub Pages

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 are 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/' : ''
}

3. Save the next.config.js
4. 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 set up 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’ll 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/[email protected]

      - name: Setup Node
        uses: actions/[email protected]
        with:
          node-version: 'lts/*'
          cache: 'npm'

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

      - name: Deploy
        uses: peaceiris/[email protected]
        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 something wrong, please file an issue. Good luck!