Walkthrough: Connecting a code-first JSS Next.js application to Sitecore
Every JSS application must at some point in its lifecycle transition from disconnected mode, to being deployed to a Sitecore environment. We can use the JSS CLI to deploy our app to Sitecore, which imports all of our disconnected content and components into Sitecore Items that can then be edited.
Once the app is connected to Sitecore you can run it in connected mode where you 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.
A JSS Next.js app created with the container-based template is already connected to the Sitecore instance inside the Docker container. The following steps only need to be performed for JSS Next.js apps created with the JSS CLI.
Connecting and deploying JSS applications to Sitecore requires that you have access to a Sitecore instance with Sitecore Headless Services, you installed the JSS CLI globally and created a Sitecore API Key.
This walkthrough describes how to:
Configure the site name and hostname for the JSS app.
Set up the connection information.
Deploy the app configuration to Sitecore.
Deploy a JSS Next.js app to Sitecore.
Configure the site name and hostname for the JSS app
In the root folder of your JSS application, open the file containing the configuration patch
/sitecore/config/<AppName>.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.
Provide a top-level domain (TLD) for the development hostname. The browser Microsoft Edge does not resolve hostnames without a TLD. For example, the browser can resolve
http://jss.sitecore but not
The following is a site configuration example for setting the site name and the hostname:
<!-- other attributes removed for brevity -->
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
Add the mapping. For example:RequestResponseshell
Save and close the file.
After adding the hostname entry, add it as a binding on your IIS instance as well:
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 setupand 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/<AppName>.config. For example,
Sitecore import service URL: This is the import service URL of your JSS app. It consists of the hostname of your JSS app plus
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.Important
Do not commit the secret to source control; use a unique secret for each environment and limit access to production secrets. For CI environments,
jss setupaccepts parameters (
--help) that can be used to pass the secret and other parameters from variables. By default, the secret is stored in
/sitecore/config/AppName.deploysecret.config- both of which are automatically ignored if you use Git for source control.
jss setup process generates the
/scjssconfig.json file containing the connection strings for your JSS application.
To build an environment-agnostic JSS app bundle for production environments that always use the current hostname for API requests, in the
scjssconfig.json set the
layoutServiceHost setting to blank. This can be useful when you wish to commit one set of build artifacts and deploy them to CM + CD, or even a headless proxy. This technique is incompatible with connected GraphQL and server-side rendering, which requires an absolute URL to be set.
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:RequestResponseshell
jss deploy config
The script copies the config patch files from the
sitecore/configfolder to the Sitecore
The automatic configuration deployment configured the JSS app within Sitecorecreates 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.
Ensure that the user account you use to run the command has permission to write to the Sitecore website folder configured in
/scjssconfig.json. On Windows, this can involve UAC elevation.
If the JSS app config is to be deployed by a dedicated Sitecore developer (or DevOps), or when you're working with a remote instance, the JSS app config may need to be deployed manually. Acquire the
sitecore/config/*.config patches from the JSS application, and deploy them to your
App_Config/Include folder in a location of your liking, such as a
zzz folder. Ensure you review the config patches for content before deploying them.
Deploy a JSS Next.js 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:RequestResponseshell
jss deploy items --includeContent --includeDictionary
Do 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.