This blog was last modified 238 days before.

Static Export

When the app not necessarily requires all Next.js server side features and don't require Node.js (For example if you are developing an SPA), then maybe you would use Static Export feature provided by Next.js.

To get a better support of Static Export feature, Next.js recommend you using App Router.

Enable Static Export

To enable Static Export, add following config to next.config.mjs:

const nextConfig = {
    output: "export"
};

The old next export script has been deprecated and removed in Next.js 14, so the only way to use this feature now is update the config file.

After this settings, everytime you call next build, it would generate the static file in /out directory.

Reference Error: window is undefined

This is a general error that we may met when using static export.

To solve this, we need to ensure all the client specified code are actually only run in client side.

You may say you have added use client; at the beginning of the file, but this is not enough. Because in the new version of Next.js, client component will also be pre-rendered in server.

To make sure your code run only in client side, you can write something like:

if (typeof window !== 'undefined') {
    // client only code like below
    // access window etc
    return window.matchMedia("(prefers-color-scheme:dark)").matches;
}

Route 404 Not Found

After exporting and deploying the exported static file, we may met 404 Not Found error when accessing some of the sub routes like /info/user, this may because we don't set the NGINX rules.

location / {
    if ($request_uri ~ ^/(.*)\.html(\?|$)) {
        return 302 /$1;
    }
    try_files $uri $uri.html $uri/ =404;
}

After adding this NGINX settings, there should be no more 404 when you try to access any route.

TypeScript / ESLint Error When Exporting

This issue is generally caused by unexpected export in Next.js special files.

For example, trying to export a custom React Components besides default export in files like page.ts, layout.ts will likely to trigger this issue.

// In /src/app/page.tsx

export default Page(){
    return (
        ...
    );
}

// This export may trigger type checking errors when using Static Export
// And should be removed in order to solve the issue.
export MyCustomComponent(){
    return (
        ...
    );
}

And the solution is quite simple: just remove the redundant export in these files.

Refs

Next.js Docs - Static Export