Contact Us

A NextJS application uses the Sitecore Headless Services HTTP rendering engine, Next.js API routes, and the Next.js Preview Mode to integrate with advanced Sitecore editors, such as the Experience Editor or Horizon.

The following diagram illustrates the architecture of integrating a NextJS JSS app with advanced Sitecore editors. The diagram uses Sitecore Experience Editor as an example, but the architecture is similar for Horizon integration.

In the diagram, APIs included with JSS for Next.js are highlighted with teal. Elements with other colors are part of the Next.js JSS sample application.

MicrosoftTeams-image (63)

API Routes

To integrate with Sitecore editors, the NextJs JSS sample application includes three NextJs API routes, as follows:

The Render API Route defined in the file /pages/api/editing/render.ts handles POST requests from the Sitecore editor, using logic encapsulated in the middleware EditingRenderMiddleware provided by JSS for NextJS. Use this route as the value for the JSS app configuration option serverSideRenderingEngineEndpointUrl. <.p>

The Data API Route defined in /pages/api/editing/data/[key].ts is a dynamic NextJS API route responsible for handling the storage and retrieval of data sent from the Sitecore editor using the middleware ‘Editing Data Middleware’, provided by JSS for NextJS.

The Page Route, the main NextJS optional catch-all route, defined in /pages/ [[...path]]. tsx, renders all Sitecore page routes.


Next.js Preview Mode

Preview Mode is a built-in feature of NextJS meant for occasions when you are drafting content using the Sitecore Experience Editor and wish to render pages with this content at request time, bypassing any static generation. Integrating Next.js JSS apps with Sitecore editors depends on this feature.

The ‘Editing Render Middleware’ enables the NextJ Preview Mode. The NextJS Preview Mode creates specific cookies on the Render API Route responses and passes them along to the subsequent Page Route request.

The Page Props Factory, responsible for preparing all the data needed to render the page, checks if the current route is in Preview Mode. If it determines that the page is in preview mode, the Page Route request can use the preview/editing data.

 

Features supported by JSS for Next.js

  • NextJS static HTML export, incremental static site generation, server-side rendering, and hybrid rendering.
  • Dynamic author-defined URLs through the NextJS file-based router and the Sitecore Layout Service.
  • Dynamic component rendering based on author-defined page layouts.
  • Helper components for rendering various Sitecore field types.
  • Integration with advanced Sitecore content and layout editors through NextJS Preview Mode.
  • Sitecore route querying for static site generation.
  • NextJS client-side routing support for Sitecore link and rich text fields.
  • Internationalization support through Sitecore language versions and NextJS internationalized routing.
  • Component-level data fetching for Sitecore-driven components.
  • Sitecore analytics and personalization support. This feature requires NextJS app and uses the Sitecore Layout Service REST API.

JSS for NextJS development

Sitecore offers two paths for setting up your environment for developing NextJs JSS apps based on your role, workflow, and operating system.

  • Full-stack, Sitecore-first development: To create a solution for a full-stack development with Sitecore and JSS for NextJs, Sitecore provides a container-based template optimized for the Sitecore-first development workflow.

  • Front-end development: If you do not have a Windows machine and work strictly in a front-end /JavaScript development role, you can get started with JSS front-end development on any operating system supported by NodeJs, using the JSS CLI.

Setting up a development environment with the Sitecore Containers template for Next.js

List of Prerequisites:

  • A valid Sitecore license file.
  • Windows PowerShell 5.1. PowerShell 7 is not supported currently.
  • The current long-term support (LTS) version of Node.js.
  • .NET Core 3.1 SDK (check your installed version with the dotnet --version command).
  • .NET Framework 4.8 SDK (see the Microsoft procedure for checking .NET Framework versions).
  • Visual Studio 2019.
  • Docker for Windows, with Windows Containers enabled.
  • Any required components for using Sitecore Containers.

Install the template

Before you create a solution, you must download and install the .NET sitecore.nextjs.gettingstarted template in your file system.

To install the template:

  • Open PowerShell with administrator privileges.

  • Run the following command:

dotnet new -i Sitecore.DevEx.Templates --nuget-source https://sitecore.myget.org/F/sc-packages/api/v3/index.json


Create the project solution

To create the MyProject solution:

  • Open PowerShell with administrator privileges.
  • Check if you have the Internet Information Server running on port 443:
  • Get-Process -Id (Get-NetTCPConnection -LocalPort 443).OwningProcess

    If you must stop it, run the following command:

    iisreset /stop

  • Check if you have Apache Solr or any other service running on port 8984:
  • Get-Process -Id (Get-NetTCPConnection -LocalPort 8984).OwningProcess

    If you do you must stop it by running the following command:

    Stop-Service -Name " "

  • Go to your solutions folder and create the MyProject solution and project:
  • dotnet new sitecore.nextjs.gettingstarted -n MyProject

  • Go to the MyProject folder.

  • To prepare the Sitecore container environment, run the script init.ps1 from the root directory of the project:

  • .\init.ps1 -InitEnv -LicenseXmlPath "<c:\path\to\license.xml>" -AdminPassword ""</c:\path\to\license.xml>

  • To download the Sitecore Docker images, install and configure the containers and JSS application, run the following script:

  • .\up.ps1

  • When prompted, in your browser, log in to Sitecore and accept the device authorization.

  • Wait for the startup script to open browser tabs for the rendered site and the Sitecore Launchpad.

Rebuild search indexes

  • After running the script .\up.ps1 for the first time, or if you ever run the script \docker\clean.ps1, you must rebuild search indexes.

Creating a JSS Next.js application with the JSS CLI

Before you can create JSS applications using the JSS CLI, you must install the JSS CLI globally.

 

Create a JSS Next.js application

To create a JSS application based on the Next.js template:

In a terminal, run the following command, providing the name of the directory and the nextjs template:

jss create my-first-jss-app nextjs [--fetchWith {REST|GraphQL}] [--prerender {SSG|SSR}]

The command creates the JSS Next.js application for the latest version of JSS and installs the necessary packages.

To create an application using a previous version of JSS, see an example in theJSS CLI reference for jss create.

 

Run the JSS Next.js application

To run your application:

In the terminal, go to your application directory. For example:

cd my-first-jss-app

In the terminal, run the command:

jss start

You can now start developing in disconnected mode.

 

Connecting a code-first JSS Next.js application to Sitecore

Every JSS application must, at some point in its lifecycle, transition from the disconnected mode, to being deployed to a Sitecore environment. We can use the JSS CLI to deploy our app to Sitecore, which imports all the disconnected content and components into Sitecore Items that can then be edited.

Once the app is connected to Sitecore, you can run it in the connected mode where you can develop the app using live data from Sitecore and integrate the Next.js JSS app with Sitecore content and layout editors such as Experience Edge and Horizon. Connecting and deploying JSS applications to Sitecore requires you to have access to a Sitecore instance with Sitecore Headless Services, install the JSS CLI globally, and create a Sitecore API Key.

 

Configure the site name and hostname for the JSS app

Applications created based on JSS samples with the JSS create command provided by the JSS CLI, include a Sitecore site definition in a Sitecore configuration patch that is created with the application.

In the root folder of your JSS application, open the file containing the configuration patch /sitecore/config/.config and confirm that the ‘Hostname’ attribute matches a host header that the server must respond to. If you are deploying a JSS app as the default site for the Sitecore installation, you can remove the ‘Hostname’ attribute so that the JSS app responds to any host.

The following is a site configuration example for setting the site name and the hostname:

hostName="myapp.siteco.re" />

When using a local instance, you must map the desired hostname to your local host.

To map a hostname to your localhost on Windows:

  • Open a code editor as an administrator.

  • In the editor, open the file C:\Windows\System32\drivers\etc\hosts.

  • Add the mapping. For example:

  • 127.0.0.1 myapp.siteco.re

  • Save and close the file.

After adding the hostname entry, add it as a binding on your IIS instance as well:

MicrosoftTeams-image (64)

If you plan to deploy multiple JSS applications, you must configure the different hosts and hostname bindings in IIS for Sitecore to resolve the correct site.


Set up the connection information

To configure the connection:

In a terminal, run the JSS command jss setup and follow the prompts. Follow the prompts to supply the following pieces of information:

  • Website folder: This is the root physical path to the Sitecore instance, used to deploy config files. File share paths are fine for remote instances. For example: c:\inetpub\wwwroot\MySitecore\Website. If you do not have access to the website folder directly, answer no when asked if your instance is remote.

  • Sitecore hostname: This is the hostname of your JSS app previously configured in the Sitecore configuration patch /sitecore/config/.config. For example, http://jssreactweb

  • Sitecore import service URL: This is the import service URL of your JSS app. It consists of the hostname of your JSS app plus /sitecore/api/jss/import: http://jssreactweb/sitecore/api/jss/import. You can leave this blank to use the default value or provide your custom URL.

  • Sitecore API key: Provide the Item ID of the API key for this JSS app.

  • Deployment secret: This is a shared secret that enables authentication to deploy your app items to Sitecore. We recommend you use the random key generated by the setup process. If you choose your own key, the secret must be a randomly generated string 32 or more characters long

The jss setup process generates the /scjssconfig.json file containing the connection strings for your JSS application.

 

Deploy the app configuration to Sitecore

The JSS app is registered with Sitecore using configuration patches that are deployed to the Sitecore server. When setting up the Sitecore server, you already edited one of these patches when setting the hostName attribute. Before the configuration patch can take effect on the Sitecore server, you need to deploy it. You can deploy configurations automatically (recommended) or manually.

Automatic deployment deploys the config patches directly from the JSS app using the JSS CLI.

To automatically deploy the configuration patches:

  • In your JSS app working directory, in a terminal, run the command:

  • jss deploy config.

    The automatic configuration deployment configured the JSS app within Sitecore creates a site for it and enables live mode without the need to publish. Developers should review the patch file carefully to ensure all the settings are correct for the environment. In production, for example, the application should not run in live mode.

 

Deploy a JSS NextJs app to Sitecore

Applications built with JSS for Next.js are deployed differently to Sitecore than apps built with JSS for React, Angular, and Vue.js because of the particularities of Next.js. Essentially, because of the Next.js server, a JSS Next.js app uses the HTTP rendering engine. This means that any Sitecore instance behaves as a remote Sitecore instance in connection to a Next.js application.To deploy a JSS Next.js app to a Sitecore installation:

  • Open a command prompt/terminal within your JSS app.
  • Run the command:
  • jss deploy items --includeContent –includeDictionary ImportantDo not use jss deploy app or jss deploy files when working with Next.js.You do not have to configure a sitecoreDistPath in the package.json file of a Next.js JSS app


Conclusion

We have extensively covered the entire process of integrating NextJS applications using the Sitecore Headless Services HTTP rendering engine, the NextJs API routes, and the NextJs Preview Mode.

If you are keen to learn more or are willing to implement similar procedures to enhance your company’s digital customer experience, then reach out to us at Altudo. Our team of certified experts will not only help you better understand the NextJS framework and its relevance for your business, but also help implement and build digital applications to drive tangible growth.

Need Help?