> For the complete documentation index, see [llms.txt](https://node-sitecore.gitbook.io/sitecore-cli/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://node-sitecore.gitbook.io/sitecore-cli/usage/configuration.md). # 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](https://github.com/indexzero/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 | `/build` | Path to the Sitecore instance directory. | | licensePath | `/Data/license.xml` | License path required by Sitecore. | | authConfigFilePath | `/App_config/Include/Unicorn/Unicorn.UI.config` | Auth config file path required by Unicorn task. | | srcDir | `/src` | Source code directory. | | foundationDir | `/src/Foundation` | Foundation level directory (Helix structure). | | foundationScriptsDir | `/Core/code/Scripts` | Scripts Foundation directory. Shortcut to the shared code. | | featureDir | `/Feature` | Feature level directory (Helix structure). | | projectDir | `/Project` | Project level directory (Helix structure). | | websiteDir | `/Website` | Website directory used by Sitecore. | | websiteConfigDir | `/App_Config` | Sitecore website config directory. | | websiteViewsDir | `/Views` | Sitecore views directory. | | websiteLibrariesDir | `/bin` | Sitecore libraries directory. | | themesDir | `/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 | `['']` | 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 | `['']` | 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: ```javascript { "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: ```javascript "currentWebsite": "Master", "siteUrl": "https://master.dev.local", "instanceRoot": "/build", "websiteRoot": "/Website", "licensePath": "/Data/license.xml", "sitecoreLibrariesRoot": "/Website/bin", "solutionName": "master", "buildToolsVersion": "15.0", ... } ``` The `.nscrc` file from ns-child-project can inherit his configuration from the master project like this: ```javascript { "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 `` 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: ```bash 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). ```javascript 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` | `[]` | List of solutions or projects given to the command `nsc build`. | | `config.publishPaths` | `[]` | 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: `` ::: warning Placeholders is a pre-defined list by the [placeholder.js](https://github.com/NodeSitecore/sitecore-cli/blob/master/packages/config/src/config.js) file. Only plugins can add new placeholder with `Config.definePlaceholder` method. ::: For example, one of the defined placeholder is the ``. Here a usage example of this placeholder: ```javascript { "currentWebsite": "MySite", "siteUrl": "https://mysite.dev.local", "instanceDir": "/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: ```bash nsc inspect ``` Or in your project: ```javascript const config = require('@node-sitecore/config'); // resolver config.resolve('') // path/to/root config.resolve('') // path/to/root/build config.resolve('') // path/to/root/build/Website config.resolve('') // path/to/root/build/Website/themes config.resolve('') // path/to/root/src config.resolve('') // path/to/root/src/Project config.resolve('') // path/to/root/src/Feature config.resolve('') // path/to/root/src/Foundation config.resolve('') // path/to/root/src/Project/Custom/code ``` ### List of placeholder * ``: Current code name of the Sitecore website (Can be the same as `masterWebsite`. It used for localisation process). * ``: Foundation level directory (Helix structure). * ``: Feature level directory (Helix structure) * ``: Project level directory (Helix structure) * ``: Source code directory. * ``: Themes directory. * ``: Website directory. * ``: Output directory where is installed your Sitecore instance. * ``: Path to the MsBuild Solution. * ``: Root directory of your project. * ``: Context directory where is runned the CLI command.