Deploying a Next.js app into GitHub Pages

Tim Neutkens edited this page Jul 22, 2018 · 7 revisions

Add a .nojekyll file

To deploy a static site exported with next export onto GitHub Pages, you'll need to add an empty file called .nojekyll to your out directory.

This is because GitHub Pages will by default ignore any files and folders prefixed by an underscore (like _next), as documented here:

Extra step for Project Page sites

If your github page is a "Project Pages site" (rather than a "User and Organization Pages site"), you will need to perform the following step. (You know it's a "Project Pages site" if your URL looks like https://{username}{reponame}. See this description for information about Project vs User & Organization Pages).

The extra step is to set a configuration in next.config.js. If you don't yet have that configuration file, you'll need to create it in the root of your project directory (next to package.json), as described here.

You will set assetPrefix in next.config.js to the name of repository like this:

module.exports = {
  // some configuration
  assetPrefix: process.env.NODE_ENV === 'production' ? '/{reponame}' : '',
  // another configuration

Alter link URLs

You will also want to alter link URLs, because otherwise it will lead to 404. See this discussion:

Pushing to GitHub Pages from a Subdirectory

For more info on pushing to a gh-pages branch with a certain directory (like the default out directory), see here:

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.