The Sitecore Containers template for JSS Next.js apps

Current version: 21.x

The Next.js template using Sitecore Containers was created to help developers set up a full-stack, Sitecore-first development environment for JSS Next.js apps,

The Sitecore Containers template for JSS Next.js apps is built with Docker, JSS for Next.js, and Sitecore Content Serialization.

Note

For simplicity, this solution does not implement Sitecore Helix conventions for solution architecture. Before you begin building your Sitecore solution, we recommend you 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.

    Note

    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.

  • Scripts to initialize a JSS Next.js application and deploy the app configuration to the Sitecore instance.

  • Sitecore Content Serialization configuration.

  • An MSBuild project for deploying configuration and code into the Sitecore Content Management role. For details, after creating the project, inspect the files in the directory src\platform.

Important

Sitecore supports the template output as it is provided. If you change or amend the solution, it becomes a custom implementation and is subject to the limitations defined in Sitecore's scope of support.

The initialization script

The solution created using the Sitecore Containers template for Next.js projects includes a PowerShell script that simplifies setting up the solution. The script is defined in the file .\init.ps1, located in the root directory of the project. You run the script in PowerShell as part of the procedure to create your project solution.

The \.init.ps1 in PowerShell performs the following tasks:

  • It generates hosts file entries for your project hostname, for example, myproject.localhost.

  • It creates a valid/trusted privately signed wildcard certificate for your project hostname *.myproject.localhost.

  • If running the script with the -InitEnv switch, it populates the .env file with the required environment variable values in for the Sitecore instance.

In 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 must manually set theNODE_EXTRA_CA_CERTS environment variable to prevent HTTPS errors.

The .\init.ps1 script instructs you on how to set the NODE_EXTRA_CA_CERTS environment variable in your user or system environment variables:

RequestResponse
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.
Note

The sample application does not exclude the .env file from source control 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.

Do you have some feedback for us?

If you have suggestions for improving this article,