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

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

On the configuration/sitecore/javaScriptServices/apps path, 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 configuration/sitecore/javaScriptServices/settings node, 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 markup and JS after Next.js Fast Refresh
    handleEditorFastRefresh();
  }, []);
  ...
};

export default MyPage;

The Next.js Fast Refresh feature requires special handling within the Sitecore Experience Editor to preserve additional markup and JavaScript injected by the Sitecore editor for each rendering, often called editor chromes.

By default, only the editor chromes are refreshed. In some scenarios, you might want to force an entire page to reload instead by using the forceReload parameter:

handleEditorFastRefresh(true)