# Next.js Static Export Shows a Blank or Unstyled Page — out/, basePath and _next

Canonical: https://commareports.com/fix/nextjs-static-export-blank-page
Published: 2026-11-20

> `next dev` works, but the `output: 'export'` build in out/ is blank, unstyled or 404s. The cause behind each symptom — absolute /_next paths on file://, GitHub Pages and the _next folder, basePath, trailingSlash, 'Application error: a client-side exception' — and the fix for each.

# Next.js static export shows a blank or unstyled page

`next dev` works. `next build` with `output: 'export'` finishes and writes
`out/`. Then the exported site is a white screen, plain unstyled text, or a
page whose links all 404.

A static export fails differently from a single-page app. Next prerenders
every page to HTML, so you usually see _something_: the text without its CSS.
A fully blank page means the content is rendered only on the client, and the
JavaScript never ran. Open the console (F12 → Console) and the Network tab
before you change anything. For other frameworks see
[Vite](/fix/vite-build-blank-page), [React](/fix/react-build-blank-page) and
[Angular](/fix/angular-build-blank-page).

## Match the symptom to the cause

| What you see                                                 | Cause                                      | Section                     |
| ------------------------------------------------------------ | ------------------------------------------ | --------------------------- |
| Unstyled text, `ERR_FILE_NOT_FOUND` for `/_next/static/…`    | Opened `out/index.html` from disk          | Opened from disk            |
| Unstyled on GitHub Pages, `404` for every `/_next/…` file    | Jekyll skipped `_next`, or no `basePath`   | GitHub Pages                |
| Styled home page, broken images or fonts below `/repo/`      | Hardcoded `/` paths ignore `basePath`      | GitHub Pages                |
| `/about` 404s on refresh or a direct link                    | `about.html` without `trailingSlash`       | Refresh and deep links 404  |
| `Uncaught SyntaxError: Unexpected token '<'`                 | A chunk request got `index.html` back      | Unexpected token and chunks |
| `ChunkLoadError: Loading chunk … failed` after a deploy      | Cached HTML points at deleted chunks       | Unexpected token and chunks |
| `Application error: a client-side exception has occurred`    | A component threw in the browser           | Application error           |
| Build error: `next export` has been removed                  | Next 14 dropped the command                | Build errors on export      |
| Build error: missing `generateStaticParams()`                | Dynamic route with no list of pages        | Build errors on export      |
| Build error: Image Optimization … not compatible with export | `next/image` default loader needs a server | Build errors on export      |

## You opened out/index.html from disk

Look at the source of any exported page:

```html
<link rel="stylesheet" href="/_next/static/css/a1b2c3.css" />
<script src="/_next/static/chunks/main-app-d4e5f6.js" async></script>
```

On a web server `/_next/` is under the site root. On a `file:///` page it is
under the root of your disk, so every stylesheet and chunk fails. Links have
the same problem: `<Link href="/about">` points at `file:///about`.

There is no supported relative mode. `assetPrefix: "./"` is a common
workaround, but it only holds for top-level pages and breaks on nested routes
and client-side navigation. Serve the folder over HTTP instead:

```bash
npx serve out
```

## GitHub Pages: \_next 404s and the basePath

Two separate things break a Next export on GitHub Pages.

**Jekyll eats `_next`.** When Pages publishes from a branch it runs Jekyll,
and Jekyll skips every file and folder that starts with `_`. The HTML is
published; `_next/` is not. Add an empty `.nojekyll` file to `public/` so the
build copies it into `out/`:

```bash
touch public/.nojekyll
```

Deploying with the `actions/deploy-pages` workflow skips Jekyll, so this only
bites branch deploys.

**A project site lives below the root.** `https://user.github.io/repo/` asks
for `https://user.github.io/_next/…` and gets a 404. Set the base path:

```js
// next.config.js
module.exports = {
  output: "export",
  basePath: "/repo",
  images: { unoptimized: true },
};
```

No trailing slash on `basePath`. It prefixes routes, `<Link>` targets and the
`_next` assets. It does **not** prefix paths you wrote by hand:

| Written as                    | With `basePath: "/repo"` it requests | Fix                                      |
| ----------------------------- | ------------------------------------ | ---------------------------------------- |
| `<img src="/logo.png">`       | `/logo.png` (404)                    | `src={base + "/logo.png"}`               |
| `<Image src="/logo.png" …>`   | `/logo.png` (404)                    | Static import, or prefix the string      |
| CSS `url(/fonts/inter.woff2)` | `/fonts/inter.woff2` (404)           | Relative `url(../fonts/…)` or prefix     |
| `fetch("/data.json")`         | `/data.json` (404)                   | Prefix, or import the JSON at build time |

Keep the prefix in one place, for example
`const base = process.env.NEXT_PUBLIC_BASE_PATH ?? ""`, and set it alongside
`basePath`. With a custom domain the site is at `/` again, so remove
`basePath` or every asset 404s.

`assetPrefix` is for serving `_next/` from another host, such as a CDN. You
don't need it for GitHub Pages.

## Refresh and deep links 404

The home page loads and client-side navigation works, but refreshing
`/about` or opening it from a link returns 404.

By default the export writes one file per route:

```
out/
├── index.html
├── about.html
└── blog/
    └── first-post.html
```

GitHub Pages and Netlify serve `about.html` for `/about`. S3, nginx, Apache
and most CDNs look for a file or folder called `about` and find neither.
The portable fix is one line:

```js
module.exports = { output: "export", trailingSlash: true };
```

Now the export writes `about/index.html`, which every static host serves for
`/about/`. If you'd rather keep the flat files, tell the server to try them:

| Host          | Serve `about.html` for `/about`                           |
| ------------- | --------------------------------------------------------- |
| nginx         | `try_files $uri $uri.html $uri/ =404;`                    |
| Apache        | `RewriteCond %{REQUEST_FILENAME}.html -f` + `RewriteRule` |
| Firebase      | `"cleanUrls": true` in `firebase.json`                    |
| S3/CloudFront | `trailingSlash: true` (S3 has no extension fallback)      |

Don't add a catch-all rewrite to `index.html` here. An export has a real HTML
file per route, and a catch-all hides missing files behind a 200 (see the next
section). Dynamic segments only exist if `generateStaticParams()` listed them,
so `/blog/new-post` 404s until you rebuild.

## Unexpected token '<' and ChunkLoadError

```
Uncaught SyntaxError: Unexpected token '<'
```

The browser asked for a `.js` chunk and got an HTML page back. Hosts set up
for single-page apps answer any missing path with `index.html` and a 200, so a
wrong path never shows as a 404. Check the Network tab for the chunk: if its
response is HTML, the path is wrong (the `basePath` cases above) or the file
wasn't deployed (the Jekyll case).

```
ChunkLoadError: Loading chunk 123 failed.
```

This one appears right after a deploy. A CDN or the browser cached the old
HTML, which references hashed chunks the new build deleted. Hard-reload
(Ctrl+Shift+R) to confirm, then serve HTML with `Cache-Control: no-cache` and
`_next/static/` with a long immutable cache. Delete old chunks a deploy or two
later, not at once, if visitors keep tabs open.

## Application error: a client-side exception has occurred

Production Next replaces the page with this one line when a component throws
in the browser. The real error is in the console. On a static export it is
usually one of these:

- **Browser APIs during render.** `window`, `localStorage` or `document` read
  at the top of a component throws during prerender or hydration. Read them
  in `useEffect`, or load the component with
  `dynamic(() => import("./Chart"), { ssr: false })`.
- **An empty `NEXT_PUBLIC_` variable.** These are inlined at build time, so a
  variable set only on the host is `undefined` in the export, and the first
  `new URL(process.env.NEXT_PUBLIC_API_URL)` throws. Set it in the build
  environment. Variables without the prefix never reach the browser at all.
- **Server features that aren't in the export.** API routes, middleware,
  `rewrites`, `redirects`, `headers`, Server Actions, ISR and `cookies()` all
  need a running server. A `fetch("/api/…")` returns 404 or the host's HTML,
  and the JSON parse throws. Move the call to an external API, or fetch at
  build time in a Server Component.
- **Hydration mismatch.** Dates, random IDs or `typeof window` branches that
  render differently on the server and in the browser. React logs the mismatch
  and re-renders on the client; an error thrown during that re-render blanks
  the page.

Rebuild with source maps (`productionBrowserSourceMaps: true`) to see the real
file and line instead of minified chunk names.

## Build errors on export

The export refuses to build rather than shipping a broken page in these cases:

- **`next export` has been removed.** Next.js 14 dropped the command. Set
  `output: "export"` in `next.config.js`, run `next build`, and read the site
  from `out/`. Delete the `next export` step from your scripts and CI.
- **Missing `generateStaticParams()`.** A dynamic route such as
  `app/blog/[slug]/page.tsx` must list every slug at build time. Return the
  full list from `generateStaticParams()`. In the Pages Router the equivalent
  is `getStaticPaths` with `fallback: false`.
- **Image Optimization isn't compatible with export.** The default
  `next/image` loader resizes on a server. Set `images: { unoptimized: true }`,
  or configure a custom loader that points at an image CDN.
- **`useSearchParams()` should be wrapped in a suspense boundary.** Search
  params only exist in the browser, so the page can't prerender them. Wrap the
  component that reads them in `<Suspense>`.

## Stop sending the out folder

Every file-based fix above has a ceiling: the person you send `out/` to still
needs a local server, because every asset path starts at `/`. A build preview
works best as a URL.

Comma takes the `out/` folder or a zip of it and returns one link. Assets
upload alongside the HTML with their references rewritten, so the `/_next`,
`basePath` and `file://` problems don't apply, and reviewers comment on the
exact element they mean instead of sending a screenshot.
[Share a Next.js static export](/share-nextjs-static-export) has the steps.

Two honest caveats. Reports run in a sandboxed iframe with scripts enabled but
no same-origin access, so code that reads `localStorage` or cookies without a
`try/catch` throws there. And leave `basePath` unset for a preview build;
it bakes in a path the preview isn't served from.

**[Publish a build preview →](https://commareports.com/)**

### Related

- [Vite build shows a blank page](/fix/vite-build-blank-page)
- [React (Create React App, webpack) build shows a blank page](/fix/react-build-blank-page)
- [Angular build shows a blank page](/fix/angular-build-blank-page)
- [ERR_FILE_NOT_FOUND in Chrome](/fix/err-file-not-found)
- [My HTML report lost its CSS](/html-report-broken-css)
- [The localhost link doesn't work for others](/fix/localhost-link-doesnt-work-for-others)
- [Share a Next.js static export](/share-nextjs-static-export)
