Deploying a Next.js (App Router) Application to GitHub Pages
Tags: nextjs, javascript
Published: 2024-06-28 08:33:18

# 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.

{% youtube https://youtu.be/307GombOUXg?si=MIHgyMf64jjXJLg- %}

## 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:
   ```js
   module.exports = {
     output: 'export',
     basePath: '/your-repo-name',
     assetPrefix: '/your-repo-name/',

   }
   ```

2. **Update Scripts in `package.json`:**
   Modify your `package.json` to include the export script:
   ```json
   {
     "scripts": {
       "build": "next build",
       "export": "next export"
     }
   }
   ```

3. **Build and Export:**
   Run the following commands to build and export your application:
   ```bash
   npm run build
   npm run export
   ```

4. **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:
   ```yaml
   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
   ```

3. **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:
   ```yaml
   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 'your-email@example.com'
             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.