cosmiconfig

Cosmiconfig searches for and loads configuration for a program using the conventions the JavaScript ecosystem has settled on: a property in package.json, an extensionless or extensioned rc file, or a <module>.config.{js,ts,mjs,cjs} file, optionally nested inside a .config subdirectory. It’s the same search-and-load engine that powers tools like Prettier, ESLint, and Stylelint’s own config resolution.

Both asynchronous and synchronous APIs are available, along with a highly customizable configuration surface — custom search places, custom loaders for arbitrary file extensions, transform hooks, and configurable search strategies (search only the current directory, walk up to the nearest package.json, or walk all the way to the home directory and OS config directory).

What You Get

• Async (cosmiconfig()) and sync (cosmiconfigSync()) explorer APIs with matching .search()/.load() methods
• Default search across package.json properties, rc files (JSON/YAML/JS/TS/mjs/cjs), .config subdirectory files, and <name>.config.* files
• Three configurable search strategies: none (cwd only), project (up to nearest package.json), and global (up to home dir plus OS config dir)
• Custom loaders for arbitrary file extensions and a transform hook for post-processing loaded config
• Built-in load/search caching with explicit cache-clearing methods for long-running processes

Common Use Cases

• Letting a CLI tool’s users configure it via .toolrc, tool.config.js, or a tool key in package.json
• Building linters, formatters, or build tools that need conventional, zero-config-by-default config discovery
• Supporting multiple config file formats (JSON, YAML, JS, TS) without writing custom parsing logic per format
• Walking a monorepo directory tree to find the nearest applicable configuration file

Under The Hood

Architecture — src/ExplorerBase.ts implements shared state (caches, search-place resolution) that src/Explorer.ts (async) and src/ExplorerSync.ts (sync) both extend, keeping the two API surfaces behaviorally identical while allowing genuinely synchronous file I/O for the sync variant. src/loaders.ts maps file extensions to parser functions (JSON, YAML, and dynamic import()/require() for JS/TS), src/defaults.ts computes the default search-places list from the module name, and src/index.ts wires everything into the two public factory functions.

Tech Stack — Written entirely in TypeScript, targeting Node 14+, built with Vite (vite.config.ts) and tested with the accompanying test runner. Runtime dependencies are minimal and dependency-lean (a YAML parser, an import-resolution helper, and env-paths for OS-specific config directories) — no heavyweight parsing frameworks.

Code Quality — The test/ directory is organized by concern (successful-files, failed-files, successful-directories, caches, search-strategies, meta-config, etc.), giving clear coverage of both the happy path and error/edge cases like malformed configs and missing files. Code-coverage is tracked via Codecov (badge in the README), and the codebase has been incrementally hardened over nearly a decade of production use by major tools.

API Design — The API is intentionally narrow: one factory function per mode (cosmiconfig/cosmiconfigSync), each returning an explorer with just search()/load()/cache-clearing methods. Defaults are inferred entirely from the single required moduleName argument, so a tool author gets working config discovery with one line of code, while cosmiconfigOptions (searchPlaces, loaders, searchStrategy, transform, stopDir) let advanced users override every behavior individually.