Walkthrough: Exporting a JSS Next.js app to static HTML files with next export
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 thenext/image
component.
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:
RequestResponse<IncludeServerUrlInMediaUrls>true</IncludeServerUrlInMediaUrls>
-
Alternatively, remove the
<IncludeServerUrlInMediaUrls>
configuration patch:RequestResponse<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:RequestResponseEXPORT_MODE=true
-
In the
next.config.js
file, use the environment variableEXPORT_MODE
to instruct Next.js to usei18n
andrewrites
options only ifEXPORT_MODE
is set tofalse
:RequestResponsei18n: !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 theEXPORT_MODE
environment variable:RequestResponse{!process.env.EXPORT_MODE && <VisitorIdentification />}
-
In the
.env
file, define thePUBLIC_URL
variable. -
In the
package.json
file, add the following scripts:-
A basic export script:
RequestResponse"next:export": "next export"
-
A script for exporting apps that use content from local files:
RequestResponse"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:
RequestResponse"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 thenext/image
component, replace the instances with the JSSImage
component. Image optimization using theNextImage
andnext/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:
RequestResponsejss 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:
RequestResponsejss export:connected
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.