This is a cross-post from my Medium

Recently, I’ve decided to finally create my homepage. For this task I decided to go with Next.js and it’s amazing static export functionality. Without thinking twice I also decided to use github pages, since the fact that I’ll github. And I was like: “It should be plain and simple, just export the app into the docs folder (with the next build and next export -o docs) and you’re done”. Those, who are already giggling, are actually right, because it turned out to be not a piece of a cake.

First of all we have this guide (which actually missed some crucial information, which I’ve added, but it’s better to proceed reading the post). The first important part is .nojekyll file, because Jekyll ignores folders, that starts with underscores and we have _next. So you should add empty file called .nojekyll in your docs folder. Don’t worry, it won’t be deleted upon next export. You also have an option to use gh-pages branch (there is a cool git feature called subtree for it, see here). So it should be ok, right?…

First problem

If it isn’t your personal or organization page, your github page will be published under http://{username}.github.io/{reponame}. That means that by default links to the scripts will be broken. But no worries, next.js has an option to fix it, it’s called assetPrefix. The catch is that you don’t wanna clear the assetPrefix for local development, so it’s better to rely on process.env.NODE_ENV, or whatever you use to distinguish dev from prod.

And we proceed to the next one

You’ve updated to paths to static files, but what about links? We should also add prefix to them. The easiest way to pass the prefix to the components and pages would be using webpack.DefinePlugin and webpack config function (Next.js version ≥ 5).

Next.js also have an option to use env-config.js, but I don’t see the point of splitting the one concern into two files.

And then we use it like this. Important part is that we don’t simply prefixing it to the href, but using as prop. Otherwise this won’t be a client-side navigation, but full page reload. I wonder what‘s the reasons of this (see this thread for more information).

You could also create a simple wrapper for it.

Bonus problem

If you’re using Next.js v5 universal webpack configuration features, like withCss decorator that allows you to use old-style css approach (plain css, css-modules, sass, less, post-css) that creates separate file, you may want to use _document.js file to fine-tune the template that Next.js will be using to render your page. But in case of assetPrefix you may also want to alter the url for this script. Fortunately you can get the assetPrefix from props (this.props.__NEXT_DATA__.assetPrefix), like this.

Thank you for the attention, hope you won’t be facing another bunch of whatever problems soon!