cosmiconfig

Find and load configuration from a package.json property, rc file, TypeScript module, and more!

weekly downloads85.5M

versionv9.0.0

licenseMIT

categorytoolchain

loadconfigurationconfig

Overview

Cosmiconfig is a configuration file discovery and loading library for Node.js applications. It implements the standard pattern of searching up the directory tree from the current working directory, looking for configuration in multiple formats: a property in package.json, RC files (.myapprc, .myapprc.json, .myapprc.yaml), and JavaScript/TypeScript modules (myapp.config.js, myapp.config.ts). It stops at the first valid configuration found, making config resolution predictable and aligned with how modern JavaScript tooling works.

The package exists because nearly every JavaScript tool needs to load user configuration, but implementing search logic, format parsing, and extensibility from scratch is repetitive and error-prone. Cosmiconfig provides a battle-tested solution with sensible defaults that match ecosystem conventions. With over 85 million weekly downloads, it powers critical tools across the JavaScript ecosystem including ESLint, Prettier, Babel, and hundreds of other CLI tools and libraries.

Under the hood, cosmiconfig handles JSON and YAML natively, supports CommonJS modules via require(), and allows custom loaders for formats like TypeScript, JSON5, or TOML. The API is deliberately minimal: create an explorer for your tool's name, then search() for config or load() a specific path. Both async and sync modes are supported, with async being the default to accommodate loaders that perform I/O or compilation.

Version 9.0.0 focuses on first-class TypeScript support and maintains a lean dependency tree (only 4 dependencies, ~124 kB). The library's stability and wide adoption make it the de facto standard for configuration loading in the JavaScript ecosystem, particularly for tools that need flexibility in where and how users define settings.

Quick Start

typescript

import { cosmiconfig } from 'cosmiconfig';

// Create explorer for 'myapp' - searches for .myapprc, myapp.config.js, etc.
const explorer = cosmiconfig('myapp', {
  searchPlaces: [
    'package.json',
    '.myapprc',
    '.myapprc.json',
    '.myapprc.yaml',
    '.myapprc.yml',
    'myapp.config.js',
    'myapp.config.cjs'
  ],
  stopDir: process.cwd() // Don't search above project root
});

// Search from current directory upward
const result = await explorer.search();

if (result) {
  console.log('Config found at:', result.filepath);
  console.log('Config contents:', result.config);
  // Example result.config: { apiKey: 'abc123', timeout: 5000 }
} else {
  console.log('No config found, using defaults');
}

// Or load from specific path
const specificConfig = await explorer.load('./config/custom.json');

// Sync version for tools that can't use async
import { cosmiconfigSync } from 'cosmiconfig';
const explorerSync = cosmiconfigSync('myapp');
const syncResult = explorerSync.search();

// Clear cache if config might change during runtime
explorer.clearCaches();

Use Cases

CLI tool configuration: A command-line tool like a linter or bundler uses cosmiconfig to discover user settings from .toolrc.json, tool.config.js, or a "tool" key in package.json, allowing users to choose their preferred format without the tool needing custom logic for each.

Plugin systems: A framework with plugins uses cosmiconfig to load configuration for each plugin, searching for plugin-specific config files (e.g., .babel-plugin-foorc) and merging them with defaults, enabling per-project customization of plugin behavior.

Monorepo tooling: A workspace management tool searches up from a package directory to find workspace-level configuration, stopping at the monorepo root, allowing shared settings across packages while respecting directory boundaries via stopDir option.

Build tools with TypeScript configs: A bundler or compiler uses cosmiconfig with TypeScript loader to support myapp.config.ts files, allowing users to write type-safe configuration with IDE autocomplete and import other TS modules for dynamic config generation.

Library initialization: A testing library or API client reads authentication or endpoint configuration from user's config files at runtime, checking standard locations (.librc, package.json) without requiring users to pass config programmatically or set environment variables.

Pros & Cons

Pros

+Zero-configuration defaults match ecosystem conventions, reducing setup code and providing familiar patterns for end users
+Extensible loader system supports any format (TypeScript, JSON5, TOML) while maintaining clean core dependencies
+Both async and sync APIs with smart caching prevent redundant file reads and parsing in performance-critical tools
+Stops at first found config (no merging) makes behavior predictable and debugging straightforward
+Massive ecosystem adoption means well-tested edge cases and compatibility with virtually all Node.js environments

Cons

−No automatic config merging across directory levels requires manual implementation if cascading configs are needed
−TypeScript config support requires separate loader package (cosmiconfig-typescript-loader) adding complexity and bundle size
−Directory traversal can be slow on deep filesystems with many parent directories, though caching mitigates repeated searches
−Error messages when config files have syntax errors can be cryptic depending on the loader, requiring users to manually validate JSON/YAML
−No built-in schema validation means tools must implement their own config validation layer on top of raw loaded data

Install

bash

npm install cosmiconfig

bash

pnpm add cosmiconfig

bash

bun add cosmiconfig

Overview

Quick Start

typescript

import { cosmiconfig } from 'cosmiconfig';

// Create explorer for 'myapp' - searches for .myapprc, myapp.config.js, etc.
const explorer = cosmiconfig('myapp', {
  searchPlaces: [
    'package.json',
    '.myapprc',
    '.myapprc.json',
    '.myapprc.yaml',
    '.myapprc.yml',
    'myapp.config.js',
    'myapp.config.cjs'
  ],
  stopDir: process.cwd() // Don't search above project root
});

// Search from current directory upward
const result = await explorer.search();

if (result) {
  console.log('Config found at:', result.filepath);
  console.log('Config contents:', result.config);
  // Example result.config: { apiKey: 'abc123', timeout: 5000 }
} else {
  console.log('No config found, using defaults');
}

// Or load from specific path
const specificConfig = await explorer.load('./config/custom.json');

// Sync version for tools that can't use async
import { cosmiconfigSync } from 'cosmiconfig';
const explorerSync = cosmiconfigSync('myapp');
const syncResult = explorerSync.search();

// Clear cache if config might change during runtime
explorer.clearCaches();

Use Cases

Pros & Cons

Pros

+Zero-configuration defaults match ecosystem conventions, reducing setup code and providing familiar patterns for end users
+Extensible loader system supports any format (TypeScript, JSON5, TOML) while maintaining clean core dependencies
+Both async and sync APIs with smart caching prevent redundant file reads and parsing in performance-critical tools
+Stops at first found config (no merging) makes behavior predictable and debugging straightforward
+Massive ecosystem adoption means well-tested edge cases and compatibility with virtually all Node.js environments

Cons

−No automatic config merging across directory levels requires manual implementation if cascading configs are needed
−TypeScript config support requires separate loader package (cosmiconfig-typescript-loader) adding complexity and bundle size
−Directory traversal can be slow on deep filesystems with many parent directories, though caching mitigates repeated searches
−Error messages when config files have syntax errors can be cryptic depending on the loader, requiring users to manually validate JSON/YAML
−No built-in schema validation means tools must implement their own config validation layer on top of raw loaded data