Next.js and GitHub Pages, how the basePath and assetPrefix configuration options will fix your website
Tags: react, javascript, nextjs, webdev
Published: 2020-08-13 16:48:53

**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](https://nextjs.org/blog/next-9-5#customizable-base-path) 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`.
```javascript
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.](https://dev.to/jameswallis/deploying-a-next-js-app-to-github-pages-24pn)

## 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.

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