Deploy @nx/next App to GitHub Pages

Context

Setting up GitHub Pages deployment for an Nx-based Next.js application requires specific configuration for static export and proper subpath handling.

Requirements

Configure Next.js app for static export
Set up GitHub Actions workflow for automated deployment
Configure GitHub Pages settings
Add local preview capability

Implementation Steps

1. Update next.config.js

Configure the Next.js app for static export with proper GitHub Pages paths:

//@ts-check
// eslint-disable-next-line @typescript-eslint/no-var-requires
const { composePlugins, withNx } = require('@nx/next');

/**
 * @type {import('@nx/next/plugins/with-nx').WithNxOptions}
 **/
const nextConfig = {
  output: 'export',
  basePath: '/portfolio',
  assetPrefix: '/portfolio',
  distDir: '/portfolio'
}
const plugins = [
  // Add more Next.js plugins to this list if needed.
  withNx,
];
module.exports = composePlugins(...plugins)(nextConfig);

2. Update .gitignore

Add the build output directory to ignore:

/portfolio

3. Create GitHub Actions Workflow

Create .github/workflows/deploy.yml:

name: Deploy Next.js site to Pages

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Setup Pages
        id: setup_pages
        uses: actions/configure-pages@v5

      - name: Restore cache
        uses: actions/cache@v4
        with:
          path: |
            apps/portfolio/.next/cache
          key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
          restore-keys: |
            ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-

      - name: Build with Next.js
        run: npx nx build portfolio

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./apps/portfolio/portfolio

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

4. Add Local Serve Target

Update project.json to add local preview capability:

{
  "targets": {
    "serve": {
      "command": "npx http-server .",
      "options": {
        "cwd": "{projectRoot}"
      },
      "dependsOn": ["build"],
      "continuous": true
    }
  }
}

5. Configure GitHub Pages

In repository settings:

Go to Settings > Pages
Select "GitHub Actions" as source

Usage

Push to main branch triggers automatic deployment
Run nx serve <app> for local preview at http://127.0.0.1:8080/<basename>/
Run nx dev <app> for development at http://localhost:3000/<basename>

Result

Automated deployment to GitHub Pages on every push
Site available at https://username.github.io/reponame/
Local preview capability for testing static export

Key Configuration Points

output: 'export' enables static export
basePath and assetPrefix handle GitHub Pages subpath
distDir specifies build output location
Workflow uploads from correct artifact path

xiongemi/deploy-nx-next-app-to-github-pages.md