Deploying Next.js to Github Pages
Tags: nextjs, github
Published: 2022-08-02 16:53:00

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](https://nextjs.org/docs/advanced-features/static-html-export#unsupported-features))

(by the way, I learned all of this by looking at the [official Next.js example](https://github.com/vercel/next.js/tree/canary/examples/github-pages) 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

```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`