cosmiconfig

• Fixed a prototype chain issue that may happen when merging different config objects.
• Fixed the project search strategy not correctly stopping at the package boundary.

• Fixed a race condition where multiple instances existing simultaneously could cause cosmiconfig to fail to load TypeScript config files.
• Fixed an issue on Windows where CWD being a short path (e.g. C:\Users\USERNA~1) would cause cosmiconfig to fail to load ESM config files.

• Added searchStrategy option:
  • The none value means that cosmiconfig does not traverse any directories upwards.
    • Breaking change: This is the default value if you don't pass a stopDir option, which means that cosmiconfig no longer traverses directories by default, and instead just looks in the current working directory.
      • If you want to achieve maximum backwards compatibility without adding an explicit stopDir, add the searchStrategy: 'global' option.
  • The project value means that cosmiconfig traverses upwards until it finds a package.json (or .yaml) file.
  • The global value means that cosmiconfig traverses upwards until the passed stopDir, or your home directory if no stopDir is given.
• Breaking change: Meta config files (i.e. config.js and similar) are not looked for in the current working directory anymore. Instead, it looks in the .config subfolder.
• Breaking change: When defining searchPlaces in a meta config file, the tool-defined searchPlaces are merged into this. Users may specify mergeSearchPlaces: false to disable this.
• Added support for a special $import key which will import another configuration file
  • The imported file will act as a base file - all properties from that file will be applied to the configuration, but can be overridden by the importing file
  • For more information, read the import section of the README
• Added searching in OS conventional folders (XDG compatible on Linux, %APPDATA% on Windows, Library/Preferences on macOS) for searchStrategy: 'global'
• Fixed crash when trying to load a file that is not readable due to file system permissions
• Fixed wrong ERR_REQUIRE_ESM error being thrown when there is an issue loading an ESM file

8.3.6 (2023-09-13)

Bug Fixes

• ignore search place if accessing it causes ENOTDIR (i.e. if access of a subpath of a file is attempted) (5bd915a)

8.3.5 (2023-09-08)

Bug Fixes

• pass null to transform function for backwards compat (2b38510)

8.3.4 (2023-09-04)

Bug Fixes

• remove node: prefix from imports (f76484a), closes #323

8.3.3 (2023-09-03)

Bug Fixes

• add back node 14 compat (7392541), closes #320

8.3.2 (2023-09-02)

Bug Fixes

• use .cjs extension for sync compiled typescript (0d76a9a)
• use default for async TS loader (5bed3e3)

8.3.1 (2023-09-02)

Bug Fixes

• do not resolve stopDir when undefined (59082e2), closes #317

8.3.0 (2023-09-02)

Features

• add support for TypeScript configuration files (d88b1b4)

• Add support for ECMAScript modules (ESM) to the asynchronous API. End users running Node versions that support ESM can provide .mjs files, or .js files whose nearest parent package.json file contains "type": "module".
  • ${moduleName}rc.mjs and ${moduleName}.config.mjs are included in the default searchPlaces of the asynchronous API.
  • The synchronous API does not support ECMAScript modules, so does not look for .mjs files.
  • To learn more, read "Loading JS modules".

• Fixed: existence of meta config breaking default loaders

• Fixed: generation of TypeScript types going to the wrong output path

• Fixed: meta config overriding original options completely (now merges correctly)

• Added: always look at .config.{yml,yaml,json,js,cjs} file to configure cosmiconfig itself, and look for tool configuration in it using packageProp (similar to package.json)
  • For more info on this, look at the end user configuration section of the README

No major breaking changes! We dropped support for Node 10 and 12 -- which you're probably not using. And we swapped out the YAML parser -- which you probably won't notice.

• Breaking change: Drop support for Node 10 and 12.

• Breaking change: Use npm package js-yaml to parse YAML instead of npm package yaml.

• Added: Loader errors now include the path of the file that was tried to be loaded.

• Added: Additional default searchPlaces within a .config subdirectory (without leading dot in the file name)

• Fixed: If there was a directory that had the same name as a search place (e.g. "package.json"), we would try to read it as a file, which would cause an exception.

• Breaking change: Add ${moduleName}rc.cjs and ${moduleName}.config.cjs to the default searchPlaces, to support users of "type": "module" in recent versions of Node.
• Breaking change: Drop support for Node 8. Now requires Node 10+.

• Breaking change: The package now has named exports. See examples below.

• Breaking change: Separate async and sync APIs, accessible from different named exports. If you used 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');
  

• Breaking change: Remove support for Node 4 and 6. Requires Node 8+.

• Breaking change: Use npm package yaml to parse YAML instead of npm package js-yaml.

• Breaking change: Remove 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] ]
  // ]
  

• Migrate from Flowtype to Typescript.

• Lazy load all default loaders.

• Chore: Upgrade js-yaml to avoid npm audit warning.

• Added: 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.)
• Chore: Replaced the lodash.get dependency with a locally defined function.
• Chore: Upgrade js-yaml to avoid npm audit warning.

• Added: packageProp values can include periods to describe paths to nested objects within package.json.

• Fixed: JS loader bypasses Node's require cache, fixing a bug where updates to .js config files would not load even when Cosmiconfig was told not to cache.

• Fixed: Better error message if the end user tries an extension Cosmiconfig is not configured to understand.

• Fixed: load and loadSync work with paths relative to process.cwd().

• Fixed: rc files with .js extensions included in default searchPlaces.

• Docs: Minor corrections to documentation. Released to update package documentation on npm.

• Fixed: Allow 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.

• The 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.
• The searchPlaces option allows you to specify exactly where cosmiconfig looks within each directory it searches.
• The combination of 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.
• The 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:

• The default JS loader uses 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.
• The options rc, js, and rcExtensions have all been removed. You can accomplish the same and more with searchPlaces.
• The default 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.
• The option 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.
• By default, empty files are ignored by search(). The new option ignoreEmptySearchPlaces allows you to load them, instead, in case you want to do something with empty files.
• The option configPath has been removed. Just pass your filepaths directory to load().
• Removed the 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.)

• Licensing improvement: updated parse-json from 3.0.0 to 4.0.0(see [sindresorhus/parse-json#12][parse-json-pr-12]).
• Changed: error message format for JSON parse errors(see [#101][pr-101]). If you were relying on the format of JSON-parsing error messages, this will be a breaking change for you.
• Changed: set default for searchPath as process.cwd() in explorer.load.

• Added: infer format based on filePath

• Fixed: memory leak due to bug in require-from-string.
• Added: for JSON files, append position to end of error message.

• Removed: support for loading config path using the --config flag. cosmiconfig will not parse command line arguments. Your application can parse command line arguments and pass them to cosmiconfig.
• Removed: argv config option.
• Removed: support for Node versions < 4.
• Added: sync option.
• Fixed: Throw a clear error on getting empty config file.
• Fixed: when a options.configPath is package.json, return the package prop, not the entire JSON file.

• Fixed: options.configPath and --config flag are respected.

• 2.2.0 included a number of improvements but somehow broke stylelint. The changes were reverted in 2.2.1, to be restored later.

• Licensing improvement: switched from json-parse-helpfulerror to parse-json.

• Fixed: bug where an ENOENT error would be thrown is searchPath referenced a non-existent file.
• Fixed: JSON parsing errors in Node v7.

• Fixed: swapped graceful-fs for regular fs, fixing a garbage collection problem.

• Added: Node 0.12 support.

• Fixed: Node version specified in package.json.

• Fixed: no more infinite loop in Windows.

• Changed: module now creates cosmiconfig instances with load methods (see README).
• Added: caching (enabled by the change above).
• Removed: support for Node versions <4.

• Add rcExtensions option.

• Fix handling of require()'s within JS module configs.

• Switch Promise implementation to pinkie-promise.

• Initial release.