Next.js is a React framework that lets us build React web applications through a layer of automatic configuration abstraction. It pushes the React component paradigm towards a page-based structure, and is great for static and, through automatic static optimization, dynamic websites. It’s one of the fastest growing frameworks since its inception in 2016, and with good reason. It’s used by Hulu, TikTok, and Twitch, to name a few. Next.js is easy to get into using its own getting started guide, however in this post we’re interested in getting a Next.js website deployed to GitHub Pages. I’m going to share my lessons learned and what they don’t tell you about the deployment process. In the end, you’ll have a public website hosted for free by GitHub, and built with React and Next.js. Let’s go through the process step-by-step.
Step 1: The Next.js project
Follow the official Next.js getting started guide up until the point where you can run the build and view the compiled website locally. Then change the following:
1. Add this command to your package.json file:
"export": "next export"
2. Change the next.config.js file to next.config.mjs, and replace everything inside with the following:
/** * @type {import('next').NextConfig} */ const nextConfig = { images: { loader: 'akamai', path: '', }, assetPrefix: './', }; export default nextConfig;
The extension change is so that the compiler can understand exports, and the update we make inside the file solves a couple of problems:
Next.js uses its own image optimization, which doesn’t play nicely with GitHub Pages by default. We change this to the akamai option which works properly. You can read more about this here
We need to define an asset prefix because GitHub uses Jekyll by default to build static pages, and Jekyll ignores all files prefixed with "_" which Next.js uses
Step 2: GitHub Repository Setup
GitHub Pages is a great, free service that lets us publish static websites automatically and directly from our own repositories. I love using this service to get projects running in a “production” environment, which lets us get proof-of-concepts into the hands of users super fast.
Add a new branch with any name you want. I’m using the name “public” in this example. Then, go to your repository Settings, then Pages, then add the public branch as the source. Make sure the root folder is also selected, and then hit Save.
After this, your page will build, and GitHub will share the public URL that you will use to reach the site.
Step 3: GitHub Actions
Your website won’t show anything yet, because GitHub doesn’t know that your repository needs to be compiled. This can be handled automatically using GitHub actions, which has free continuous integration minutes we can leverage. We’re going to use a premade GitHub action from the marketplace that contains all the code needed to do this.
Create a workflows folder inside your .github folder, and inside this new folder create a .yml file. The name can be whatever you like.
Inside this file will be the commands that GitHub actions will run. You can copy my example here. Once you commit these files, the actions tab for your repository will show your action running. Actions are triggered automatically after any commits by default.
Once your action has finished building, you can navigate to the URL GitHub created for your repository. If everything worked, and the actions completed successfully, you’ll see a screen like this:
Congratulations! You’ve successfully deployed a Next.js web application to GitHub Pages! If you’d like to see a full project, you can check out an example repository I created with the absolute minimum files needed here.
If you want to see this repository’s deployment in action, you can visit the website here.
Want to talk about Next.js? I’d love to chat with you! You can meet me in the official Bravo LT Discord Server!
Written by David Crawford, Mobile App Developer
