Walkthrough: Connecting a Next.js JSS app to Sitecore editors
When you create your Next.js JSS application using the Sitecore Containers template, the Next.js app is pre-configured for integration with Sitecore editors. If you created your app with the JSS CLI, however, you must configure the integration with Sitecore editors manually.
Before connecting a Next.js JSS app to Sitecore editors, you must:
When you have connected your JSS application, you can integrate your Next.js JSS application with a Sitecore editor, such as Sitecore Experience Editor or Horizon.
This walkthrough describes how to:
-
Update the Sitecore configuration patch for the JSS app.
-
Secure the Sitecore editor endpoint.
-
Configure the Next.js application.
The Sitecore Containers template for Next.js provides preconfigured integration with the Experience Editor.
Update the Sitecore configuration patch for the JSS app
To enable integration with an advanced Sitecore editor for a code-first Next.js application, you must first configure the JSS application using a Sitecore configuration patch.
To create the necessary configuration for Sitecore editor integration:
-
In the root of the Next.js JSS application directory, open the file
/sitecore/config
. -
On the path
configuration/sitecore/javaScriptServices/apps
, on theapp
node for the Next.js application, set the following attributes:-
serverSideRenderingEngine
tohttp
. This is because the Next.js application uses the HTTP rendering engine for integrating with Sitecore editors. -
serverSideRenderingEngineApplicationUrl
to a hostname and port of your choosing. The default value ishttp://localhost:3000
. -
serverSideRenderingEngineEndpointUrl
to the absolute URL of your Next.js app's API route for handlingPOST
requests from the Sitecore editor. The default value is the route for the Render API Routehttp://localhost:3000/api/editing/render
.
The default configuration with default values is:
RequestResponse<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"> <sitecore> ... <javaScriptServices> <apps> <app name="exampleApp" ... serverSideRenderingEngine="http" serverSideRenderingEngineEndpointUrl="http://localhost:3000/api/editing/render" serverSideRenderingEngineApplicationUrl="http://localhost:3000" ... /> </apps> </javaScriptServices> ... </sitecore> </configuration>
-
-
In a terminal, deploy the new configuration to your Sitecore instance by running the following command:
RequestResponsejss deploy config
Secure the Sitecore editor endpoint
When using a Next.js application to render Sitecore pages in editing mode, you expose the Sitecore editor endpoints through editor integration API routes in the Next.js app.
To secure the Sitecore editor endpoints, you must first generate a secret token. Sitecore recommends an alphanumeric value of at least 16 characters.
You must set this secret both server-side and client-side, and the values must match.
For setting the JSS Editing Secret server-side, you have two options. You can either set the SITECORE_JSS_EDITING_SECRET
environment variable or you can secure the Sitecore editor endpoint using a Sitecore configuration patch.
To secure the Sitecore editor endpoint using a Sitecore configuration patch:
-
In the root of the Next.js JSS application directory, in the
/sitecore/config
file, in the nodeconfiguration/sitecore/javaScriptServices/settings
, set theJavaScriptServices.ViewEngine.Http.JssEditingSecret
by adding or uncommenting:RequestResponse<setting name="JavaScriptServices.ViewEngine.Http.JssEditingSecret" value="<YOUR_SECRET_TOKEN>" />
-
In a terminal, deploy the new configuration to your Sitecore instance by running:
RequestResponsejss deploy config
Configure the Next.js application
To configure the Next.js application for Sitecore editor integration:
-
In the root directory of the project, in the
.env
file, set the environment variableJSS_EDITING_SECRET
to the value ofSITECORE_JSS_EDITING_SECRET
you configured server-side. -
In any page that is editable in the Sitecore editor, inside a
useEffect
React hook, call the utility functionhandleEditorFastRefresh
if it is not already present :RequestResponseimport { handleEditorFastRefresh } from '@sitecore-jss/sitecore-jss-nextjs'; const MyPage = ({ notFound, layoutData, componentProps }: SitecorePageProps): JSX.Element => { useEffect(() => { // Refresh Experience Editor / Horizon markup and JS after Next.js Fast Refresh handleEditorFastRefresh(); }, []); ... }; export default MyPage;
NoteThe Next.js sample application already includes this code in the default catch-all routes.
The Next.js Fast Refresh feature requires special handling when used within the Sitecore Experience Editor to preserve the so-called editor chromes (additional markup and JavaScript injected by the Sitecore editor for each rendering).
By default, only the editor chromes are refreshed. In some scenarios, you may want to force an entire page to reload instead by using the
forceReload
parameter:RequestResponsehandleEditorFastRefresh(true)
Verify the integration
To verify that the Next.js application is running correctly:
-
Open the application URL, by default
http://localhost:3000
in a browser.
Troubleshooting
When running Next.js in development mode, you might see a timeout upon the first page edit due to dynamic compilation. However, you can expect this to resolve itself on subsequent requests.
If you experience any other issues, check the following:
-
Verify the JSS Editing Secret matches on both server and client-side.
-
Check for any errors in the Next.js logs.
-
Check for any errors in the Sitecore logs.
Use the JSS debug logger to debug Sitecore editor integration in Next.js apps.