Using GitHub Pages to Build, Deploy, and Host Next.js
A version of this article appeared on viget.com
Some Next.js details may be out of date
At the time of writing, Next.js was on v12.
Considering putting a Next.js site on GitHub Pages? It can be done, provided Next.js’s static export meets your needs. Netlify or Vercel are better choices for most people — like GitHub Pages they have free options, and unlike GitHub Pages they require almost no additional configuration to support Next.js. If you’re committed to GitHub Pages ecoystem, or if like me you just want to see what it takes, read on!
I took this on as part of my adventure Comparing Heroku, Netlify, Vercel, and GitHub Pages for Node.js Projects.
In this tutorial we’ll
- enable GitHub pages for a Next.js project’s repo
- set up a GitHub Actions workflow to automatically build, export, and deploy the static site whenever
- adjust Next.js’s options to fit with GitHub Actions URL structure
- and we’ll set up a personal Imgix image CDN to support
The final GitHub Actions workflow file and Next.js config are at the end.
GitHub Pages must be turned on on a per-repo basis. When turning it on you can choose which branch to serve. The convention is to serve the branch
- In a browser, go to the repo in GitHub.
- In Settings > Pages > Source, select the
gh-pagesbranch and click “Save”.
We’ll use a GitHub action to deploy the Next.js project to GitHub Pages. The following is a boilerplate GitHub Actions workflow based on examples from GitHub. It configures the workflow to run when the branch
main is pushed. It specifies a Node version, checks out
main, installs Node dependencies with cacheing. Next we’ll configure the build and an external GitHub Pages workflow. Note that this workflow use
npm ci (docs) as recommended by GitHub (ref). Save this to
GitHub pages only supports static sites, so we’ll use
next export (docs).
next export must be preceded by
Remember, not all Next.js features are supported in static builds.
next build && next export will export a static copy of the site to the top-level directory
out. Later, in the deploy step, we’ll duplicate
out as the root directory in the branch
gh-pages. But there’s a catch:
next export puts CSS and JS in
out/_next, and by default GitHub Pages ignores underscore-prefixed directories. The fix is to add a
.nojekyll file as a sibling of the
_next directory (GitHub Pages ignores underscore-prefixed directories by default because for historical reasons GitHub Pages gives special low-friction status to Jekyll and Jekyll ignores underscore-prefixed directories). Happily, creating that file programmatically takes no more than adding a
touch command to the workflow.
The build part of the above workflow file becomes
And set up the npm scripts
export as aliases to the
next commands. (The below
set-script commands are specific to
npm. If you use something else —
yarn, etc— define them manually in your package.json’s
We’ll offload the more involved work of deployment to a 3rd-party workflow. There are many workflows for deploying to GitHub Pages in the GitHub Marketplace (see for yourself). As of this writing, the most popular by far is JamesIves’s Deploy to GitHub Pages. A nice feature of this workflow is it does not require setting and using secret tokens. We simply configure it to deploy the directory
out to the branch
The deploy part of the above workflow file becomes
'next/router' expect paths to be relative to
/. GitHub Pages hosts sites at
https://<user or org>github.io/<repo> Next.js needs to be configured to expect that
There are two relevant configuration options:
basePath (docs) and
assetPrefix (docs). Setting
/<repo name> will result in GitHub Pages-friendly
Links. And setting
/<repo name> will result in GitHub Pages-friendly
Let’s apply this configuration only in the context of the GitHub Pages. We will use GitHub Actions to export a static copy of the site for GitHub Pages (details below), so we can take advantage of the environment variables GitHub automatically adds for us (docs).
true when GitHub Actions is running the process, and
next/image’s default “loader”, the function used to resolve image URLs, does not work when
exporting a static build. Next.js supports several image host services (ref). Imgix’s free plan is a good solution for Next.js on GitHub Pages. We’ll store images in the Next.js project repo and use Imgix for optimization and delivery.
Put images in
./publicor in a public subdirectory (for example
Add the image files and commit.
Push to GitHub.
Tell Next.js to load images from your Imgix source (docs).
Commit and push that.
- Create a free Imgix account
- Create a new “Source”
- For “Type” select “Web folder”
- For “Base URL” enter
https://<user or org>.github.io/<repo>(replace
<user or org>and
<repo>with the values for your Next.js project). If your images aren’t in the root directory, append to the path as necessary (e.g.
https://<user or org>.github.io/<repo>/path/to/images)
- Configure other settings to your liking, then save
You should now be able to view your images on Imgix. For example, if your repo has the file
profile.jpg, your Imgix domain is
https://me.imgix.net, and your Imgix base URL is
https://<user or org>.github.io/<repo>, view it at
https://me.imgix.net/profile.jpg. And next/image should find them too, both locally (requires an internet connection) and on GitHub Pages.
Our complete GitHub Actions workflow file is
and our complete Next.js configuration is
With that committed and pushed to GitHub, the Imgix CDN configured and running, and GitHub Pages enabled for the Next.js project’s GitHub repo, every push to the branch
main will deploy the Next.js app’s static export to GitHub Pages!