Walkthrough: Exporting a JSS Next.js app to static HTML files with next export

Version:

Next.js allows you to export your application as static HTML files that can be run without a Node.js server using any hosting service that supports serving static files or a content delivery network.

This walkthrough describes the steps for exporting a JSS Next.js application to static HTML files using the Next.js command next export.

Static HTML export does not support:

Server-side rendered (SSR) pages (using getServerSideProps).
Pages with incremental static regeneration.
API routes.
Routes with fallback: true.
Internationalized routing.
Request rewrites.
Visitor identification and personalization.
Exporting the Sitecore Media Library. You still need a running Content Delivery instance for the media library.
The default image loader used by the next/image component.

Tip

If you are creating a hybrid application, where some pages are server-side rendered and others are statically generated, Next.js automatically builds routes/pages that use getStaticProps as a static HTML files.

This walkthrough describes how to:

Prepare your application for static HTML export.
Export the application.

Prepare your application for static HTML export

To address some of the limitations of the export process, you must make some changes to the JSS Next.js app.

Before exporting your application to static HTML files:

In the root directory of the JSS Next.js app, modify the file sitecore/config/<appname>.config to:

Include the Sitecore server URL as part of the media requests:
<IncludeServerUrlInMediaUrls>true</IncludeServerUrlInMediaUrls>

Alternatively, remove the <IncludeServerUrlInMediaUrls> configuration patch:

 <layoutService>
     <configurations>
         <config name="jss">
             <rendering>
                 <renderingContentsResolver>
                     <IncludeServerUrlInMediaUrls>false</IncludeServerUrlInMediaUrls>
                 </renderingContentsResolver>
             </rendering>
         </config>
     </configurations>
 </layoutService>

Run jss deploy config.
In the root folder of the Next.js JSS app, in the .env file, add the environment variable:
EXPORT_MODE=true

In the next.config.js file, use the environment variable EXPORT_MODE to instruct Next.js to use i18n and rewrites options only if EXPORT_MODE is set to false:

i18n: !process.env.EXPORT_MODE && {
    // These are all the locales you want to support in your application.
    // These should generally match (or at least be a subset of) those in Sitecore.
    locales: ['en', 'da-DK'],
    // This is the locale that will be used when visiting a non-locale
    // prefixed path e.g. `/styleguide`.
    defaultLocale: packageConfig.language,
  },
rewrites: !process.env.EXPORT_MODE && (async () => {
    if (isDisconnected) {
      // When disconnected we proxy to the local faux layout service host, see scripts/disconnected-mode-server.js
      return [
      // rewrite rules
      ];
    }
  }),

In the src/components/Layout.tsx file, update the use of the <VisitorIdentification /> component to account for the value of the EXPORT_MODE environment variable:
{!process.env.EXPORT_MODE && <VisitorIdentification />}
In the .env file, define the PUBLIC_URL variable.

In the package.json file, add the following scripts:

A basic export script:
"next:export": "next export"

A script for exporting apps that use content from local files:

"export": "cross-env-shell JSS_MODE=disconnected PORT=3042 EXPORT_MODE=true \"npm-run-all --serial bootstrap next:build next:export\""

Replace the PORT value with the port of your disconnected server.

A script for exporting connected apps that use Sitecore content and data:

"export:connected": "cross-env-shell EXPORT_MODE=true \"npm-run-all --serial bootstrap next:build next:export\""

In any component or file where you used the JSS NextImage component or the next/image component, replace the instances with the JSS Image component. Image optimization using the NextImage and next/image components is not supported with static export.

Export the application

To export the application to static HTML files, you use one of the scripts defined for this purpose in the package.json file.

To export a disconnected JSS Next.js application that uses content and data defined in local files:

In the root directory of the JSS application, start the app with the disconnected proxy:
In a terminal, in the root directory of the JSS Next.js app, run the script:
jss export

To export a JSS Next.js application connected to Sitecore:

In a terminal, in the root directory of the JSS Next.js app, run the script:
jss export:connected

Tip

In a CI/CD context, you can run these scripts using npm instead of jss. For example:

npm run export:connected

The export scripts place the resulting files in the out directory.

If you have suggestions for improving this article, let us know!