Static HTML Export

Examples

• Static Export

next export allows you to export your app to static HTML, which can be run standalone without the need of a Node.js server.

The exported app supports almost every feature of Next.js, including dynamic routes, prefetching, preloading and dynamic imports.

next export works by prerendering all pages to HTML. For dynamic routes, your page can export a getStaticPaths function to let the exporter know which HTML pages to generate for that route.

next export is intended for scenarios where none of your pages have server-side or incremental data requirements (though statically-rendered pages can still fetch data on the client side just fine).

If you're looking to make a hybrid site where only some pages are prerendered to static HTML, Next.js already does that automatically for you! Read up on Automatic Static Optimization for details.

next export also causes features like Incremental Static Generation and Regeneration to be disabled, as they require next start or a serverless deployment to function.

How to use it

Develop your app as you normally do with Next.js. Then run:

next build && next export

For that you may want to update the scripts in your package.json like this:

"scripts": {
  "build": "next build && next export"
}

And run it with:

npm run build

Then you'll have a static version of your app in the out directory.

By default next export doesn't require any configuration. It will output a static HTML file for each page in your pages directory (or more for dynamic routes, where it will call getStaticPaths and generate pages based on the result). For more advanced scenarios, you can define a parameter called exportPathMap in your next.config.js file to configure exactly which pages will be generated.

Deployment

You can read about deploying your Next.js application in the deployment section.

Caveats

• With next export, we build an HTML version of your app. At export time, we call getStaticProps for each page that exports it, and pass the result to the page's component. It's also possible to use the older getInitialProps API instead of getStaticProps, but it comes with a few caveats:

  • getInitialProps cannot be used alongside getStaticProps or getStaticPaths on any given page. If you have dynamic routes, instead of using getStaticPaths you'll need to configure the exportPathMap parameter in your next.config.js file to let the exporter know which HTML files it should output.
  • When getInitialProps is called during export, the req and res fields of its context parameter will be empty objects, since during export there is no server running.
  • getInitialProps will be called on every client-side navigation, if you'd like to only fetch data at build-time, switch to getStaticProps.
  • getInitialProps cannot use Node.js-specific libraries or the file system like getStaticProps can. getInitialProps must fetch from an API.

  For static export, the getStaticProps API is always preferred over getInitialProps: it's recommended you convert your pages to use the getStaticProps if possible.

• The fallback: true mode of getStaticPaths is not supported when using next export.

• You won't be able to render HTML dynamically when static exporting, as the HTML files are pre-build. Your application can be a hybrid of Static Generation and Server-Side Rendering when you don't use next export. You can learn more about it in the pages section.

• API Routes are not supported by this method because they can't be prerendered to HTML.

• getServerSideProps cannot be used within pages because the method requires a server. Consider using getStaticProps instead.