Deploying a Next.js (App Router) Application to GitHub Pages

Deploying a Next.js application with the App Router to GitHub Pages can be done using several methods. Here, we'll explore three effective ways to achieve this: using the next export command, leveraging GitHub Actions, and utilizing predefined workflows available on GitHub.

Method 1: Using next export

The next export command generates a static HTML version of your Next.js application, which can be served on any static hosting service like GitHub Pages. Here’s how you can do it:

1. Configure next.config.js: Ensure your next.config.js is set up for static export:

   module.exports = {
     output: 'export',
     basePath: '/your-repo-name',
     assetPrefix: '/your-repo-name/',

   }

1. Update Scripts in package.json: Modify your package.json to include the export script:

   {
     "scripts": {
       "build": "next build",
       "export": "next export"
     }
   }

1. Build and Export: Run the following commands to build and export your application:

   npm run build
   npm run export

1. Deploy to GitHub Pages: Move the contents of the out directory to the gh-pages branch and push it to GitHub. You can do this manually or automate it using a shell script.

Method 2: Using GitHub Actions

GitHub Actions can automate the deployment process. Here’s a simple workflow:

1. Create Workflow File:
   Create a file named deploy.yml in the .github/workflows/ directory.

2. Define the Workflow:
   Add the following configuration to your workflow file:
   

   name: Deploy Next.js App to GitHub Pages

   on:
     push:
       branches:
         - main

   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v2
         - uses: actions/setup-node@v2
           with:
             node-version: 14
         - run: npm install
         - run: npm run build
         - run: npm run export
         - name: Deploy to GitHub Pages
           uses: peaceiris/actions-gh-pages@v3
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
             publish_dir: ./out

1. Commit and Push: Commit the workflow file and push it to your repository. GitHub Actions will handle the rest.

Method 3: Using Predefined Workflows

There are predefined GitHub Actions available that can simplify the deployment process. For example, the Next Pages action by anorcle automatically handles exporting and deploying Next.js applications to GitHub Pages.

1. Install Next Pages Action: Add the Next Pages action to your workflow:

   name: Deploy Next.js to GitHub Pages

   on:
     push:
       branches:
         - main

   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v2
         - uses: actions/setup-node@v2
           with:
             node-version: 14
         - run: npm install
         - run: npm run build
         - name: Next Pages
           uses: anorcle/next-pages@v1.0
         - name: Commit and Push
           run: |
             git config --global user.name 'your-username'
             git config --global user.email '[e-mail]'
             git add -A
             git commit -m 'Deploy to GitHub Pages'
             git push

This action automates the renaming of directories and files that start with an underscore, which GitHub Pages does not support, making the deployment process seamless【12†source】【13†source】【14†source】.

These methods provide flexibility and automation for deploying your Next.js application to GitHub Pages, ensuring your deployment process is efficient and straightforward.