What is Sitecore JavaScript Services?

Sitecore JavaScript Services (JSS) is a Software Developer Kit (SDK) for JavaScript developers. Sitecore JSS enables developers to build solutions using Sitecore and modern JavaScript UI libraries and frameworks.

Sitecore JSS allows for a headless approach when developing. A traditional development approach involves having a back-end and front-end with the code base that enables the communication between the two.

Headless allows the front-end to be a stand-alone piece of software which uses an API to communicate with the back-end.

Both back-end and front-end can be developed independently. This headless approach potentially reduces the number of blockers on a feature.

Sitecore JSS deployment

Deployment of the headless node app for Sitecore JSS can be quite challenging when done for the first time, depending on what needs to be deployed and the customisation required.

For example, the Sitecore JSS app will require HTTP Response Headers. Unlike a standard .NET website, a JSS headless site doesn’t allow for server changes to the app.

For JSS to change server settings, changes must be made directly to the config.js file. To avoid polluting the config.js with too many custom changes, developers need to create a folder containing all the custom server changes.

From the config.js a bundle path is created. This bundle path is added to the server bundle when the config file is applied. It's recommended to use Helmet.js, to include every HTTP Response Header for the entire website site. This is because Helmet.js, by default, applies response headers such as xxsFilter, noSniff, and frameguard. Other responses such as featurePolicy or crossdomain will have to be specifically called as demonstrated here.

Things to consider when deploying Sitecore JSS

For Sitecore JavaScript Services deployment a folder or folders containing all the deployment files needs to be created. The files can be either custom files to overwrite vanilla Sitecore files or custom files to add to vanilla files. These files will need to contain 'transforms' or 'variable' replacement, as they'll need to be modified for the appropriate environments.

NuSpec files are required for arranging and collecting the custom files into appropriate packages. The specific NuSpec files are added to the TeamCity build pipeline. TeamCity then builds the NuGet packages based on the Nuspec files provided.

Build server

Before Sitecore JSS deployment, Node.js needs to be installed on the deployment environment(s). If however, Node.js is pre-installed then the deployment can proceed.

An example of configured JSS specific steps and variables on TeamCity build server is highlighted below:

JSS headless deployment

 

  1. In the example above Step 6, NPM Install for JSS, runs a custom script with the command to install NPM quietly (will only return a flag if the install fails). The command installs a package and any packages that said package depends on, NPM Install will install all modules listed as dependencies in package.json
  2. The NuGet package in Step 8 includes the creation of two special NuGet packages. (1) the JSS NuGet Package which includes all the JSS specific node_modules files and (2) the NuGet Package HeadlessNode which includes Headless Node specific files such as the config.js, index.js, web.config, and a server file to include HTTP Response Headers for the JSS site
  3. Step 9 publishes the NuGet packages to Octopus including the JSS specific packages, which will be installed in specific file locations and transformable variables for specific environments

Deployment

Before deploying, it's recommended to set up iisnode on the environments you wish to deploy to. Iisnode is a native IIS module that allows hosting Node.js applications in IIS on windows. Iisnode also ensures that whenever the Node.js application is updated, the node.exe processes are recycled.

For example, the following steps could be used on a deployment server (such as Octopus), to deploy a JSS site:

  1. Deploy Sitecore Vanilla  JSS: Installs the vanilla version of Sitecore JSS on the Sitecore CD instance. Octopus variables are transformed within this step to suit the required server and environment.
  2. Deploy Vanilla JSS Headless App: Installs the vanilla version of the headless app for the CD server
  3. Deploy CD JSS App Configuration: Uses the Octopus parameters to overwrite the vanilla files with site-specific and deploys site-specific files that change the server configuration of the site, such as adding the HTTP Response Headers for the CD server
  4. CD-JSS NPM Install: Runs a PowerShell script NPM install command on the root folder of the headless app. This installs all the NPM modules needed for the site to function as required
  5. Deploy JSS: Deploys the JSS app package

To recap, .NET configuration changes are not applied to JSS app. Because of this the challenge is how to get these configuration changes to apply on the JSS app on various environments such as Daily, UAT, RTC, etc.

One solution is to use Octopus variables. Within the file that requires the configuration change apply the Octopus variable in the following format #{Octopus.Parameter}, and ensure the variable is also included within the Octopus project otherwise the configuration change will fail.

However, some files will not require Octopus parameters. These files can just be included in the deployment with custom code for the project with the inclusion of Helmet.js for the JSS app config file.

The practice thus far is to only use the Octopus variables for Sitecore vanilla files that have custom settings or custom code applied, and for files that have fluctuating values depending on the environment they are needed on.

Our Sitecore development teams have worked with Sitecore JSS delivering websites to many customers spanning a variety of industries.