GitHub Pages Deployment of Next.js Static Sites: JS/CSS 404 Errors and Solutions

Issue Check & Solutions

After deploying a Next.js static export (SSG) to GitHub Pages, you might encounter issues where JavaScript and CSS files fail to load correctly.

In your browser's developer tools network panel, you'll see a 404 error for the corresponding files.

If you try to open the URL of the problematic file directly in your browser, you'll likely see the default Next.js 404 page.

The .nojekyll File

First, check if the root directory of your GitHub Pages deployment is missing the .nojekyll file.

If it's missing, this is often the cause of the problem. A missing .nojekyll file will cause directories starting with an underscore (_), such as _next, to be ignored, leading to errors.

The .nojekyll file is an empty file placed in the root directory of your static site. It tells GitHub Pages to:

"Do not use the default Jekyll processing mechanism," especially don't ignore directories that start with an underscore _ (like Next.js's _next/ static resource directory).

❌ https://username.github.io/repo-name/_next/static/xxx.js → 404
✅ After adding .nojekyll, it can be accessed normally

basePath & assetPrefix

Next, you'll want to check the JavaScript and CSS paths referenced in your index.html to ensure they include your repository name as a subdirectory.

GitHub Pages supports three types of sites: project pages, user pages, and organization pages. Project pages are typically hosted at https://username.github.io/repo-name/. This means your resource paths need to include the repository name as a subdirectory.

For example, if your site is username.github.io/your-repository-name, you'll need to adjust your build tools and framework configurations. Otherwise, incorrect resource paths (missing the subdirectory) will lead to 404 errors.

For GitHub Pages deployments that use a subpath, like Next.js, the paths for static assets (such as JS and CSS files) must be modified. Here's the recommended approach:

Loading...

Let's break down basePath and assetPrefix:

• basePath: This modifies the prefix for your page routes. For example, a route like /about would become /tailwindcss-typography-demo/about.
• assetPrefix: This changes the prefix for your static asset paths, ensuring that resources in _next/ load correctly.

Here’s a comparison of how your site behaves with and without correct basePath and assetPrefix settings:

After recompiling and redeploying your site:

Finally, check all your hyperlinks. If you're using plain <a> tags, replace them with Next.js's Link component. Otherwise, they might not correctly handle the path prefix, which can lead to 404 errors.

import Link from "next/link"

Native HTML <a> tags don't automatically handle basePath, which can easily lead to path errors. We recommend consistently using the Link component provided by Next.js instead.

After performing the checks above, most issues should be resolved. If errors still persist, you'll need to verify that your static resource files have been uploaded to the repository.

Recommended Deployment Process

If you've been manually deploying your out directory to GitHub Pages, we recommend switching to an automated deployment tool.

These tools can automatically publish your built out directory to the gh-pages branch. This method offers a high degree of automation and is the most commonly used deployment approach within the community.

It publishes the contents of your out directory to a dedicated gh-pages branch for GitHub Pages, without affecting your main branch.

1. Install gh-pages

Loading...

2. Modify package.json, add a new deploy script in the scripts section.

"scripts": {
	"dev": "next dev --turbopack",
	"build": "next build",
	"start": "next start",
	"lint": "next lint",
	"deploy": "next build && gh-pages -d out --nojekyll"
},

• next build: First build to ensure the out directory is up to date;
• gh-pages -d out --nojekyll: Deploy the contents of the out directory to the gh-pages branch, ensuring the generation of a .nojekyll empty file to avoid affecting the _next static resource directories;

3. Run the deployment command

pnpm run deploy

This command will automatically create a gh-pages branch (if it doesn't exist) and push the files from the out directory to this branch, then publish to GitHub Pages.

After using this automated tool, you can complete the deployment without manually entering the GitHub repository's Settings → Pages page configuration.

Other: Why Choose GitHub Pages?

Some friends may wonder: "Next.js is Vercel's product, shouldn't it be deployed on Vercel?"

Indeed, Vercel is the preferred platform for deploying Next.js, with deep integration that supports advanced features like SSR, ISR, and dynamic API routing, providing an excellent deployment experience. However, this also means it relies on Vercel's runtime resources, such as the Node.js environment.

However, in the following scenarios, GitHub Pages is still a viable option:

• 🔹 You're exclusively using Next.js's static export (output: "export") feature and don't rely on runtime characteristics like SSR.
• 🔹 You're building purely frontend content such as tutorial demos, project documentation, or personal blogs.
• 🔹 You want to use GitHub's free static hosting resources instead of consuming Vercel's Hobby plan quota.
• 🔹 Your project is already hosted on GitHub, and deploying to Pages is a simpler, more controllable process.
• 🔹 You don't have high demands for traffic or performance; instead, you prioritize deployment maintainability and public transparency.

In summary, GitHub Pages is a lightweight alternative for deploying static sites, particularly suitable for projects with limited resources or pure front-end content.

FAQ

❓ How do I generate the .nojekyll file?

.nojekyll is an empty file used to prevent GitHub Pages from ignoring the _next/ directory. It can be manually created or generated through a deployment command:

Method 1: Command Line Creation

touch out/.nojekyll

Method 2: Automatically Add with gh-pages Tool

gh-pages -d out --nojekyll

References

tschaub gh-pages

Github Pages

Github Pages Documentation

Bypassing Jekyll on GitHub Pages