How do I deploy a Next.js app to GitHub Pages using GitHub Actions?

[javascripter101]

🏷️ Discussion Type

Question

💬 Feature/Topic Area

Workflow Configuration

Discussion Details

I have a Next.js project and I want to host it for free on GitHub Pages. I tried just pushing my code but it doesn't work like a normal HTML site. I heard I need to configure something for static export and set up a GitHub Action to build and deploy it automatically on every push. Can someone walk me through the full setup? I'm pretty new to this stuff.

[Code-Crafter09]

You’re right — Next.js doesn’t work on GitHub Pages like a normal static HTML site because it’s designed for server-side rendering.

To deploy it on GitHub Pages, you need to use static export + GitHub Actions.

Here’s a complete step-by-step guide:

---

1. Enable Static Export in Next.js

Update your next.config.js:

const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true
  },
  basePath: '/your-repo-name',
  assetPrefix: '/your-repo-name/',
};

module.exports = nextConfig;

[andraokta]

Hello!

You are completely right—because Next.js is a React framework that usually relies on a Node.js server for rendering, it doesn't work out of the box when you just push the code to a static host like GitHub Pages.

You are already on the right track! You just need to tell Next.js to generate static HTML files, and then use GitHub Actions to automate the build and deployment process.

Here is a step-by-step guide to get your site live:

1. Configure Next.js for Static Export

First, you need to tell Next.js to output static files (.html, .css, .js) instead of running a server.

Open your next.config.js (or next.config.mjs) file at the root of your project and add output: 'export'. It should look something like this:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  // If you use next/image, you might also need to disable default image optimization:
  // images: { unoptimized: true },
};

module.exports = nextConfig;

Note: When you run a build with this setting, Next.js will create an out folder containing your static site.

2. Update your GitHub Repository Settings

Before adding the workflow file, you need to tell GitHub Pages to expect a deployment from GitHub Actions, rather than looking for an index.html file in your main branch.

1. Go to your repository on GitHub.
2. Click on the Settings tab.
3. On the left sidebar, click on Pages.
4. Under Build and deployment, look for the Source dropdown menu.
5. Change it from "Deploy from a branch" to GitHub Actions.

3. Create the GitHub Actions Workflow

Now, you need to create the automated script that will install your dependencies, build the static export, and deploy it every time you push to your main branch.

1. In the root of your project, create a new folder path: .github/workflows/
2. Inside that folder, create a file named deploy.yml (or anything you like, e.g., nextjs.yml).
3. Paste the following configuration into that file:

name: Deploy Next.js site to Pages

on:
  push:
    branches: ["main"] # Ensure this matches your default branch name
  workflow_dispatch: # Allows you to run this workflow manually from the Actions tab

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: "20" # You can change this to match your local Node version
          
      - name: Install dependencies
        run: npm ci # Use 'yarn install' or 'pnpm install' if you don't use npm
        
      - name: Build with Next.js
        run: npx next build
        
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./out # Next.js exports static files to the 'out' directory by default

  # Deployment job
  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. Push and Wait

1. Commit these changes (next.config.js and .github/workflows/deploy.yml) and push them to your repository.
2. Go to the Actions tab in your GitHub repository. You should see a workflow running.
3. Once it turns green, go back to your repository's Settings > Pages to find the live URL of your newly hosted Next.js site!

[javascripter101]

Thank you :)