Skip to content
BSWEN
Blog

How to Deploy a Next.js Website to GitHub Pages for Free

Cowrie
Cowrie
Dev @ Bswen

GitHub Pages deployment settings

I just finished building my first Next.js portfolio project and wanted to put it online. I tried Vercel but wanted to explore free alternatives. That’s when I discovered GitHub Pages—it’s free, it supports static sites, and I already have a GitHub account. Perfect.

But then I hit the first wall: GitHub Pages settings showed confusing options. Do I deploy from a branch? Do I need GitHub Actions? Which workflow should I pick?

Here’s what I learned through trial and error.

The Two Deployment Methods

After several attempts, I figured out there are two ways to deploy Next.js to GitHub Pages:

Method 1: Deploy from a branch—simple, good for pre-built static exports Method 2: GitHub Actions workflow—automated build process, better for full Next.js apps

Let me walk you through both.

Method 1: Branch Deployment (The Simple Way)

This works if your project builds as static HTML. I tried this first.

Configure Next.js for static export first:

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: { unoptimized: true },
  basePath: '/your-repo-name',
  assetPrefix: '/your-repo-name',
}
module.exports = nextConfig

Then update the build script:

package.json
{
  "scripts": {
    "build": "next build",
    "export": "next build && next export"
  }
}

After building, push your code and go to Settings → Pages. Under “Build and deployment”, select “Deploy from a branch”. Choose main branch and / (root) folder. Save.

Wait 2-3 minutes. Your site should appear at https://yourusername.github.io/your-repo-name/.

Method 2: GitHub Actions (The Better Way)

I hit issues with Method 1—images broke, routing was weird. GitHub Actions solved this by handling the full build process automatically.

GitHub will suggest a workflow when you first enable Pages. Or create one yourself:

.github/workflows/deploy.yml
name: Deploy Next.js site to Pages


on:
  push:
    branches: ["main"]


permissions:
  contents: read
  pages: write
  id-token: write


jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run build


  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

You also need to configure Next.js for static export since GitHub Pages is a static host:

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: { unoptimized: true },
}
module.exports = nextConfig

Push this to your repository. Go to Settings → Pages → Build and deployment → Select “GitHub Actions” as the source.

The Actions tab will show the build running. Wait for it to complete. Your site is now live.

Common Issues I Encountered

Here’s where I got stuck:

Issue 1: 404 errors after deployment The base path wasn’t configured. If deploying to username.github.io/repo-name, you need basePath: '/repo-name' in next.config.js. But with GitHub Actions, it handles this automatically.

Issue 2: Images not loading Next.js uses image optimization on-the-fly. GitHub Pages doesn’t support this. Set images: { unoptimized: true } in config.

Issue 3: Actions failing with permission errors The workflow needs proper permissions. Check the permissions section in the YAML—id-token: write and pages: write are required for Pages deployment.

Issue 4: Private repository confusion I thought my private repo meant my site would be private. Not true. GitHub Pages sites are public regardless of repository visibility. Your code stays private, but the deployed site is accessible to anyone.

Why GitHub Pages Matters

For students, hobbyists, and anyone building portfolios, free hosting removes a massive barrier. No monthly fees, no credit card required. Just push code and it’s live.

GitHub Pages also integrates with your existing workflow. You’re already version-controlling your code—why not deploy from the same place?

What’s Next

Start with the GitHub Pages beginner tutorial. Fork the sample repository and practice deploying it. Once you’re comfortable, try your own Next.js project.

For more complex apps with SSR or API routes, you’ll need a different host—GitHub Pages only serves static content. But for portfolios, docs, and marketing sites, it’s perfect.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: