cosmiconfig

Cosmiconfig searches for and loads configuration for your program.

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.

By default, Cosmiconfig will check the current directory for the following:

• a package.json property
• a JSON or YAML, extensionless "rc file"
• an "rc file" with the extensions .json, .yaml, .yml, .js, .ts, .mjs, or .cjs
• any of the above two inside a .config subdirectory
• a .config.js, .config.ts, .config.mjs, or .config.cjs file

For example, if your module's name is "myapp", cosmiconfig will search up the directory tree for configuration in the following places:

• a myapp property in package.json
• a .myapprc file in JSON or YAML format
• a .myapprc.json, .myapprc.yaml, .myapprc.yml, .myapprc.js, .myapprc.ts, .myapprc.mjs, or .myapprc.cjs file
• a myapprc, myapprc.json, myapprc.yaml, myapprc.yml, myapprc.js, myapprc.ts, myapprc.mjs, or myapprc.cjs file inside a .config subdirectory
• a myapp.config.js, myapp.config.ts, myapp.config.mjs, or myapp.config.cjs file

Optionally, you can tell it to search up the directory tree using [search strategies], checking each of these places in each directory, until it finds some acceptable configuration (or hits the home directory).

Table of contents

• Installation
• Usage for tooling developers
• Result
• Asynchronous API
• cosmiconfig()
• explorer.search()
• explorer.load()
• explorer.clearLoadCache()
• explorer.clearSearchCache()
• explorer.clearCaches()
• Synchronous API
• cosmiconfigSync()
• explorerSync.search()
• explorerSync.load()
• explorerSync.clearLoadCache()
• explorerSync.clearSearchCache()
• explorerSync.clearCaches()
• cosmiconfigOptions
• searchStrategy
• searchPlaces
• loaders
• packageProp
• stopDir
• cache
• transform
• ignoreEmptySearchPlaces
• Loading JS modules
• Caching
• Differences from rc
• Usage for end users
• Imports
• Contributing & Development

Installation

npm install cosmiconfig

Tested in Node 14+.

Usage for tooling developers

If you are an end user (i.e. a user of a tool that uses cosmiconfig, like prettier or stylelint), you can skip down to the end user section.

Create a Cosmiconfig explorer, then either search for or directly load a configuration file.

const { cosmiconfig, cosmiconfigSync } = require('cosmiconfig');
// ...
const explorer = cosmiconfig(moduleName);

// 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.isEmpty is true if there was nothing to parse in the config file.
  })
  .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 explorerSync = cosmiconfigSync(moduleName);

const searchedFor = explorerSync.search();
const loaded = explorerSync.load(pathToConfig);

Result

The result object you get from search or load has the following properties:

• 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.

Asynchronous API

cosmiconfig()

const { cosmiconfig } = require('cosmiconfig');
const explorer = cosmiconfig(moduleName, /* optional */ cosmiconfigOptions)

Creates a cosmiconfig instance ("explorer") configured according to the arguments, and initializes its caches.

moduleName

Type: string. Required.

Your module name. This is used to create the default [searchPlaces] and [packageProp].

If your [searchPlaces] value will include files, as it does by default (e.g. ${moduleName}rc), your moduleName must consist of characters allowed in filenames. That means you should not copy scoped package names, such as @my-org/my-package, directly into moduleName.

[cosmiconfigOptions] are documented below. You may not need them, and should first read about the functions you'll use.

explorer.search()

explorer.search([searchFrom]).then(result => { /* ... */ })

Searches for a configuration file. Returns a Promise that resolves with a [result] or with null, if no configuration file is found.

You can do the same thing synchronously with [explorerSync.search()].

Let's say your module name is goldengrahams so you initialized with const explorer = cosmiconfig('goldengrahams');. Here's how your default [search()] will work:

• Starting from process.cwd() (or some other directory defined by the searchFrom argument to [search()]), look for configuration objects in the following places:
• A goldengrahams property in a package.json file.
• A .goldengrahamsrc file with JSON or YAML syntax.
• A .goldengrahamsrc.json, .goldengrahamsrc.yaml, .goldengrahamsrc.yml, .goldengrahamsrc.js, .goldengrahamsrc.ts, .goldengrahamsrc.mjs, or .goldengrahamsrc.cjs file. (To learn more about how JS files are loaded, see ["Loading JS modules"].)
• A goldengrahamsrc, goldengrahamsrc.json, goldengrahamsrc.yaml, goldengrahamsrc.yml, goldengrahamsrc.js, goldengrahamsrc.ts, goldengrahamsrc.mjs, or goldengrahamsrc.cjs file in the .config subdirectory.
• A goldengrahams.config.js, goldengrahams.config.ts, goldengrahams.config.mjs, or goldengrahams.config.cjs file. (To learn more about how JS files are loaded, see ["Loading JS modules"].)
• If none of those searches reveal a configuration object, continue depending on the current search strategy:
• If it's none (which is the default if you don't specify a [stopDir] option), stop here and return/resolve with null.
• If it's global (which is the default if you specify a [stopDir] option), move up one directory level and try again, recursing until arriving at the configured [stopDir] option, which defaults to the user's home directory.
  • After arriving at the [stopDir], the global configuration directory (as defined by [env-paths] without prefix) is also checked, looking at the files config, config.json, config.yaml, config.yml, config.js, config.ts, config.cjs, and config.mjs in the directory ~/.config/goldengrahams/ (on Linux; see [env-paths] documentation for other OSs).
• If it's project, check whether a package.json file is present in the current directory, and if not, move up one directory level and try again, recursing until there is one.
• If at any point a parsable configuration is found, the [search()] Promise resolves with its [result] (or, with [explorerSync.search()], the [result] is returned).
• If no configuration object is found, the [search()] Promise resolves with null (or, with [explorerSync.search()], 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 [explorerSync.search()], the error is thrown.)

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.load()

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.

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]. package.yaml will work as well if you specify these file names in your [searchPlaces].

You can do the same thing synchronously with [explorerSync.load()].

explorer.clearLoadCache()

Clears the cache used in [load()].

explorer.clearSearchCache()

Clears the cache used in [search()].

explorer.clearCaches()

Performs both [clearLoadCache()] and [clearSearchCache()].

Synchronous API

cosmiconfigSync()

const { cosmiconfigSync } = require('cosmiconfig');
const explorerSync = cosmiconfigSync(moduleName, /* optional */ cosmiconfigOptions)

Creates a synchronous cosmiconfig instance ("explorerSync") configured according to the arguments, and initializes its caches.

See cosmiconfig().

explorerSync.search()

const result = explorerSync.search([searchFrom]);

Synchronous version of [explorer.search()].

Returns a [result] or null.

explorerSync.load()

const result = explorerSync.load(loadPath);

Synchronous version of [explorer.load()].

Returns a [result].

explorerSync.clearLoadCache()

Clears the cache used in [load()].

explorerSync.clearSearchCache()

Clears the cache used in [search()].

explorerSync.clearCaches()

Performs both [clearLoadCache()] and [clearSearchCache()].

cosmiconfigOptions

Type: Object.

Possible options are documented below.

searchStrategy

Type: string Default: global if [stopDir] is specified, none otherwise.

The strategy that should be used to determine which directories to check for configuration files.

• none: Only checks in the current working directory.
• project: Starts in the current working directory, traversing upwards until a package.{json,yaml} file is found.
• global: Starts in the current working directory, traversing upwards until the configured [stopDir] (or the current user's home directory if none is given). Then, if no configuration is found, also look in the operating system's default configuration directory (according to [env-paths] without prefix), where a different set of file names is checked:

[
  `config`,
  `config.json`,
  `config.yaml`,
  `config.yml`,
  `config.js`,
  `config.ts`,
  `config.cjs`,
  `config.mjs`
]

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:

For the asynchronous API, these are the default searchPlaces:

[
  'package.json',
  `.${moduleName}rc`,
  `.${moduleName}rc.json`,
  `.${moduleName}rc.yaml`,
  `.${moduleName}rc.yml`,
  `.${moduleName}rc.js`,
  `.${moduleName}rc.ts`,
  `.${moduleName}rc.mjs`,
  `.${moduleName}rc.cjs`,
  `.config/${moduleName}rc`,
  `.config/${moduleName}rc.json`,
  `.config/${moduleName}rc.yaml`,
  `.config/${moduleName}rc.yml`,
  `.config/${moduleName}rc.js`,
  `.config/${moduleName}rc.ts`,
  `.config/${moduleName}rc.mjs`,
  `.config/${moduleName}rc.cjs`,
  `${moduleName}.config.js`,
  `${moduleName}.config.ts`,
  `${moduleName}.config.mjs`,
  `${moduleName}.config.cjs`,
];

For the synchronous API, the only difference is that .mjs files are not included. See ["Loading JS modules"] for more information.

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.

package.yaml (used by pnpm) works the same way.

Examples, with a module named porgy:

// Disallow extensions on rc files:
['package.json', '.porgyrc', 'porgy.config.js']

// Limit the options dramatically:
['package.json', '.porgyrc']

```js // 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 a custom loader to tell // Cosmic