Note: You are viewing the new Next.js documentation. The old docs are still available here.


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, /, 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 permalink

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,

Related permalink