--- title: Configuration --- import EnvBadges from '@theme/EnvBadges'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; Powerful convention based finder, loader, and manager of both configuration and ignore files. Will find config files of multiple supported formats while traversing up the tree. ## Installation ```bash yarn add @boost/config ``` ```bash pnpm add @boost/config ``` ```bash npm install @boost/config ``` ## Setup Configuration in the context of this package encompasses 2 concepts: config files and ignore files. Config files are a collection of settings (key-value pairs), while ignore files are a list of file path patterns and globs. To utilize this functionality, we must extend the [`Configuration`][configuration] class, and define a blueprint for the structure of our config file (using [optimal](./common.mdx#class-contracts)). This class will fulfill multiple roles: managing, finding, loading, and processing of files. ```ts import { Blueprint, Schemas } from '@boost/common'; import { Configuration } from '@boost/config'; // Example structure interface ConfigFile { ast?: boolean; cwd?: string; debug?: boolean; exclude?: string[]; include?: string[]; options?: object; } class Manager extends Configuration { blueprint({ array, bool, string, object }: Schemas): Blueprint { return { ast: bool(), cwd: string(process.cwd()), debug: bool(), exclude: array().of(string()), include: array().of(string()), options: object(), }; } } ``` This class layer is designed to be "internal only", and should not be utilized by consumers directly. Instead, consumers should interact with an instance of the class, like so. ```ts export default new Manager('boost'); ``` > The string value passed to the constructor is the name of the config and ignore files, in camel > case format. For example, `boost.js` and `.boostignore`. ### Finder options To customize the config file finding and loading layer, call [`Configuration#configureFinder()`](/api/config/class/Configuration#configureFinder) within [`#bootstrap()`](/api/config/class/Configuration#bootstrap). This method supports all options in [`ConfigFinderOptions`](/api/config/interface/ConfigFinderOptions) except for `name`. ```ts class Manager extends Configuration { // ... bootstrap() { this.configureFinder({ extendsSetting: 'extends', includeEnv: false, }); } } ``` ### Processor options To customize the config processing layer, call [`Configuration#configureProcessor()`](/api/config/class/Configuration#configureProcessor) while within [`#bootstrap()`](/api/config/class/Configuration#bootstrap). This method supports all options in [`ProcessorOptions`](/api/config/interface/ProcessorOptions) except for `name`. ```ts class Manager extends Configuration { // ... bootstrap() { this.configureProcessor({ defaultWhenUndefined: false, }); } } ``` ### Processing settings When multiple config files are merged into a single config file, this is known as processing. Processing happens automatically for each setting as we need to determine what the next setting value would be. By default, the following rules apply when the next and previous setting values are: - _Arrays_: will be merged and deduped into a new array. - _Objects_: will be shallow merged (using spread) into a new object. - _Primitives_: next value will overwrite the previous value. - _Undefined_: will reset to initial value if [`defaultWhenUndefined`](/api/config/interface/ProcessorOptions#defaultWhenUndefined) is true. If you would like to customize this process, you can define custom process handlers per setting with [`Configuration#addProcessHandler()`](/api/config/class/Configuration#addProcessHandler). This method requires a setting name and handler function (which is passed the previous and next values). ```ts class Manager extends Configuration { // ... bootstrap() { // Always use forward slashes this.addProcessHandler('cwd', (prev, next) => next.replace(/\\/g, '/')); // Deep merge options since they're dynamic this.addProcessHandler('options', (prev, next) => deepMerge(prev, next)); } } ``` > Handlers may only be defined on root-level settings. To make this process even easier, we provide a handful of pre-defined handlers (below) that can be used for common scenarios (these handlers power the default rules mentioned above). - [`mergeArray`](/api/config/function/mergeArray) - Merges previous and next arrays into a new array while removing duplicates (using `Set`). - [`mergeExtends`](/api/config/function/mergeExtends) - Merges previous and next file paths (either a string or array of strings) into a new list of file paths. This is useful if utilizing [config extending](#enable-extending). - [`mergeObject`](/api/config/function/mergeObject) - Shallow merges previous and next objects into a new object using object spread. - [`mergePlugins`](/api/config/function/mergePlugins) - Merges previous and next plugin configurations into an object. Plugin configs can either be a list of sources, or list of sources with flags/options (tuples), or a map of sources to flags/options. This is useful if utilizing the [plugin package](./plugin.mdx#configuration-files). - [`overwrite`](/api/config/function/overwrite) - Overwrite the previous value with the next value. ```ts import { mergePlugins } from '@boost/config'; class Manager extends Configuration { // ... bootstrap() { // Using example from @boost/plugin documentation this.addProcessHandler('renderers', mergePlugins); } } ``` ## Config files A config file is a file that explicitly defines settings (key-value pairs) according to a defined structure. > Configuration files are designed to be serializable, so please use primitive, object, and array > values only. Try to avoid non-serializable values like class instances. ### File patterns Config files are grouped into either the root or branch category. The root of a project is denoted by a root `*.config.*` file, or a folder with the name `.config`, which contains config files. Branch config files are located within folders (at any depth) below the root, and are prefixed with a leading dot (`.`). | Root | Branch | | --------------------------------------------------------- | --------------------- | | `.config/.`, `.config.` | `..` | | `.config/..`, `.config..` | `...` | - `` - Name passed to your [`Configuration`][configuration] instance (in camel case). - `` - Current environment derived from `NODE_ENV`. - `` - File extension supported by the defined [loaders and extensions](#finder-options). ### File formats Config files can be written in the formats below, and are listed in the order in which they're resolved (can customize with the [`extensions`](#finder-options) option). - `.js` - JavaScript. Will load with [CommonJS or ECMAScript modules][esm] depending on the `package.json` `type` field. Defaults to CommonJS if not defined. - `.json`, `.json5` - JSON. Supports [JSON5](https://json5.org/) for both extensions. - `.cjs` - JavaScript using [CommonJS][esm] (`require()`). _Supported by all Node.js versions._ - `.mjs` - JavaScript using [ECMAScript modules][esm] (`import`/`export`). _Requires Node.js v13.3+._ - `.ts` - TypeScript. _Requires the `typescript` package._ - `.yaml`, `.yml` - YAML. _Does not support multi-document._ Based on the file structure in the [Setup](#setup) section above, the config files can be demonstrated as followed (excluding standard JavaScript since it's either CJS or MJS). ```js module.exports = { ast: false, debug: true, exclude: ['**/node_modules/**'], include: ['src/**', 'tests/**'], options: { experimental: true }, }; ``` ```js export default { ast: false, debug: true, exclude: ['**/node_modules/**'], include: ['src/**', 'tests/**'], options: { experimental: true }, }; ``` ```ts import type { ConfigFile } from './types'; const config: ConfigFile = { ast: false, debug: true, exclude: ['**/node_modules/**'], include: ['src/**', 'tests/**'], options: { experimental: true }, }; export default config; ``` ```json { "ast": false, "debug": true, "exclude": ["**/node_modules/**"], "include": ["src/**", "tests/**"], "options": { "experimental": true } } ``` ```yaml ast: false debug: true exclude: - '**/node_modules/**' include: - 'src/**' - 'tests/**' options: experimental: true ``` ### Loading config files Config files can be found and loaded with either the [`Configuration#loadConfigFromRoot()`][loadconfigfromroot] or [`Configuration#loadConfigFromBranchToRoot()`][loadconfigfrombranchtoroot] methods -- both of which return a processed config object that abides the [`ProcessedConfig`](/api/config/interface/ProcessedConfig) type. #### Lookup resolution When the finder traverses through the file system and attempts to resolve config files within each/target folder, it does so using the lookup algorithm demonstrated below. Let's assume the following: - The config file name is `boost`. - All file formats are supported, in their default lookup order (js, json, cjs, mjs, ts, json5, yaml, yml). - The current environment is `development` (the value of `NODE_ENV`). ``` boost.js boost.development.js boost.json boost.development.json boost.cjs boost.development.cjs boost.mjs boost.development.mjs boost.ts boost.development.ts boost.json5 boost.development.json5 boost.yaml boost.development.yaml boost.yml boost.development.yml ``` For each file format, we attempt to find the base config file, and an environment config file (if [`includeEnv`](#finder-options) is true). This allows for higher precendence config per environment. Once a file is found, the lookup process is aborted, and the confg is returned. > Only 1 file format will be used per folder. Multiple file formats is not supported. #### From root The [`Configuration#loadConfigFromRoot()`][loadconfigfromroot] will load the config file found in the root, either a `*.config.*` or `.config/*.*` file. If no root path is provided, it defaults to `process.cwd()`. ```json title="root/.config/boost.json" { "debug": true } ``` ```ts const { config } = await manager.loadConfigFromRoot('/root'); ``` ```js { config: { debug: true }, files: [ { config: { debug: true }, path: new Path('/root/.config/boost.json'), source: 'root', }, ], } ``` #### From branch The [`Configuration#loadConfigFromBranchToRoot()`][loadconfigfrombranchtoroot] method will load a config file from each folder while traversing upwards from the branch folder to the root folder. The found list is returned in reverse order so that the deepest branch can be used to overwrite the previous branch (or root). ```js title="root/modules/features/.boost.mjs" export default { ast: true, }; ``` ```yaml title="root/modules/.boost.yaml" options: experimental: true ``` ```json title="root/.config/boost.json" { "debug": true } ``` ```ts const { config } = await manager.loadConfigFromBranchToRoot('/root/modules/features'); ``` ```js { config: { ast: true, debug: true, options: { experimental: true, }, }, files: [ { config: { debug: true }, path: new Path('/root/.config/boost.json'), source: 'root', }, { config: { options: { experimental: true, }, }, path: new Path('/root/modules/.boost.yaml'), source: 'branch', }, { config: { ast: true }, path: new Path('/root/modules/features/.boost.mjs'), source: 'branch', }, ], }; ``` ### Enable extending Config extending enables consumers of your project to extend and merge with external config files using file system paths or [Node.js modules](#presets), with the current config file taking precedence. With that being said, extending is _not_ enabled by default and must be configured for use. To enable, define the [`extendsSetting`](#finder-options) option with the name of a setting in which extending would be configured. ```ts class Manager extends Configuration { // ... bootstrap() { this.configureFinder({ extendsSetting: 'extend', }); } } ``` Consumers may now extend external config files by defining a string or an array of strings for `extend` (name derived from the example above). ```ts export default { extend: ['./some/relative/path.js', 'npm-module'], debug: false, }; ``` > File paths are relative to the file it's configured in. #### Presets To extend from a Node.js module, we must use a preset. A preset is a [JavaScript config file](#file-formats) located in the module root, named in the format of `.preset.js`. ```ts title="npm-module/boost.preset.js" module.exports = { exclude: ['**/node_modules'], }; ``` > Since the preset is JavaScript, it can be written in either CommonJS or ECMAScript format, > assuming the `type` field has been set in `package.json`. ### Enable overrides Config overrides enables consumers of your project to define granular settings based on file path matching; settings defined in this fashion would override their base settings. With that being said, overrides are _not_ enabled by default and must be configured for use. To enable, define the [`overridesSetting`](#finder-options) option with the name of a setting in which overrides would be configured. ```ts class Manager extends Configuration { // ... bootstrap() { this.configureFinder({ overridesSetting: 'override', }); } } ``` > Overrides are extracted _before_ configurations are processed, so a process handler is not > required. Consumers may now define overrides in their config file by passing a list of items to the `override` setting (name derived from the example above). Each item must abide the [`OverridesSettingItem`](/api/config/interface/OverridesSettingItem) type. ```ts export default { debug: false, override: [ { include: '*.test.ts', settings: { debug: true, }, }, ], }; ``` ## Ignore files An ignore file is a standard text file that denotes files and folders to ignore (filter/exclude/etc), within the current directory, using matching globs and patterns. ### File patterns Both root and branch level ignore files use the same file naming scheme. The file is prefixed with a leading dot (`.`), followed by the name passed to your [`Configuration`][configuration] instance (in camel case), and suffixed with `ignore`. | Root | Branch | | --------------- | --------------- | | `.ignore` | `.ignore` | > The root ignore file is not located within the `.config` folder as ignore paths/patterns/globs > must be relative to the current directory. ### Loading ignore files Ignore files can be found and loaded with either the [`Configuration#loadIgnoreFromRoot()`][loadignorefromroot] or [`Configuration#loadIgnoreFromBranchToRoot()`][loadignorefrombranchtoroot] methods -- both of which return a list of ignore metadata that abide the [`IgnoreFile`](/api/config/interface/IgnoreFile) type. To demonstrate this, let's assume the following file system. ``` root/ ├── modules/ │ ├── features/ │ │ ├── index.ts │ │ └── .boostignore │ ├── foo.ts │ ├── bar.ts │ └── baz.ts └── .boostignore ``` ```bash title="root/modules/features/.boostignore" build/ ``` ```bash title="root/.boostignore" *.log *.lock ``` #### From root The [`Configuration#loadIgnoreFromRoot()`][loadignorefromroot] will load the ignore file found in the root folder (typically 1 file). If no root path is provided, it defaults to `process.cwd()`. ```ts const list = await manager.loadIgnoreFromRoot('/root'); ``` ```js [ { ignore: ['*.log', '*.lock'], path: new Path('/root/.boostignore'), source: 'root', }, ]; ``` #### From branch The [`Configuration#loadIgnoreFromBranchToRoot()`][loadignorefrombranchtoroot] method will load an ignore file from each folder while traversing upwards from the branch folder to the root folder. The found list is returned in reverse order so that the deepest branch can be used to overwrite the previous branch (or root). ```ts const list = await manager.loadIgnoreFromBranchToRoot('/root/modules/features'); ``` ```js [ { ignore: ['*.log', '*.lock'], path: new Path('/root'), source: 'root', }, { ignore: ['build/'], path: new Path('/root/modules/features/.boostignore'), source: 'branch', }, ]; ``` [esm]: https://nodejs.org/api/esm.html#esm_enabling [configuration]: /api/config/class/Configuration [loadconfigfromroot]: /api/config/class/Configuration#loadConfigFromRoot [loadconfigfrombranchtoroot]: /api/config/class/Configuration#loadConfigFromBranchToRoot [loadignorefromroot]: /api/config/class/Configuration#loadIgnoreFromRoot [loadignorefrombranchtoroot]: /api/config/class/Configuration#loadIgnoreFromBranchToRoot