How to Deploy a Next.js Subfolder to GitHub Pages
When working on a project with a multi-repo structure, such as in my Attachment Lyrics Matcher, you might encounter challenges deploying the Next.js frontend to GitHub Pages.
For instance, your project structure might look like this:
project
│ README.md
└───backend
│ │ ...
└───frontend
│ package.json
| ...
Deploying the frontend
folder to GitHub Pages doesn’t work out of the box. However, with the steps below, you’ll have it up and running in no time.
Step 1: Adjust Your next.config.ts
The next.config.ts
file needs to specify the correct basePath
for GitHub Pages, but only when in production mode.
- Replace
<YOUR_REPO_NAME>
with the name of your GitHub repository. - The
basePath
is only required in production. During development, this should remain unset to avoid issues.
// next.config.ts
import type { NextConfig } from "next";
const isProduction = process.env.NODE_ENV === "production";
const nextConfig: NextConfig = {
basePath: isProduction ? "/<YOUR_REPO_NAME>" : "",
output: "export",
};
export default nextConfig;
Step 2: Configure GitHub Actions
To deploy your Next.js frontend using GitHub Actions, the key is setting the correct working-directory
.
Other configurations here account for using pnpm.
If you use npm or yarn instead, refer to the default GitHub Action YAML for their configurations.
# .github/workflows/nextjs.yaml
name: Deploy Frontend
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
strategy:
matrix:
node-version: [20]
defaults:
run:
working-directory: <NAME_OF_SUBFOLDER> # Set working directory to subfolder
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Detect package manager
id: detect-package-manager
run: |
if [ -f "pnpm-lock.yaml" ]; then
echo "manager=pnpm" >> $GITHUB_OUTPUT
echo "command=install" >> $GITHUB_OUTPUT
echo "runner=pnpm" >> $GITHUB_OUTPUT
exit 0
else
echo "Unable to determine package manager"
exit 1
fi
- name: Install pnpm
uses: pnpm/action-setup@v4
with:
version: 9
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
cache-dependency-path: frontend/pnpm-lock.yaml
node-version: ${{ matrix.node-version }}
cache: "pnpm"
- name: Setup Pages
uses: actions/configure-pages@v5
with:
static_site_generator: next
- name: Restore cache
uses: actions/cache@v4
with:
path: .next/cache
key: ${{ runner.os }}-nextjs-${{ hashFiles('pnpm-lock.yaml', 'yarn.lock', 'package-lock.json') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
restore-keys: |
${{ runner.os }}-nextjs-${{ hashFiles('pnpm-lock.yaml', 'yarn.lock', 'package-lock.json') }}-
- name: Install dependencies
run: pnpm install
- name: Build with Next.js
run: pnpm run build
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: frontend/out
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
That’s It!
After completing these steps, your Next.js project should successfully deploy to GitHub Pages.