Next.js app on Github Pages
Tags: nextjs, javascript, githubpages
Published: 2018-02-20 18:37:52

---
title: Next.js app on Github Pages
published: true
description: Cathes and gotchas while trying to deploy Next.js static exported application to Github Pages
tags: next.js, javascript, github pages
---
![Next.js + Github Pages](https://cdn-images-1.medium.com/max/800/1*NZ7KxwBB1NSuVsJP4FeMnQ.jpeg)

> This is a cross-post from [my Medium](https://medium.com/@saitonakamura/next-js-app-on-github-pages-768020f2b65e)

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](https://github.com/zeit/next.js/#static-html-export). 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](https://github.com/zeit/next.js/wiki/Deploying-a-Next.js-app-into-GitHub-Pages) (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](https://gist.github.com/cobyism/4730490)). So it should be ok, right?…

![Cuphead Cagney Carnation boss](https://cdn-images-1.medium.com/max/800/1*w0IMUgxXUqA-Nutq6VLU2g.jpeg)

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

{% gist https://gist.github.com/saitonakamura/c34f13740532ddeb1dbeb66ca151368f %}

![Cuphead Cala Maria boss](https://cdn-images-1.medium.com/max/800/1*YAeOvAWO34gc2u6HNXad-A.jpeg)

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

{% gist https://gist.github.com/saitonakamura/643d6f7c4b02f56f5dd962e0d38eaaa5 %}

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](https://github.com/zeit/next.js/issues/3335#issuecomment-348802894) for more information).

{% gist https://gist.github.com/saitonakamura/acc250e15900f14cc32818ab17e53374 %}

You could also create a simple wrapper for it.

{% gist https://gist.github.com/saitonakamura/3b9e6b3c0024dcdc7fa691268ef18a79 %}

![Cuphead Devil boss](https://cdn-images-1.medium.com/max/800/1*Rwxavy5zVS8Qm30hkbSoGw.jpeg)

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

{% gist https://gist.github.com/saitonakamura/890dc276f97f798c41f7c52bb104c059 %}

![Cuphead "thank you" screen](https://cdn-images-1.medium.com/max/800/1*aMjZLxnhwjYnn1v-DYJk7A.png)

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