This feature is exclusive of next export. Please refer to Static HTML export if you want to learn more about it.


Let's start with an example, to create a custom exportPathMap for an app with the following pages:

  • pages/index.js
  • pages/about.js
  • pages/post.js

Open next.config.js and add the following exportPathMap config:

module.exports = {
  exportPathMap: async function (
    { dev, dir, outDir, distDir, buildId }
  ) {
    return {
      '/': { page: '/' },
      '/about': { page: '/about' },
      '/p/hello-nextjs': { page: '/post', query: { title: 'hello-nextjs' } },
      '/p/learn-nextjs': { page: '/post', query: { title: 'learn-nextjs' } },
      '/p/deploy-nextjs': { page: '/post', query: { title: 'deploy-nextjs' } },

The pages will then be exported as HTML files, for example, /about will become /about.html.

exportPathMap is an async function that receives 2 arguments: the first one is defaultPathMap, which is the default map used by Next.js. The second argument is an object with:

  • dev - true when exportPathMap is being called in development. false when running next export. In development exportPathMap is used to define routes.
  • dir - Absolute path to the project directory
  • outDir - Absolute path to the out/ directory (configurable with -o). When dev is true the value of outDir will be null.
  • distDir - Absolute path to the .next/ directory (configurable with the distDir config)
  • buildId - The generated build id

The returned object is a map of pages where the key is the pathname and the value is an object that accepts the following fields:

  • page: String - the page inside the pages directory to render
  • query: Object - the query object passed to getInitialProps when prerendering. Defaults to {}

The exported pathname can also be a filename (for example, /readme.md), but you may need to set the Content-Type header to text/html when serving its content if it is different than .html.

Adding a trailing slash

It is possible to configure Next.js to export pages as index.html files and require trailing slashes, /about becomes /about/index.html and is routable via /about/. This was the default behavior prior to Next.js 9.

To switch back and add a trailing slash, open next.config.js and enable the exportTrailingSlash config:

module.exports = {
  exportTrailingSlash: true,

Customizing the output directory

next export will use out as the default output directory, you can customize this using the -o argument, like so:

next export -o outdir