npm / cosmiconfig

cosmiconfig

What changed in cosmiconfig 6 to 10, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-23.

8 breaking3 new APIs and options1 performance3 behavior and defaults4 fixes and other

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

cosmiconfig 104 changes

The required Node.js version range is now ^22.18 || >=24, so projects must use a supported version.
10.0.0release notes
Node's type stripping replaces typescript; TypeScript 7 projects are supported, but non-erasable syntax such as namespace or enum is unsupported.
10.0.0release notes

JSON parsing now uses Node's JSON.parse directly instead of parse-json, so error messages come from Node.
10.0.0release notes
Config files encoded as UTF-16 are now supported.
10.0.0release notes

Meta config files such as config.js are now searched for in the .config subfolder rather than the current working directory.
9.0.0release notes
Without stopDir, the default is now none, so cosmiconfig searches only the current working directory; use global for maximum backwards compatibility.
9.0.0release notes

A special $import key imports another configuration file as a base whose properties can be overridden by the importing file.
9.0.0release notes
Users can set mergeSearchPlaces to false to prevent tool-defined searchPlaces from being merged into searchPlaces defined in a meta config file.
9.0.0release notes
Adds none, project, and global search strategies to control how cosmiconfig traverses directories.
9.0.0release notes

With searchStrategy set to global, cosmiconfig also searches OS conventional folders, including XDG-compatible folders on Linux, %APPDATA% on Windows, and Library/Preferences on macOS.
9.0.0release notes

Fixed an issue on Windows where a short CWD path could prevent cosmiconfig from loading ESM config files.
9.0.1release notes
Fixed a race condition that could prevent cosmiconfig from loading TypeScript config files when multiple instances exist simultaneously.
9.0.1release notes
Fixes an incorrect ERR_REQUIRE_ESM error when an issue occurs while loading an ESM file.
9.0.0release notes
Fixes a crash when loading a file that cannot be read because of file system permissions.
9.0.0release notes

The package now uses named exports, so import cosmiconfig with a named import.
6.0.0release notes
Create a sync explorer with cosmiconfigSync(); its search() and load() methods replace explorer.searchSync() and explorer.loadSync().
6.0.0release notes
A named export provides the default loaders for each extension, replacing cosmiconfig.loaders.
6.0.0release notes
Node 4 and 6 are no longer supported; Node 8 or later is required.
6.0.0release notes