Ken Schnall

Hosting a Next.js website with GitHub Pages

October 26, 2020

(Updated 2021-05-08 with build-export-windows command)

In this post I'll show you how to host a Next.js website with GitHub Pages. You'll need to have Git installed, a GitHub account, Node.js installed, and ideally you'll already have a Next.js project that you are looking to host.

1. Create the Next.js project repository
2. Create the GitHub Pages repository
3. Set up your Next.js project to compile to the GitHub Pages repository
4. Disable Jekyll processing in the GitHub Pages repository

Create the Next.js project repository

Create an empty Git repository. This repository will serve as the source of your Next.js website. Make sure it's empty, we'll make the first commit later.

An easy way to start a Next.js project is to use the project created in the Next.js website's learn section. Work your way through that section to learn how Next.js works, or skip to the end of that section to find a command you can run to create a Next.js project.

The final result of the learn section is the Next.js project at https://github.com/vercel/next-learn-starter/tree/master/demo. I highly recommend checking this repository to verify that this is still accurate.

Using a command found throughout the Next.js website's learn section, create the Next.js project using the link we just found. Read the notes just below before running this command.

• Run the command in the directory above your Git repository's directory
• Replace nextjs-blog with the name of your Git repository

Now your Next.js project is created and we can push the first commit to the project source repository. If you're using a GitHub repository for the source of your project, follow the instructions at the GitHub page for your repository to make the first commit. Push the first commit to the source repository.

Create the GitHub Pages repository

Now we need to create the repository for the compiled Next.js website, which will be the repository served by GitHub Pages. Create an empty GitHub repository with the name below.

kas.github.io

• Replace "kas" with your GitHub username

Now we need to compile your Next.js project, sending the output to the GitHub Pages repository that you just created. Then we'll use the output as the first commit to the GitHub Pages repository.

Set up your Next.js project to compile to the GitHub Pages repository

To send the Next.js project compilation output to the GitHub Pages repository, we'll create an npm script. This script needs to accomplish the following:

1. Remove files and folders that updates to the Next.js project would overwrite
2. Build the Next.js project
3. Export the Next.js project
4. Copy the output of the built Next.js project to the GitHub Pages repository

Edit the Next.js project's package.json file and add a script with the below content.

or

• Replace "kas" with your GitHub username
• If you're using the Windows command, I recommend unlinking OneDrive or disabling OneDrive for the repository folders

Now you can make changes to your Next.js project, run the "build-export" script, and the changes will be sent to your GitHub Pages repository. You'll still need to commit and push the changes in the GitHub Pages repository.

Disable Jekyll processing in the GitHub Pages repository

The last thing to do in the GitHub Pages repository is to include a file to disable Jekyll processing. GitHub Pages automatically processes files with Jekyll, which interferes with the _next directory. To unblock the _next directory from being included in the final website, add an empty .nojekyll file to the root of the GitHub Pages repository.

<- Back