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

Version:

Using the Sitecore Containers template for Next.js you can create a full-stack, Sitecore-first JSS Next.js project.

This walkthrough describes the steps for setting up your development environment using the Sitecore containers template for Next.js.

Before you can install the template and create a full-stack solution for Sitecore and JSS for Next.js, you must have the following software components on your workstation:

A valid Sitecore license file.
Windows PowerShell 5.1. PowerShell 7 is not supported at this time.
A current version of Node.js. We recommend using the most recent long-term support (LTS) version.
.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.
Git

Note

This template configures a development environment for the current release of Sitecore XP and JSS. To find out which version of JSS to use with your licensed Sitecore XP version, consult the Sitecore compatibility table.

This walkthrough describes how to:

Install the template.
Create the project solution.
Rebuild search indexes.

Install the template

Before you can 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://nuget.sitecore.com/resources/v3/index.json
Note

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

Create the project solution

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

Important

Do not use non-Latin characters in the project/folder name. Using non-Latin characters 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>"
Alternatively, 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 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 "<desired password>"

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

If you ever run the script \docker\clean.ps1, you must rebuild search indexes.

If you have suggestions for improving this article, let us know!