How to Deploy Your Next.js Website on GitHub Pages Like a Pro!

Are you building an awesome Next.js website and wondering how to get it live on GitHub Pages? You’re in the right place! In this guide, I'll show you step-by-step how to deploy your Next.js project to GitHub Pages effortlessly. 🚀

Why Deploy on GitHub Pages?

GitHub Pages is a fantastic (and free!) way to host your static websites directly from your GitHub repository. If you have a portfolio, documentation, or any static Next.js site, GitHub Pages is a great hosting option.

Prerequisites

Before we dive in, make sure you have: ✅ A Next.js project set up ✅ A GitHub account ✅ Node.js installed on your machine

Step 1: Configure next.config.js

By default, Next.js generates dynamic server-side pages. However, GitHub Pages only supports static sites, so we need to tweak our Next.js config to export static files.

Edit your next.config.js to include:

const isProd = process.env.NODE_ENV === "production";

module.exports = {
  output: "export",
  basePath: isProd ? "/your-repo-name" : "",
  images: { unoptimized: true },
};

What’s happening here?

• output: 'export' tells Next.js to generate static files.
• basePath ensures correct routing for GitHub Pages.
• images.unoptimized: true is necessary if you’re using Next.js Image Optimization, which doesn’t work with static exports.

Step 2: Add a GitHub Actions Workflow (Optional but Recommended)

Automation is key! We’ll use GitHub Actions to deploy our site automatically.

1️⃣ Create a .github/workflows/deploy.yml file in your project. 2️⃣ Add the following code:

name: Deploy to GitHub Pages
on:
  push:
    branches:
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Install dependencies
        run: npm install
      - name: Build and export
        run: npm run build && npm run export
      - name: Deploy to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          branch: gh-pages
          folder: out

Step 3: Add a Deployment Script to package.json

Modify package.json to include a script for exporting your static site:

"scripts": {
  "export": "next build && next export",
  "deploy": "gh-pages -d out"
}

Step 4: Push to GitHub and Deploy 🚀

1. Initialize a Git repository (if you haven’t already):

   git init
   git remote add origin https://github.com/your-username/your-repo-name.git
   

2. Commit and push your changes:

   git add .
   git commit -m "Deploy Next.js to GitHub Pages"
   git push origin main
   

3. If you set up GitHub Actions, it will handle the deployment for you. Otherwise, run:

   npm run export
   npm run deploy
   

Step 5: Enable GitHub Pages

1. Go to your repository on GitHub.
2. Navigate to Settings > Pages.
3. Select gh-pages as the branch.
4. Save the changes, and your site should be live at https://your-username.github.io/your-repo-name/! 🎉

Bonus: Custom Domain (Optional)

Want a personalized domain? No problem!

1. In your repo, create a CNAME file inside the public/ folder.
2. Add your custom domain inside the CNAME file (e.g., mywebsite.com).
3. Configure your domain's DNS settings to point to your-username.github.io.

Conclusion

That’s it! You’ve successfully deployed your Next.js site to GitHub Pages. Now, every time you push to the main branch, your site will automatically update. 💯