Deploying Next.js to Github Pages

important: this will use next export so the Next.js server won't be running and you won't have things like API routes or catch-all routes in your regular pages (for more details see the docs)

(by the way, I learned all of this by looking at the official Next.js example for usage with github pages)

Ready? Let's go.

Update next.config.js

const nextConfig = {

  // ... you might have other stuff above here!
  // just add this basePath property
  basePath: 'REPOSITORY_NAME'
}

module.exports = nextConfig

Why?

By default when running next export, Next.js expects the root of your site to be <some_domain_name>.com/ but that's not (always) what happens with Github Pages. If you create a Project Site (which means you just have a random project on a random repo and you wanna enable github pages for it) then your URL will be: https://<your_github_username>.github.io/<name_of_repository>/ and we need to take into account that extra <name_of_repository>/ at the end by modifying basePath in the Next config.

HOWEVER, now when you run a dev server at http://localhost:3000/ you need to append that basePath there too! so if your repo is called 'awesome-app' and you change your basePath to be '/awesome-app' now you can access your app at http://localhost:3000/awesome-app

Though you have to skip this step in some cases:

for user and organization sites it will be https://<your_github_username>.github.io. and from what I understand (haven’t tried it) for both the project site and user/organization site you can set up custom domains but in any case you can skip this part because the root of your site is in accordance with the default basePath.

build and export

Run the following commands in order:

1. npx next build - build your app
2. npx next export - create static export of your app

if all goes well, you should see an ‘out’ folder inside of which are the files github is going to serve

add .nojekyll file to the out/ directory

to opt out of using jekyll (since you’re using next.js) with github pages you have to add a .nojekyll file to out/

command: touch out/.nojekyll

commit changes

run git add out/ -f then git commit -m "Deploy"
you need to add the -f option because git will complain about the out/ dir being in .gitignore

and one last (awesome) command

git subtree push --prefix out origin gh-pages
this will make a new branch called gh-pages on the remote repository origin (which is on github) and in this new branch it will have all the content inside of the out/ directory but they will all be in the root so that the files can easily be served by github from that branch.

make the workflow easy

you can add this "deploy" script to your package.json

  "scripts": {

    // ... you might have other scripts above and around!

    "deploy": "next build && next export && touch out/.nojekyll && git add out/ -f && git commit -m \"Deploy\" && git subtree push --prefix out origin gh-pages"

  },

and run it with the command npm run deploy or yarn deploy