--- /dev/null
+# cosmiconfig
+
+[](https://travis-ci.org/davidtheclark/cosmiconfig) [](https://ci.appveyor.com/project/davidtheclark/cosmiconfig/branch/master)
+
+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)
+
+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)
+
+cosmiconfig continues to search in these places all the way up the directory tree until it finds acceptable configuration (or hits the home directory).
+
+Additionally, all of these search locations are configurable: you can customize filenames or turn off any location.
+
+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.
+
+## Installation
+
+```
+npm install cosmiconfig
+```
+
+Tested in Node 4+.
+
+## Usage
+
+```js
+var cosmiconfig = require('cosmiconfig');
+
+var explorer = cosmiconfig(yourModuleName[, options]);
+
+explorer.load(yourSearchPath)
+ .then((result) => {
+ // result.config is the parsed configuration object
+ // result.filepath is the path to the config file that was found
+ })
+ .catch((parsingError) => {
+ // do something constructive
+ });
+```
+
+The function `cosmiconfig()` searches for a configuration object and returns a Promise,
+which resolves with an object containing the information you're looking for.
+
+You can also pass option `sync: true` to load the config synchronously, returning the config itself.
+
+So let's say `var yourModuleName = 'goldengrahams'` — here's how cosmiconfig will work:
+
+- 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).
+
+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.
+
+## Caching
+
+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.
+
+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.
+
+## API
+
+### `var explorer = cosmiconfig(moduleName[, options])`
+
+Creates a cosmiconfig instance (i.e. explorer) configured according to the arguments, and initializes its caches.
+
+#### moduleName
+
+Type: `string`
+
+You module name. This is used to create the default filenames that cosmiconfig will look for.
+
+#### Options
+
+##### packageProp
+
+Type: `string` or `false`
+Default: `'[moduleName]'`
+
+Name of the property in `package.json` to look for.
+
+If `false`, cosmiconfig will not look in `package.json` files.
+
+##### rc
+
+Type: `string` or `false`
+Default: `'.[moduleName]rc'`
+
+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
+
+Directory where the search will stop.
+
+##### cache
+
+Type: `boolean`
+Default: `true`
+
+If `false`, no caches will be used.
+
+##### sync
+
+Type: `boolean`
+Default: `false`
+
+If `true`, config will be loaded synchronously.
+
+##### transform
+
+Type: `Function`
+
+A function that transforms the parsed configuration. Receives the result object with `config` and `filepath` properties.
+
+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.
+
+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.
+
+##### configPath
+
+Type: `string`
+
+If provided, cosmiconfig will load and parse a config from this path, and will not perform its usual search.
+
+##### format
+
+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. Otherwise, use `searchPath`.
+
+```js
+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.
+
+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()`.
+
+## Differences from [rc](https://github.com/dominictarr/rc)
+
+[rc](https://github.com/dominictarr/rc) serves its focused purpose well. cosmiconfig differs in a few key ways — making it more useful for some projects, less useful for others:
+
+- Looks for configuration in some different places: in a `package.json` property, an rc file, a `.config.js` file, and rc files with extensions.
+- Built-in support for JSON, YAML, and CommonJS formats.
+- Stops at the first configuration found, instead of finding all that can be found up the directory tree and merging them automatically.
+- Options.
+- Asynchronous by default (though can be run synchronously).
+
+## 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.
+
+And please do participate!
projects / dotfiles / .git / blobdiff