tl;dr: When hosting a Next.js project on GitHub Pages (without a custom domain name) your internal links won't work as your project will be hosted on a subpath (e.g. https://user.github.io/repository
). The basePath
configuration property will fix this. Combine it with assetPrefix
which fixes the paths for images and CSS stylesheets.
Preface
Next.js 9.5 contains a few really good enhancements to the React.js framework. Included in it is the new basePath
configuration variable for the next.config.js
file.
What is it?
The basePath
configurator allows you to serve your website pages under a subpath with no complex configuration. For example, if you're hosting docs you might want them to be at example.com/docs
rather than example.com
. In addition to this, Next.js will automatically prefix any <Link>
components to the basePath
.
To use a custom basePath
all you need to do is add the following to your next.config.js
.
module.exports = {
basePath: '/docs'
}
Once thats added, all your content will be available on /docs
without changing any of your <Link>
's to other pages. Neat.
Why is it awesome?
Usually you'll find a website available on it's root path (example.com/
) but some free hosting platforms allow you to host using their domain but on a path.
GitHub Pages is one such platform.
When you host a static website on GitHub Pages (without a custom domain) you will be allocated a domain specific to GitHub Pages in the format user.github.io
. For me this is james-wallis.github.io
. You will also be allocated a subpath on a per repository basis. This means the final address for the website will be user.github.io/repository
.
Previous to the basePath
variable, to host a Next.js static website on GitHub Pages you were required to manually prefix each <Link>
with the subpath, this required extra configuration and meant that if you forgot to add it on a single link, user's would be sent to the 404
page.
Using basePath
we can now simply add it to the next.config.js
file and set its value to whatever your repository is with 0 other configuration around your codebase. Simple.
Ok cool, give me an example...
So you have a Next.js application, works great on your machine and you want to launch it through GitHub Pages. You create a GitHub action or Travis job to run the next build
and next export
to turn your application into a static website and you push your website to GitHub expecting to see it available at your GitHub Pages URL but:
- All the links are directed at
/
rather than yourrepository
subpath. - The page has no styling, the CSS is pointing to the wrong path.
To solve these you need to add basePath
and assetPrefix
to your next.config.js
file.
assetPrefix
does the same as basePath
but for static assets such as CSS files and images.
Steps:
- In your Next.js application create a
next.config.js
file. - Get the name of your GitHub repository.
- Add the following code to your
next.config.js
file, replacingrepository
with the name of your GitHub repository.
module.exports = {
basePath: '/repository',
assetPrefix: '/repository/', // assetPrefix requires the trailing slash
}
And that's it, push those changes to your GitHub and once your static Next.js website is rebuilt using next build
and next export
it will work as you intended it to in the first place.
Thanks for reading!