Nextra Github Pages

Deploy Nextra Doc Site to Github Pages with Github Actions, Same like a native Next.js app. Forked from https://github.com/gregrickaby/nextjs-github-pages.

Configure Next.js

In order to get assets to display correctly, you'll need to prefix the assets directory. Additionally, you'll need to disable automatic image optimization since dynamic features don't work when using next export.

Create next.config.js file
Add the following:

// next.config.js
const isProd = process.env.NODE_ENV === 'production'

module.exports = {
  assetPrefix: isProd ? '/your-github-repo-name/' : '',
  images: {
    unoptimized: true,
  },
}

Save the next.config.js
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 will be disabled. Learn more

Configure Github Repository

Next you need to configure Github for automated deployments via Github Actions.

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 ""

Open the keys in your code editor, because in a minute, you're going to copy and paste the contents into your Github repository settings.

Setup Deploy Key

In your Github repository:

Go to Settings --> Deploy Keys
Add Title: Public key of ACTIONS_DEPLOY_KEY
Add Key: (paste the public key)
Check: Allow write access
Click: Add key

Setup Private Key

In your Github repository:

Go to Settings --> Secrets --> Actions
Add Click: Add a new secret
Add Name: ACTIONS_DEPLOY_KEY
Add Value: (paste the private key)
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.

Setup 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:

Check out main branch
Setup Node
Get NPM's cache from the last build 🚀
Build the app
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/

42arch/nextra-github-pages