Configuration

A shared configuration between all packages based on @node-sitecore/cli.

Features

  • Control over configuration values.

  • Support multiple configuration files by environment (.nscrc (default), .development.nscrc, .test.nscrc, .production.nscrc).

  • Support custom configuration path with nsc [cmd] --configPath ./my-custom.config.json,

  • Extensible configuration,

  • All value can be overridden by env or args variable (nconf).

Configuration fields

Key

Default value

Description

currentWebsite

Common

Current code name of the Sitecore website (Can be the same as masterWebsite. It used for localisation process).

masterWebsite

Common

Master code name of the Sitecore website.

solutionName

Base

Solution name of the Visual Studio project.

siteUrl

http://base.dev.local

Site url use on your local machine. You change this value in a separated file like .dev.nsrc.

authConfigFilePath

path/to//Unicorn.UI.config

Auth config file path required by Unicorn task.

outputDir

<rootDir>/build

Path to the Sitecore instance directory.

licensePath

<outputDir>/Data/license.xml

License path required by Sitecore.

authConfigFilePath

<websiteDir>/App_config/Include/Unicorn/Unicorn.UI.config

Auth config file path required by Unicorn task.

srcDir

<rootDir>/src

Source code directory.

foundationDir

<srcDir>/src/Foundation

Foundation level directory (Helix structure).

foundationScriptsDir

<foundationDir>/Core/code/Scripts

Scripts Foundation directory. Shortcut to the shared code.

featureDir

<srcDir>/Feature

Feature level directory (Helix structure).

projectDir

<srcDir>/Project

Project level directory (Helix structure).

websiteDir

<outputDir>/Website

Website directory used by Sitecore.

websiteConfigDir

<websiteDir>/App_Config

Sitecore website config directory.

websiteViewsDir

<websiteDir>/Views

Sitecore views directory.

websiteLibrariesDir

<websiteDir>/bin

Sitecore libraries directory.

themesDir

<websiteDir>/themes

Sitecore themes directory.

buildConfiguration

Debug

MsBuild Configuration (Release or Debug).

buildToolsVersion

15.0

MsBuild .NET Tools-Version (1.0, 1.1, 2.0, 3.5, 4.0, 12.0, 14.0, 15.0, auto).

buildMaxCpuCount

0

Maximal CPU-Count to use. (-1: MSBuild Default, 0: Automatic selection, > 0: Concrete value).

buildVerbosity

minimal

Specify the amount of information to display in the build output (quiet, minimal, normal, detailed, diagnostic).

buildNodeReuse

false

MsBuild Specify whether to enable or disable the re-use of MSBuild nodes (true or false).

buildLogCommand

false

Logs the MsBuild command that will be executed.

excludeFilesFromDeployment

['packages.config']

Exclude files from the deployment on the Sitecore instance.

buildTargets

['<solutionPath>']

Build all solutions or/and projects. Support glob patterns.

buildPaths

['Build']

Build targets options (Build, Clean, Rebuild).

buildPlatform

Any CPU

Build targets options (e.g. x86, x64, Any CPU).

buildProperties

{}

Additional build properties.

publishTargets

['Build']

Publish targets options (Build, Clean, Rebuild).

publishTargets

['<solutionPath>']

Publish all solutions or/and projects. Support glob patterns.

publishPlatform

AnyCpu

Publish platform (e.g. x86, x64, AnyCpu).

publishProperties

{...}

Additional publish properties.

PublishProperties

Default value of publishProperties:

{
  "DeployOnBuild": "true",
  "DeployDefaultTarget": "WebPublish",
  "WebPublishMethod": "FileSystem",
  "DeleteExistingFiles": "false",
  "_FindDependencies": "false"
}

Hierarchical configuration

Configuration management can get complicated very quickly for even trivial applications running in production. nconf addresses this problem by enabling you to setup a hierarchy for different sources of configuration with no defaults. The order in which you attach these configuration sources determines their priority in the hierarchy. Let's take a look at the options available to you

The priority of hierarchical configuration is defined like there :

  1. Default configuration from @node-sitecore/config,

  2. Arguments given by command line tools,

  3. Environment variables,

  4. From file .nscrc,

  5. From --configPath command line options. Example: nsc [cmd] --configPath ./my-custom.config.json,

  6. From .development.nscrc, .test.nscrc, .production.nscrc or [process.env.NODE_ENV].nscrc according to process.env.NODE_ENV value.

Extends configuration

In addiction with Hierarchical configuration feature, config file support the extends keywords to set explicitly an inheritance from another configuration file. It useful when you manage multiple project in different directories location.

Here is an example of multiple project structure:

.
├── ns-master-project (Master project)
│   ├── package.json
│   ├── master.sln
│   └── .nscrc
└── ns-child-project (Child project)
    ├── package.json
    ├── child.sln
    └── .nscrc

We can considere the Master as the project reference. His .nscrc his look like that:

  "currentWebsite": "Master",
  "siteUrl": "https://master.dev.local",
  "instanceRoot": "<rootDir>/build",
  "websiteRoot": "<instanceDir>/Website",
  "licensePath": "<instanceDir>/Data/license.xml",
  "sitecoreLibrariesRoot": "<instanceDir>/Website/bin",
  "solutionName": "master",
  "buildToolsVersion": "15.0",
  ...
}

The .nscrc file from ns-child-project can inherit his configuration from the master project like this:

{
  "extends": "../ns-master-project/.nscrc",
  "currentWebsite": "Child",
  "siteUrl": "https://child.dev.local",
  "solutionName": "child"
}

Now the configuration file of ns-child-project will be resolved with inherited values from ns-master-project and overrided values from ns-child-project.

::: tip When you run a nsc command on ns-child-project, the placeholder <rootDir> will be equals to the ns-child-project path. :::

::: tip To see how the values in the ns-child-project/.nscrc file are resolved, run:

nsc inspect

:::

Getters

Config instance has getters to provide some shortcut to resolve a path based on the main configuration and your local machine configuration (Mac or Windows).

const config = require('@node-sitecore/config');

// getters
console.log(config.currentWebsite) // Custom
console.log(config.websiteDir) // build/Website

// Or get()
console.log(config.get('customObj')) // Object {attr1: "value1", ...}

// or
console.log(config.get('customObj:attr1') // bundle

// has()
console.log(config.has('customObj:attr1')) // true

// set()
config.set('customObj:attr1', "new value");

Getters

Example value

Description

config.currentWebsite

Custom

Current website used by front-end and Sitecore

config.siteUrl

http://base.dev.local

Site url configured on your local machine. Use .development.nscrc

config.authConfigFile

path/to/build/Website/App_config/Include/Unicorn/Unicorn.UI.config

Path the unicorn script configuration.

config.outputDir

path/to/build

Path to the Sitecore instance directory.

config.websiteDir

path/to/build/Website

Path to the Website directory 1.

config.themeWebsiteDir

path/to/build/Website/themes

Path to the themes directory 1.

config.currentWebsiteDir

path/to/build/Website/themes/Custom

Path to the current Website directory 1.

config.sitecoreLibrariesDir

path/to/build/Website/bin

Path to the Sitecore libraries directory 1.

config.licensePath

path/to/build/Data/license.xml

Path to the license file 1.

config.solutionPath

path/to/Base.sln

Path to the Visual Studio solution 1.

config.websiteViewsDir

path/to/build/Website/Views

Path to the Views directory 1.

config.websiteConfigDir

path/to/build/Website/App_Config

Path to the App_Config directory 1.

config.srcDir

path/to/build/Website/src

Path to the source code directory 1.

config.foundationDir

path/to/build/Website/src/Foundation

Path to the Foundation directory 1.

config.foundationScriptsDir

path/to/build/Website/src/Foundation/Core/code/Scripts

Path to the Foundation script directory 1.

config.featureDir

path/to/build/Website/src/Feature

Path to the Feature directory 1.

config.projectDir

path/to/build/Website/src/Project

Path to the Project directory 1.

config.projectScriptsDir

path/to/build/Website/src/Project/Custom/code/Scripts

Path to the current Project scripts directory 1.

config.currentProjectDir

path/to/build/Website/src/Project/Custom/code

Path to the current Project directory 1.

config.buildPaths

[<solutionPath>]

List of solutions or projects given to the command nsc build.

config.publishPaths

[<solutionPath>]

List of solutions or projects given to the command nsc publish.

Placeholders

Config class define a list of placeholders which can be used in your configuration file. It's kind of shortcut to another field in your configuration file. A placeholder follow this pattern: <myPlaceholderName>

::: warning Placeholders is a pre-defined list by the placeholder.js file. Only plugins can add new placeholder with Config.definePlaceholder method. :::

For example, one of the defined placeholder is the <rootDir>. Here a usage example of this placeholder:

{
  "currentWebsite": "MySite",
  "siteUrl": "https://mysite.dev.local",
  "instanceDir": "<rootDir>/build",
}

When the Config class is loaded, the .nscrc configuration file will be imported and all placeholder will be resolved.

To preview the resolved configuration, you can run this command:

nsc inspect

Or in your project:

const config = require('@node-sitecore/config');

// resolver
config.resolve('<rootDir>') // path/to/root
config.resolve('<ouputDir>') // path/to/root/build
config.resolve('<websiteDir>') // path/to/root/build/Website
config.resolve('<themesDir>') // path/to/root/build/Website/themes
config.resolve('<srcDir>') // path/to/root/src
config.resolve('<projectDir>') // path/to/root/src/Project
config.resolve('<featureDir>') // path/to/root/src/Feature
config.resolve('<foundationDir>') // path/to/root/src/Foundation
config.resolve('<currentDir>') // path/to/root/src/Project/Custom/code

List of placeholder

  • <currentWebsite>: Current code name of the Sitecore website (Can be the same as masterWebsite. It used for localisation process).

  • <foundationDir>: Foundation level directory (Helix structure).

  • <featureDir>: Feature level directory (Helix structure)

  • <projectDir>: Project level directory (Helix structure)

  • <srcDir>: Source code directory.

  • <themesDir>: Themes directory.

  • <websiteDir>: Website directory.

  • <outputDir>: Output directory where is installed your Sitecore instance.

  • <solutionPath>: Path to the MsBuild Solution.

  • <rootDir>: Root directory of your project.

  • <contextDir>: Context directory where is runned the CLI command.

PreviousInstallationNextCLI

Last updated