Walkthrough: Connecting a Next.js JSS app to Sitecore editors

Abstract

How to connect a Next.js JSS application to the Sitecore Experience Editor or Horizon

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 app initializer, 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.

Note

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:

  1. In the root of the Next.js JSS application directory, open the file /sitecore/config.

  2. On the path configuration/sitecore/javaScriptServices/apps, on the app node for the Next.js application, set the following attributes:

    • serverSideRenderingEngine to http. 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 is http://localhost:3000.

    • serverSideRenderingEngineEndpointUrl to the absolute URL of your Next.js app's API route for handling POST requests from the Sitecore editor. The default value is the route for the Render API Route http://localhost:3000/api/editing/render.

    The default configuration with default values is:

    <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>
  3. In a terminal, deploy the new configuration to your Sitecore instance by running the following command:

    jss 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:

  1. In the root of the Next.js JSS application directory, in the /sitecore/config file, in the node configuration/sitecore/javaScriptServices/settings, set the JavaScriptServices.ViewEngine.Http.JssEditingSecret by adding or uncommenting:

    <setting name="JavaScriptServices.ViewEngine.Http.JssEditingSecret" value="<YOUR_SECRET_TOKEN>" />
  2. In a terminal, deploy the new configuration to your Sitecore instance by running:

    jss deploy config

Configure the Next.js application

To configure the Next.js application for Sitecore editor integration:

  1. In the root directory of the project, in the .env file, set the environment variable JSS_EDITING_SECRET to the value of SITECORE_JSS_EDITING_SECRET you configured server-side.

  2. In any page that is editable in the Sitecore editor, inside a useEffect React hook, call the utility function handleEditorFastRefresh if it is not already present :

    import { 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;

    Note

    The 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:

    handleEditorFastRefresh(true)

Verify the integration

To verify that the Next.js application is running correctly:

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.

Tip

Use the JSS debug logger to debug Sitecore editor integration in Next.js apps.