# 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

# 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 3.0.0+

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.

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");

# 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>

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.