# 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://node-sitecore.gitbook.io/sitecore-cli/usage/configuration.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.