Next.js and GitHub Pages, how the basePath and assetPrefix configuration options will fix your website

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.

I demonstrated the difference between these two methods in-depth in a previous blog where I hosted a Next.js site on GitHub Pages.

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:

1. All the links are directed at / rather than your repository subpath.
2. 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:

1. In your Next.js application create a next.config.js file.
2. Get the name of your GitHub repository.
3. Add the following code to your next.config.js file, replacing repository 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!

Comments

[jintao-wang]

I have set it up like this, but I still can’t access the pictures.

[James Wallis]

Hi, do you have a link to a GitHub repo that I can take a look at? Are the images located in the public folder + have you added the assetPrefix? Thanks.