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

Abstract

Get started with full-stack Sitecore JSS and Next.js development

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:

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:

  1. Open PowerShell with administrator privileges.

  2. Run the following command:

       dotnet new -i Sitecore.DevEx.Templates --nuget-source https://sitecore.myget.org/F/sc-packages/api/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:

  1. Open PowerShell with administrator privileges.

  2. 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
  3. 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>"
  4. Go to your solutions folder and create the MyProject solution and project:

    dotnet new sitecore.nextjs.gettingstarted -n MyProject

    Tip

    You can customize the parameters passed into the jss create command invoked internally by the template by using the --JSSCreateParams parameter to pass parameters to the jss create command. For example:

    dotnet new sitecore.nextjs.gettingstarted -n MyProject --JSSCreateParams "--fetchWith GraphQL --prerender SSR"
    
  5. Go to the MyProject folder.

  6. 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>"
  7. To download the Sitecore Docker images, install and configure the containers and JSS application, run the following script:

    .\up.ps1
  8. When prompted, in your browser, log in to Sitecore and accept the device authorization.

  9. 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.