nav tabs on admin dashboard
This commit is contained in:
+430
-161
@@ -1,23 +1,61 @@
|
||||
# cosmiconfig
|
||||
|
||||
[](https://travis-ci.org/davidtheclark/cosmiconfig) [](https://ci.appveyor.com/project/davidtheclark/cosmiconfig/branch/master)
|
||||
[](https://codecov.io/gh/davidtheclark/cosmiconfig)
|
||||
|
||||
Find and load a configuration object from
|
||||
- a `package.json` property (anywhere up the directory tree)
|
||||
- a JSON or YAML "rc file" (anywhere up the directory tree)
|
||||
- a `.config.js` CommonJS module (anywhere up the directory tree)
|
||||
Cosmiconfig searches for and loads configuration for your program.
|
||||
|
||||
For example, if your module's name is "soursocks," cosmiconfig will search out configuration in the following places:
|
||||
- a `soursocks` property in `package.json` (anywhere up the directory tree)
|
||||
- a `.soursocksrc` file in JSON or YAML format (anywhere up the directory tree)
|
||||
- a `soursocks.config.js` file exporting a JS object (anywhere up the directory tree)
|
||||
It features smart defaults based on conventional expectations in the JavaScript ecosystem.
|
||||
But it's also flexible enough to search wherever you'd like to search, and load whatever you'd like to load.
|
||||
|
||||
cosmiconfig continues to search in these places all the way up the directory tree until it finds acceptable configuration (or hits the home directory).
|
||||
By default, Cosmiconfig will start where you tell it to start and search up the directory tree for the following:
|
||||
|
||||
Additionally, all of these search locations are configurable: you can customize filenames or turn off any location.
|
||||
- a `package.json` property
|
||||
- a JSON or YAML, extensionless "rc file"
|
||||
- an "rc file" with the extensions `.json`, `.yaml`, `.yml`, or `.js`.
|
||||
- a `.config.js` CommonJS module
|
||||
|
||||
You can also look for rc files with extensions, e.g. `.soursocksrc.json` or `.soursocksrc.yaml`.
|
||||
You may like extensions on your rc files because you'll get syntax highlighting and linting in text editors.
|
||||
For example, if your module's name is "soursocks", cosmiconfig will search up the directory tree for configuration in the following places:
|
||||
|
||||
- a `soursocks` property in `package.json`
|
||||
- a `.soursocksrc` file in JSON or YAML format
|
||||
- a `.soursocksrc.json` file
|
||||
- a `.soursocksrc.yaml`, `.soursocksrc.yml`, or `.soursocksrc.js` file
|
||||
- a `soursocks.config.js` file exporting a JS object
|
||||
|
||||
Cosmiconfig continues to search up the directory tree, checking each of these places in each directory, until it finds some acceptable configuration (or hits the home directory).
|
||||
|
||||
👀 **Looking for the v4 docs?**
|
||||
v5 involves significant revisions to Cosmiconfig's API, allowing for much greater flexibility and clarifying some things.
|
||||
If you have trouble switching from v4 to v5, please file an issue.
|
||||
If you are still using v4, those v4 docs are available [in the `4.0.0` tag](https://github.com/davidtheclark/cosmiconfig/tree/4.0.0).
|
||||
|
||||
## Table of contents
|
||||
|
||||
- [Installation](#installation)
|
||||
- [Usage](#usage)
|
||||
- [Result](#result)
|
||||
- [cosmiconfig()](#cosmiconfig-1)
|
||||
- [moduleName](#modulename)
|
||||
- [explorer.search()](#explorersearch)
|
||||
- [searchFrom](#searchfrom)
|
||||
- [explorer.searchSync()](#explorersearchsync)
|
||||
- [explorer.load()](#explorerload)
|
||||
- [explorer.loadSync()](#explorerloadsync)
|
||||
- [explorer.clearLoadCache()](#explorerclearloadcache)
|
||||
- [explorer.clearSearchCache()](#explorerclearsearchcache)
|
||||
- [explorer.clearCaches()](#explorerclearcaches)
|
||||
- [cosmiconfigOptions](#cosmiconfigoptions)
|
||||
- [searchPlaces](#searchplaces)
|
||||
- [loaders](#loaders)
|
||||
- [packageProp](#packageprop)
|
||||
- [stopDir](#stopdir)
|
||||
- [cache](#cache)
|
||||
- [transform](#transform)
|
||||
- [ignoreEmptySearchPlaces](#ignoreemptysearchplaces)
|
||||
- [Caching](#caching)
|
||||
- [Differences from rc](#differences-from-rc)
|
||||
- [Contributing & Development](#contributing--development)
|
||||
|
||||
## Installation
|
||||
|
||||
@@ -29,202 +67,405 @@ Tested in Node 4+.
|
||||
|
||||
## Usage
|
||||
|
||||
Create a Cosmiconfig explorer, then either `search` for or directly `load` a configuration file.
|
||||
|
||||
```js
|
||||
var cosmiconfig = require('cosmiconfig');
|
||||
const cosmiconfig = require('cosmiconfig');
|
||||
// ...
|
||||
const explorer = cosmiconfig(moduleName);
|
||||
|
||||
var explorer = cosmiconfig(yourModuleName[, options]);
|
||||
|
||||
explorer.load()
|
||||
// Search for a configuration by walking up directories.
|
||||
// See documentation for search, below.
|
||||
explorer.search()
|
||||
.then((result) => {
|
||||
// result.config is the parsed configuration object
|
||||
// result.filepath is the path to the config file that was found
|
||||
// result.config is the parsed configuration object.
|
||||
// result.filepath is the path to the config file that was found.
|
||||
// result.isEmpty is true if there was nothing to parse in the config file.
|
||||
})
|
||||
.catch((parsingError) => {
|
||||
// do something constructive
|
||||
.catch((error) => {
|
||||
// Do something constructive.
|
||||
});
|
||||
|
||||
// Load a configuration directly when you know where it should be.
|
||||
// The result object is the same as for search.
|
||||
// See documentation for load, below.
|
||||
explorer.load(pathToConfig).then(..);
|
||||
|
||||
// You can also search and load synchronously.
|
||||
const searchedFor = explorer.searchSync();
|
||||
const loaded = explorer.loadSync(pathToConfig);
|
||||
```
|
||||
|
||||
The function `cosmiconfig()` searches for a configuration object and returns a Promise,
|
||||
which resolves with an object containing the information you're looking for.
|
||||
## Result
|
||||
|
||||
You can also pass option `sync: true` to load the config synchronously, returning the config itself.
|
||||
The result object you get from `search` or `load` has the following properties:
|
||||
|
||||
So let's say `var yourModuleName = 'goldengrahams'` — here's how cosmiconfig will work:
|
||||
- **config:** The parsed configuration object. `undefined` if the file is empty.
|
||||
- **filepath:** The path to the configuration file that was found.
|
||||
- **isEmpty:** `true` if the configuration file is empty. This property will not be present if the configuration file is not empty.
|
||||
|
||||
- Starting from `process.cwd()` (or some other directory defined by the `searchPath` argument to `load()`), it looks for configuration objects in three places, in this order:
|
||||
1. A `goldengrahams` property in a `package.json` file (or some other property defined by `options.packageProp`);
|
||||
2. A `.goldengrahamsrc` file with JSON or YAML syntax (or some other filename defined by `options.rc`);
|
||||
3. A `goldengrahams.config.js` JS file exporting the object (or some other filename defined by `options.js`).
|
||||
- If none of those searches reveal a configuration object, it moves up one directory level and tries again. So the search continues in `./`, `../`, `../../`, `../../../`, etc., checking those three locations in each directory.
|
||||
- It continues searching until it arrives at your home directory (or some other directory defined by `options.stopDir`).
|
||||
- If at any point a parseable configuration is found, the `cosmiconfig()` Promise resolves with its result object.
|
||||
- If no configuration object is found, the `cosmiconfig()` Promise resolves with `null`.
|
||||
- If a configuration object is found *but is malformed* (causing a parsing error), the `cosmiconfig()` Promise rejects and shares that error (so you should `.catch()` it).
|
||||
## cosmiconfig()
|
||||
|
||||
All this searching can be short-circuited by passing `options.configPath` to specify a file.
|
||||
cosmiconfig will read that file and try parsing it as JSON, YAML, or JS.
|
||||
```js
|
||||
const explorer = cosmiconfig(moduleName[, cosmiconfigOptions])
|
||||
```
|
||||
|
||||
## Caching
|
||||
Creates a cosmiconfig instance ("explorer") configured according to the arguments, and initializes its caches.
|
||||
|
||||
As of v2, cosmiconfig uses a few caches to reduce the need for repetitious reading of the filesystem. Every new cosmiconfig instance (created with `cosmiconfig()`) has its own caches.
|
||||
### moduleName
|
||||
|
||||
To avoid or work around caching, you can
|
||||
- create separate instances of cosmiconfig, or
|
||||
- set `cache: false` in your options.
|
||||
- use the cache clearing methods documented below.
|
||||
Type: `string`. **Required.**
|
||||
|
||||
## API
|
||||
Your module name. This is used to create the default [`searchPlaces`] and [`packageProp`].
|
||||
|
||||
### `var explorer = cosmiconfig(moduleName[, options])`
|
||||
**[`cosmiconfigOptions`] are documented below.**
|
||||
You may not need them, and should first read about the functions you'll use.
|
||||
|
||||
Creates a cosmiconfig instance (i.e. explorer) configured according to the arguments, and initializes its caches.
|
||||
## explorer.search()
|
||||
|
||||
#### moduleName
|
||||
```js
|
||||
explorer.search([searchFrom]).then(result => {..})
|
||||
```
|
||||
|
||||
Type: `string`
|
||||
Searches for a configuration file. Returns a Promise that resolves with a [result] or with `null`, if no configuration file is found.
|
||||
|
||||
You module name. This is used to create the default filenames that cosmiconfig will look for.
|
||||
You can do the same thing synchronously with [`searchSync()`].
|
||||
|
||||
#### Options
|
||||
Let's say your module name is `goldengrahams` so you initialized with `const explorer = cosmiconfig('goldengrahams');`.
|
||||
Here's how your default [`search()`] will work:
|
||||
|
||||
##### packageProp
|
||||
- Starting from `process.cwd()` (or some other directory defined by the `searchFrom` argument to [`search()`]), look for configuration objects in the following places:
|
||||
1. A `goldengrahams` property in a `package.json` file.
|
||||
2. A `.goldengrahamsrc` file with JSON or YAML syntax.
|
||||
3. A `.goldengrahamsrc.json` file.
|
||||
4. A `.goldengrahamsrc.yaml`, `.goldengrahamsrc.yml`, or `.goldengrahamsrc.js` file.
|
||||
5. A `goldengrahams.config.js` JS file exporting the object.
|
||||
- If none of those searches reveal a configuration object, move up one directory level and try again.
|
||||
So the search continues in `./`, `../`, `../../`, `../../../`, etc., checking the same places in each directory.
|
||||
- Continue searching until arriving at your home directory (or some other directory defined by the cosmiconfig option [`stopDir`]).
|
||||
- If at any point a parseable configuration is found, the [`search()`] Promise resolves with its [result] \(or, with [`searchSync()`], the [result] is returned).
|
||||
- If no configuration object is found, the [`search()`] Promise resolves with `null` (or, with [`searchSync()`], `null` is returned).
|
||||
- If a configuration object is found *but is malformed* (causing a parsing error), the [`search()`] Promise rejects with that error (so you should `.catch()` it). (Or, with [`searchSync()`], the error is thrown.)
|
||||
|
||||
Type: `string` or `false`
|
||||
Default: `'[moduleName]'`
|
||||
**If you know exactly where your configuration file should be, you can use [`load()`], instead.**
|
||||
|
||||
**The search process is highly customizable.**
|
||||
Use the cosmiconfig options [`searchPlaces`] and [`loaders`] to precisely define where you want to look for configurations and how you want to load them.
|
||||
|
||||
### searchFrom
|
||||
|
||||
Type: `string`.
|
||||
Default: `process.cwd()`.
|
||||
|
||||
A filename.
|
||||
[`search()`] will start its search here.
|
||||
|
||||
If the value is a directory, that's where the search starts.
|
||||
If it's a file, the search starts in that file's directory.
|
||||
|
||||
## explorer.searchSync()
|
||||
|
||||
```js
|
||||
const result = explorer.searchSync([searchFrom]);
|
||||
```
|
||||
|
||||
Synchronous version of [`search()`].
|
||||
|
||||
Returns a [result] or `null`.
|
||||
|
||||
## explorer.load()
|
||||
|
||||
```js
|
||||
explorer.load(loadPath).then(result => {..})
|
||||
```
|
||||
|
||||
Loads a configuration file. Returns a Promise that resolves with a [result] or rejects with an error (if the file does not exist or cannot be loaded).
|
||||
|
||||
Use `load` if you already know where the configuration file is and you just need to load it.
|
||||
|
||||
```js
|
||||
explorer.load('load/this/file.json'); // Tries to load load/this/file.json.
|
||||
```
|
||||
|
||||
If you load a `package.json` file, the result will be derived from whatever property is specified as your [`packageProp`].
|
||||
|
||||
## explorer.loadSync()
|
||||
|
||||
```js
|
||||
const result = explorer.loadSync(loadPath);
|
||||
```
|
||||
|
||||
Synchronous version of [`load()`].
|
||||
|
||||
Returns a [result].
|
||||
|
||||
## explorer.clearLoadCache()
|
||||
|
||||
Clears the cache used in [`load()`].
|
||||
|
||||
## explorer.clearSearchCache()
|
||||
|
||||
Clears the cache used in [`search()`].
|
||||
|
||||
## explorer.clearCaches()
|
||||
|
||||
Performs both [`clearLoadCache()`] and [`clearSearchCache()`].
|
||||
|
||||
## cosmiconfigOptions
|
||||
|
||||
Type: `Object`.
|
||||
|
||||
Possible options are documented below.
|
||||
|
||||
### searchPlaces
|
||||
|
||||
Type: `Array<string>`.
|
||||
Default: See below.
|
||||
|
||||
An array of places that [`search()`] will check in each directory as it moves up the directory tree.
|
||||
Each place is relative to the directory being searched, and the places are checked in the specified order.
|
||||
|
||||
**Default `searchPlaces`:**
|
||||
|
||||
```js
|
||||
[
|
||||
'package.json',
|
||||
`.${moduleName}rc`,
|
||||
`.${moduleName}rc.json`,
|
||||
`.${moduleName}rc.yaml`,
|
||||
`.${moduleName}rc.yml`,
|
||||
`.${moduleName}rc.js`,
|
||||
`${moduleName}.config.js`,
|
||||
]
|
||||
```
|
||||
|
||||
Create your own array to search more, fewer, or altogether different places.
|
||||
|
||||
Every item in `searchPlaces` needs to have a loader in [`loaders`] that corresponds to its extension.
|
||||
(Common extensions are covered by default loaders.)
|
||||
Read more about [`loaders`] below.
|
||||
|
||||
`package.json` is a special value: When it is included in `searchPlaces`, Cosmiconfig will always parse it as JSON and load a property within it, not the whole file.
|
||||
That property is defined with the [`packageProp`] option, and defaults to your module name.
|
||||
|
||||
Examples, with a module named `porgy`:
|
||||
|
||||
```js
|
||||
// Disallow extensions on rc files:
|
||||
[
|
||||
'package.json',
|
||||
'.porgyrc',
|
||||
'porgy.config.js'
|
||||
]
|
||||
|
||||
// ESLint searches for configuration in these places:
|
||||
[
|
||||
'.eslintrc.js',
|
||||
'.eslintrc.yaml',
|
||||
'.eslintrc.yml',
|
||||
'.eslintrc.json',
|
||||
'.eslintrc',
|
||||
'package.json'
|
||||
]
|
||||
|
||||
// Babel looks in fewer places:
|
||||
[
|
||||
'package.json',
|
||||
'.babelrc'
|
||||
]
|
||||
|
||||
// Maybe you want to look for a wide variety of JS flavors:
|
||||
[
|
||||
'porgy.config.js',
|
||||
'porgy.config.mjs',
|
||||
'porgy.config.ts',
|
||||
'porgy.config.coffee'
|
||||
]
|
||||
// ^^ You will need to designate custom loaders to tell
|
||||
// Cosmiconfig how to handle these special JS flavors.
|
||||
|
||||
// Look within a .config/ subdirectory of every searched directory:
|
||||
[
|
||||
'package.json',
|
||||
'.porgyrc',
|
||||
'.config/.porgyrc',
|
||||
'.porgyrc.json',
|
||||
'.config/.porgyrc.json'
|
||||
]
|
||||
```
|
||||
|
||||
### loaders
|
||||
|
||||
Type: `Object`.
|
||||
Default: See below.
|
||||
|
||||
An object that maps extensions to the loader functions responsible for loading and parsing files with those extensions.
|
||||
|
||||
Cosmiconfig exposes its default loaders for `.js`, `.json`, and `.yaml` as `cosmiconfig.loadJs`, `cosmiconfig.loadJson`, and `cosmiconfig.loadYaml`, respectively.
|
||||
|
||||
**Default `loaders`:**
|
||||
|
||||
```js
|
||||
{
|
||||
'.json': cosmiconfig.loadJson,
|
||||
'.yaml': cosmiconfig.loadYaml,
|
||||
'.yml': cosmiconfig.loadYaml,
|
||||
'.js': cosmiconfig.loadJs,
|
||||
noExt: cosmiconfig.loadYaml
|
||||
}
|
||||
```
|
||||
|
||||
(YAML is a superset of JSON; which means YAML parsers can parse JSON; which is how extensionless files can be either YAML *or* JSON with only one parser.)
|
||||
|
||||
**If you provide a `loaders` object, your object will be *merged* with the defaults.**
|
||||
So you can override one or two without having to override them all.
|
||||
|
||||
**Keys in `loaders`** are extensions (starting with a period), or `noExt` to specify the loader for files *without* extensions, like `.soursocksrc`.
|
||||
|
||||
**Values in `loaders`** are either a loader function (described below) or an object with `sync` and/or `async` properties, whose values are loader functions.
|
||||
|
||||
**The most common use case for custom loaders value is to load extensionless `rc` files as strict JSON**, instead of JSON *or* YAML (the default).
|
||||
To accomplish that, provide the following `loaders` value:
|
||||
|
||||
```js
|
||||
{
|
||||
noExt: cosmiconfig.loadJson
|
||||
}
|
||||
```
|
||||
|
||||
If you want to load files that are not handled by the loader functions Cosmiconfig exposes, you can write a custom loader function or use one from NPM if it exists.
|
||||
|
||||
**Third-party loaders:**
|
||||
|
||||
- [@endemolshinegroup/cosmiconfig-typescript-loader](https://github.com/EndemolShineGroup/cosmiconfig-typescript-loader)
|
||||
|
||||
**Use cases for custom loader function:**
|
||||
|
||||
- Allow configuration syntaxes that aren't handled by Cosmiconfig's defaults, like JSON5, INI, or XML.
|
||||
- Allow ES2015 modules from `.mjs` configuration files.
|
||||
- Parse JS files with Babel before deriving the configuration.
|
||||
|
||||
**Custom loader functions** have the following signature:
|
||||
|
||||
```js
|
||||
// Sync
|
||||
(filepath: string, content: string) => Object | null
|
||||
|
||||
// Async
|
||||
(filepath: string, content: string) => Object | null | Promise<Object | null>
|
||||
```
|
||||
|
||||
Cosmiconfig reads the file when it checks whether the file exists, so it will provide you with both the file's path and its content.
|
||||
Do whatever you need to, and return either a configuration object or `null` (or, for async-only loaders, a Promise that resolves with one of those).
|
||||
`null` indicates that no real configuration was found and the search should continue.
|
||||
|
||||
It's easiest if you make your custom loader function synchronous.
|
||||
Then it can be used regardless of whether you end up calling [`search()`] or [`searchSync()`], [`load()`] or [`loadSync()`].
|
||||
If you want or need to provide an async-only loader, you can do so by making the value of `loaders` an object with an `async` property whose value is the async loader.
|
||||
You can also add a `sync` property to designate a sync loader, if you want to use both async and sync search and load functions.
|
||||
|
||||
A few things to note:
|
||||
|
||||
- If you use a custom loader, be aware of whether it's sync or async and how that aligned with your usage of sync or async search and load functions.
|
||||
- **Special JS syntax can also be handled by using a `require` hook**, because `cosmiconfig.loadJs` just uses `require`.
|
||||
Whether you use custom loaders or a `require` hook is up to you.
|
||||
|
||||
Examples:
|
||||
|
||||
```js
|
||||
// Allow JSON5 syntax:
|
||||
{
|
||||
'.json': json5Loader
|
||||
}
|
||||
|
||||
// Allow XML, and treat sync and async separately:
|
||||
{
|
||||
'.xml': { async: asyncXmlLoader, sync: syncXmlLoader }
|
||||
}
|
||||
|
||||
// Allow a special configuration syntax of your own creation:
|
||||
{
|
||||
'.special': specialLoader
|
||||
}
|
||||
|
||||
// Allow many flavors of JS, using custom loaders:
|
||||
{
|
||||
'.mjs': esmLoader,
|
||||
'.ts': typeScriptLoader,
|
||||
'.coffee': coffeeScriptLoader
|
||||
}
|
||||
|
||||
// Allow many flavors of JS but rely on require hooks:
|
||||
{
|
||||
'.mjs': cosmiconfig.loadJs,
|
||||
'.ts': cosmiconfig.loadJs,
|
||||
'.coffee': cosmiconfig.loadJs
|
||||
}
|
||||
```
|
||||
|
||||
### packageProp
|
||||
|
||||
Type: `string`.
|
||||
Default: `` `${moduleName}` ``.
|
||||
|
||||
Name of the property in `package.json` to look for.
|
||||
|
||||
If `false`, cosmiconfig will not look in `package.json` files.
|
||||
Use periods to describe a path to nested properties. For example, the value `'configs.myPackage'` will get you the `"myPackage"` value in a `package.json` like this:
|
||||
|
||||
##### rc
|
||||
```json
|
||||
{
|
||||
"configs": {
|
||||
"myPackage": {..}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Type: `string` or `false`
|
||||
Default: `'.[moduleName]rc'`
|
||||
### stopDir
|
||||
|
||||
Name of the "rc file" to look for, which can be formatted as JSON or YAML.
|
||||
|
||||
If `false`, cosmiconfig will not look for an rc file.
|
||||
|
||||
If `rcExtensions: true`, the rc file can also have extensions that specify the syntax, e.g. `.[moduleName]rc.json`.
|
||||
You may like extensions on your rc files because you'll get syntax highlighting and linting in text editors.
|
||||
Also, with `rcExtensions: true`, you can use JS modules as rc files, e.g. `.[moduleName]rc.js`.
|
||||
|
||||
##### js
|
||||
|
||||
Type: `string` or `false`
|
||||
Default: `'[moduleName].config.js'`
|
||||
|
||||
Name of a JS file to look for, which must export the configuration object.
|
||||
|
||||
If `false`, cosmiconfig will not look for a JS file.
|
||||
|
||||
##### rcStrictJson
|
||||
|
||||
Type: `boolean`
|
||||
Default: `false`
|
||||
|
||||
If `true`, cosmiconfig will expect rc files to be strict JSON. No YAML permitted, and no sloppy JSON.
|
||||
|
||||
By default, rc files are parsed with [js-yaml](https://github.com/nodeca/js-yaml), which is
|
||||
more permissive with punctuation than standard strict JSON.
|
||||
|
||||
##### rcExtensions
|
||||
|
||||
Type: `boolean`
|
||||
Default: `false`
|
||||
|
||||
If `true`, cosmiconfig will look for rc files with extensions, in addition to rc files without.
|
||||
|
||||
This adds a few steps to the search process.
|
||||
Instead of *just* looking for `.goldengrahamsrc` (no extension), it will also look for the following, in this order:
|
||||
|
||||
- `.goldengrahamsrc.json`
|
||||
- `.goldengrahamsrc.yaml`
|
||||
- `.goldengrahamsrc.yml`
|
||||
- `.goldengrahamsrc.js`
|
||||
|
||||
##### stopDir
|
||||
|
||||
Type: `string`
|
||||
Default: Absolute path to your home directory
|
||||
Type: `string`.
|
||||
Default: Absolute path to your home directory.
|
||||
|
||||
Directory where the search will stop.
|
||||
|
||||
##### cache
|
||||
### cache
|
||||
|
||||
Type: `boolean`
|
||||
Default: `true`
|
||||
Type: `boolean`.
|
||||
Default: `true`.
|
||||
|
||||
If `false`, no caches will be used.
|
||||
Read more about ["Caching"](#caching) below.
|
||||
|
||||
##### sync
|
||||
### transform
|
||||
|
||||
Type: `boolean`
|
||||
Default: `false`
|
||||
Type: `(Result) => Promise<Result> | Result`.
|
||||
|
||||
If `true`, config will be loaded synchronously.
|
||||
A function that transforms the parsed configuration. Receives the [result].
|
||||
|
||||
##### transform
|
||||
If using [`search()`] or [`load()`] \(which are async), the transform function can return the transformed result or return a Promise that resolves with the transformed result.
|
||||
If using [`searchSync()`] or [`loadSync()`], the function must be synchronous and return the transformed result.
|
||||
|
||||
Type: `Function`
|
||||
The reason you might use this option — instead of simply applying your transform function some other way — is that *the transformed result will be cached*. If your transformation involves additional filesystem I/O or other potentially slow processing, you can use this option to avoid repeating those steps every time a given configuration is searched or loaded.
|
||||
|
||||
A function that transforms the parsed configuration. Receives the result object with `config` and `filepath` properties.
|
||||
### ignoreEmptySearchPlaces
|
||||
|
||||
If the option `sync` is `false` (default), the function must return a Promise that resolves with the transformed result.
|
||||
If the option `sync` is `true`, though, `transform` should be a synchronous function which returns the transformed result.
|
||||
Type: `boolean`.
|
||||
Default: `true`.
|
||||
|
||||
The reason you might use this option instead of simply applying your transform function some other way is that *the transformed result will be cached*. If your transformation involves additional filesystem I/O or other potentially slow processing, you can use this option to avoid repeating those steps every time a given configuration is loaded.
|
||||
By default, if [`search()`] encounters an empty file (containing nothing but whitespace) in one of the [`searchPlaces`], it will ignore the empty file and move on.
|
||||
If you'd like to load empty configuration files, instead, set this option to `false`.
|
||||
|
||||
##### configPath
|
||||
Why might you want to load empty configuration files?
|
||||
If you want to throw an error, or if an empty configuration file means something to your program.
|
||||
|
||||
Type: `string`
|
||||
## Caching
|
||||
|
||||
If provided, cosmiconfig will load and parse a config from this path, and will not perform its usual search.
|
||||
As of v2, cosmiconfig uses caching to reduce the need for repetitious reading of the filesystem or expensive transforms. Every new cosmiconfig instance (created with `cosmiconfig()`) has its own caches.
|
||||
|
||||
##### format
|
||||
To avoid or work around caching, you can do the following:
|
||||
|
||||
Type: `'json' | 'yaml' | 'js'`
|
||||
|
||||
The expected file format for the config loaded from `configPath`.
|
||||
|
||||
If not specified, cosmiconfig will try to infer the format using the extension name (if it has one).
|
||||
In the event that the file does not have an extension or the extension is unrecognized, cosmiconfig will try to parse it as a JSON, YAML, or JS file.
|
||||
|
||||
### Instance methods (on `explorer`)
|
||||
|
||||
#### `load([searchPath, configPath])`
|
||||
|
||||
Find and load a configuration file. Returns a Promise that resolves with `null`, if nothing is found, or an object with two properties:
|
||||
- `config`: The loaded and parsed configuration.
|
||||
- `filepath`: The filepath where this configuration was found.
|
||||
|
||||
You should provide *either* `searchPath` *or* `configPath`. Use `configPath` if you know the path of the configuration file you want to load. Note that `configPath` takes priority over `searchPath` if both parameters are specified.
|
||||
|
||||
```js
|
||||
explorer.load()
|
||||
|
||||
explorer.load('start/search/here');
|
||||
explorer.load('start/search/at/this/file.css');
|
||||
|
||||
explorer.load(null, 'load/this/file.json');
|
||||
```
|
||||
|
||||
If you provide `searchPath`, cosmiconfig will start its search at `searchPath` and continue to search up the directory tree, as documented above.
|
||||
By default, `searchPath` is set to `process.cwd()`.
|
||||
|
||||
If you provide `configPath` (i.e. you already know where the configuration is that you want to load), cosmiconfig will try to read and parse that file. Note that the [`format` option](#format) is applicable for this as well.
|
||||
|
||||
#### `clearFileCache()`
|
||||
|
||||
Clears the cache used when you provide a `configPath` argument to `load`.
|
||||
|
||||
#### `clearDirectoryCache()`
|
||||
|
||||
Clears the cache used when you provide a `searchPath` argument to `load`.
|
||||
|
||||
#### `clearCaches()`
|
||||
|
||||
Performs both `clearFileCache()` and `clearDirectoryCache()`.
|
||||
- Set the `cosmiconfig` option [`cache`] to `false`.
|
||||
- Use the cache-clearing methods [`clearLoadCache()`], [`clearSearchCache()`], and [`clearCaches()`].
|
||||
- Create separate instances of cosmiconfig (separate "explorers").
|
||||
|
||||
## Differences from [rc](https://github.com/dominictarr/rc)
|
||||
|
||||
@@ -238,6 +479,34 @@ Performs both `clearFileCache()` and `clearDirectoryCache()`.
|
||||
|
||||
## Contributing & Development
|
||||
|
||||
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
|
||||
Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
|
||||
|
||||
And please do participate!
|
||||
|
||||
[result]: #result
|
||||
|
||||
[`load()`]: #explorerload
|
||||
|
||||
[`loadsync()`]: #explorerloadsync
|
||||
|
||||
[`search()`]: #explorersearch
|
||||
|
||||
[`searchsync()`]: #explorersearchsync
|
||||
|
||||
[`clearloadcache()`]: #explorerclearloadcache
|
||||
|
||||
[`clearsearchcache()`]: #explorerclearsearchcache
|
||||
|
||||
[`clearcaches()`]: #explorerclearcaches
|
||||
|
||||
[`packageprop`]: #packageprop
|
||||
|
||||
[`cache`]: #cache
|
||||
|
||||
[`stopdir`]: #stopdir
|
||||
|
||||
[`searchplaces`]: #searchplaces
|
||||
|
||||
[`loaders`]: #loaders
|
||||
|
||||
[`cosmiconfigoptions`]: #cosmiconfigoptions
|
||||
|
||||
Reference in New Issue
Block a user