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

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

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

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>

In a terminal, deploy the new configuration to your Sitecore instance by running the following command:

jss deploy config

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>" />

In a terminal, deploy the new configuration to your Sitecore instance by running:

jss deploy config

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.

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;

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)