Walkthrough: Using the Sitecore Container Starter Template for JSS Next.js Projects

Sitecore provides a Getting Started template for Sitecore developers that want to try out Sitecore JSS with Sitecore Containers, the Sitecore Next.js SDK, and Sitecore Content Serialization.

For simplicity, this solution does not implement Sitecore Helix conventions for solution architecture. As you begin building your Sitecore solution, you should review Sitecore Helix and the Sitecore Helix Examples for guidance on implementing a modular solution architecture.

The template includes:

A docker-compose environment for a Sitecore XP0 topology with a Next.js rendering host.

The included docker-compose.yml is a stock XP0 environment from the Sitecore Container Support Package. All changes/additions for this solution are included in the docker-compose.override.yml.

Scripted invocation of jss create and jss deploy to initialize a Next.js application.
Sitecore Content Serialization configuration.
An MSBuild project for deploying configuration and code into the Sitecore Content Management role. (see src\platform).

Support

Sitecore supports the template output as provided. Once changed or amended, the solution becomes a custom implementation and is subject to limitations as defined in Sitecore's scope of support.

Create a solution from the Getting Started template

To create a solution from the Getting Started template, you must complete the following procedures:

Install the prerequisites
Install the template
Create the MyProject solution
Rebuild search indexes
Add a language and import it (Optional)

Install the prerequisites

Before you can install the template and create a solution, you must make sure that you have these software components installed on your workstation:

A valid Sitecore license file.
Windows PowerShell 5.1. PowerShell 7 is not supported at this time.
NodeJs 14.x (we recommend using the latest LTS release).
.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.

See the Sitecore Containers documentation for more information on system requirements.

Install the template

Before you can create a solution, you must download and install the .NET starter 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

The dotnet tool does not provide obvious feedback that the install was successful. However, the install command ends by listing all of the installed templates. If the install is successful, the list includes sitecore.nextjs.gettingstarted.

Create the MyProject solution

You can name your solution anything you like, but we name the solution MyProject in this example.

Using non-Latin characters in the project/folder name can give unexpected results because of character limitations in Docker registry names and URLs.

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 do, you must stop it:

   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:

   Stop-Service -Name "<the name of your service>"

Or, if you have started it with Non-Sucking Service Manager, stop it with this command:

   nssm stop "<the name of your service>"

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 the Sitecore container environment, use the provided init.ps1 script:

   .\init.ps1 -InitEnv -LicenseXmlPath "<C:\path\to\license.xml>" -AdminPassword "<desired password>"

The .\init.ps1 script provides:

A valid/trusted privately signed wildcard certificate for *.myproject.localhost.
On local environments, Sitecore instances are installed using privately signed certificates. .\init.ps1 generates certificates using the mkcert utility. Node.js rejects these certificates because their root CAs are not known.

If this is your first time using mkcert with Node.js, you will need to manually set the NODE_EXTRA_CA_CERTS environment variable to prevent HTTPS errors.

The .\init.ps1 script will instruct you on how to set the NODE_EXTRA_CA_CERTS environment variable in your user or system environment variables:
```
To avoid HTTPS errors, set the NODE_EXTRA_CA_CERTS environment variable using the following command:
setx NODE_EXTRA_CA_CERTS C:\Users\<username>\AppData\Local\mkcert\rootCA.pem

You will need to restart your terminal or VS Code for it to take effect.
```
Hosts file entries for myproject.localhost.
Required environment variable values in .env for the Sitecore instance.

Running the init.ps1 script with the -InitEnv switch populates the .env variables required by the Sitecore container environment.

The sample application does not exclude the .env file from source control. This is so that developers can share initialized environment variables.

If you add your .env file into source control, other developers can prepare a certificate and hosts file entries by simply running the init.ps1 script.

If your Sitecore solution and/or its data are sensitive, we recommend that you exclude the .env file from source control and provide other means of centrally configuring the information within.

Download the Sitecore Docker images, install and configure the containers and JSS application:

   .\up.ps1

When prompted, log into Sitecore via your browser, 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 .\up.ps1 for the first time, or if you ever run \docker\clean.ps1, you need to rebuild the search indexes.

Add a language and import it (Optional)

To add a language to your JSS Next.js application, you must:

Add the language to /sitecore/system. In this example, use da-DK.
Deploy and publish the language:

      jss deploy items --language=da-DK --includeContent --includeDictionary
      dotnet sitecore publish

The language links in the sample application should work now.

To import the deployed language into your serialized items, you must:

In the file src/InitItems.module.json, add a serialization configuration for languages. For example:

   {
       "name": "languages",
       "path": "/sitecore/system/Languages",
       "scope": "descendantsOnly",
       "rules": [
           {
               "path": "/en",
               "scope": "ignored"
           }
       ]
   }

Run dotnet sitecore ser pull.

Found a problem? Have something to add? Edit this on GitHub

Documentation