exportPathMap

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

Examples

• Static Export

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 (
    defaultPathMap,
    { 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

Related