---
title: "Walkthrough: Connecting a Next.js JSS app to Sitecore editors"
slug: "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"
---
# 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:

- [Connect your JSS application to Sitecore](https://doc.sitecore.com/xp/en/developers/hd/19/sitecore-headless-development/walkthrough--connecting-a-code-first-jss-next-js-application-to-sitecore.html "Walkthrough: Connecting a code-first JSS Next.js application to Sitecore").

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](https://doc.sitecore.com/xp/en/developers/hd/19/sitecore-headless-development/walkthrough--setting-up-a-development-environment-with-the-sitecore-containers-template-for-next-js.html "Walkthrough: Setting up a development environment with 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](https://doc.sitecore.com/xp/en/developers/hd/19/sitecore-headless-development/jss-app-configuration-api.html "JSS App Configuration API").

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:

    ```xml
    <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:

    ```text
    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:

    ```text
    <setting name="JavaScriptServices.ViewEngine.Http.JssEditingSecret" value="<YOUR_SECRET_TOKEN>" />
    ```

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

    ```text
    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`](https://github.com/Sitecore/jss/blob/release/19.0.0/ref-docs/sitecore-jss-nextjs/README.md#handleeditorfastrefresh) if it is not already present :

    ```csharp
    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](https://nextjs.org/docs/basic-features/fast-refresh) 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:

    ```text
    handleEditorFastRefresh(true)
    ```

## Verify the integration

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

- Open the application URL, by default `[http://localhost:3000](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.

> [!tip]
> Use [the JSS debug logger](https://doc.sitecore.com/xp/en/developers/hd/19/sitecore-headless-development/debug-logging-in-jss-apps.html "Debug logging in JSS apps") to debug Sitecore editor integration in Next.js apps.