${moduleName}rc.cjs
and ${moduleName}.config.cjs
to the default searchPlaces
, to support users of "type": "module"
in recent versions of Node.explorer.searchSync()
or explorer.loadSync()
, you'll now create a sync explorer with cosmiconfigSync()
, then use explorerSync.search()
and explorerSync.load()
. // OLD: cosmiconfig v5
import cosmiconfig from 'cosmiconfig';
const explorer = cosmiconfig('example');
const searchAsyncResult = await explorer.search();
const loadAsyncResult = await explorer.load('./file/to/load');
const searchSyncResult = explorer.searchSync();
const loadSyncResult = explorer.loadSync('./file/to/load');
// NEW: cosmiconfig v6
import { cosmiconfig, cosmiconfigSync } from 'cosmiconfig';
const explorer = cosmiconfig('example');
const searchAsyncResult = await explorer.search();
const loadAsyncResult = await explorer.load('./file/to/load');
const explorerSync = cosmiconfigSync('example');
const searchSyncResult = explorerSync.search();
const loadSyncResult = explorerSync.load('./file/to/load');
cosmiconfig.loaders
and add named export defaultLoaders
that exports the default loaders used for each extension. import { defaultLoaders } from 'cosmiconfig';
console.log(Object.entries(defaultLoaders))
// [
// [ '.js', [Function: loadJs] ],
// [ '.json', [Function: loadJson] ],
// [ '.yaml', [Function: loadYaml] ],
// [ '.yml', [Function: loadYaml] ],
// [ 'noExt', [Function: loadYaml] ]
// ]
js-yaml
to avoid npm audit warning.packageProp
values can be arrays of strings, to allow for property names that include periods. (This was possible before, but not documented or deliberately supported.)lodash.get
dependency with a locally defined function.js-yaml
to avoid npm audit warning.packageProp
values can include periods to describe paths to nested objects within package.json
.require
cache, fixing a bug where updates to .js
config files would not load even when Cosmiconfig was told not to cache.load
and loadSync
work with paths relative to process.cwd()
.rc
files with .js
extensions included in default searchPlaces
.searchSync
and loadSync
to load JS configuration files whose export is a Promise.The API has been completely revamped to increase clarity and enable a very wide range of new usage. Please read the readme for all the details.
While the defaults remain just as useful as before — and you can still pass no options at all — now you can also do all kinds of wild and crazy things.
loaders
option allows you specify custom functions to derive config objects from files. Your loader functions could parse ES2015 modules or TypeScript, JSON5, even INI or XML. Whatever suits you.searchPlaces
option allows you to specify exactly where cosmiconfig looks within each directory it searches.loaders
and searchPlaces
means that you should be able to load pretty much any kind of configuration file you want, from wherever you want it to look.Additionally, the overloaded load()
function has been split up into several clear and focused functions:
search()
now searches up the directory tree, and load()
loads a configuration file that you don't need to search for.sync
option has been replaced with separate synchronous functions: searchSync()
and loadSync()
.clearFileCache()
and clearDirectoryCache()
have been renamed to clearLoadCache()
and clearSearchPath()
respectively.More details:
require
, instead of require-from-string
. So you could use require
hooks to control the loading of JS files (e.g. pass them through esm or Babel). In most cases it is probably preferable to use a custom loader.rc
, js
, and rcExtensions
have all been removed. You can accomplish the same and more with searchPlaces
.searchPlaces
include rc
files with extensions, e.g. .thingrc.json
, .thingrc.yaml
, .thingrc.yml
. This is the equivalent of switching the default value of the old rcExtensions
option to true
.rcStrictJson
has been removed. To get the same effect, you can specify noExt: cosmiconfig.loadJson
in your loaders
object.packageProp
no longer accepts false
. If you don't want to look in package.json
, write a searchPlaces
array that does not include it.search()
. The new option ignoreEmptySearchPlaces
allows you to load them, instead, in case you want to do something with empty files.configPath
has been removed. Just pass your filepaths directory to load()
.format
option. Formats are now all handled via the file extensions specified in loaders
.(If you're wondering with happened to 5.0.0 ... it was a silly publishing mistake.)
parse-json
from 3.0.0
to 4.0.0
(see sindresorhus/parse-json#12).JSON
parse errors(see #101). If you were relying on the format of JSON-parsing error messages, this will be a breaking change for you.searchPath
as process.cwd()
in explorer.load
.require-from-string
.--config
flag. cosmiconfig will not parse command line arguments. Your application can parse command line arguments and pass them to cosmiconfig.argv
config option.sync
option.options.configPath
is package.json
, return the package prop, not the entire JSON file.options.configPath
and --config
flag are respected.json-parse-helpfulerror
to parse-json
.ENOENT
error would be thrown is searchPath
referenced a non-existent file.graceful-fs
for regular fs
, fixing a garbage collection problem.package.json
.load
methods (see README).rcExtensions
option.require()
's within JS module configs.