or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcore-api.mdindex.mdloaders.md
tile.json

tessl/npm-cosmiconfig

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/cosmiconfig@8.3.x

To install, run

npx @tessl/cli install tessl/npm-cosmiconfig@8.3.0

index.mddocs/

Cosmiconfig

Cosmiconfig is a configuration loading library for JavaScript and TypeScript applications that provides intelligent configuration discovery and loading from multiple sources. It searches for configuration files in a variety of formats including package.json properties, RC files (JSON/YAML), JavaScript/TypeScript modules, and follows conventional filesystem patterns used across the JavaScript ecosystem.

Package Information

  • Package Name: cosmiconfig
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install cosmiconfig

Core Imports

import { cosmiconfig, cosmiconfigSync } from "cosmiconfig";

CommonJS:

const { cosmiconfig, cosmiconfigSync } = require("cosmiconfig");

Import loaders and types:

import { 
  cosmiconfig, 
  cosmiconfigSync,
  defaultLoaders,
  defaultLoadersSync,
  metaSearchPlaces,
  type Options,
  type CosmiconfigResult 
} from "cosmiconfig";

Basic Usage

import { cosmiconfig } from "cosmiconfig";

// Create an explorer for your tool
const explorer = cosmiconfig("myapp");

// Search for configuration starting from current directory
const result = await explorer.search();

if (result) {
  console.log("Found config:", result.config);
  console.log("Config file path:", result.filepath);
} else {
  console.log("No configuration found");
}

// Load a specific configuration file
const specificResult = await explorer.load("./myapp.config.js");

Synchronous usage:

import { cosmiconfigSync } from "cosmiconfig";

const explorerSync = cosmiconfigSync("myapp");
const result = explorerSync.search();

Architecture

Cosmiconfig is built around several key components:

  • Factory Functions: cosmiconfig() and cosmiconfigSync() create explorer instances
  • Explorer Pattern: Provides search() and load() methods with built-in caching
  • Flexible Loaders: Built-in support for JSON, YAML, JS, TS, and extensionless files
  • Smart Defaults: Conventional search patterns following JavaScript ecosystem standards
  • Customization: Extensive options for search locations, loaders, and transforms

Capabilities

Core API

Main factory functions and explorer methods for configuration discovery and loading.

function cosmiconfig(moduleName: string, options?: Options): PublicExplorer;
function cosmiconfigSync(moduleName: string, options?: OptionsSync): PublicExplorerSync;

interface PublicExplorer {
  search(searchFrom?: string): Promise<CosmiconfigResult>;
  load(filepath: string): Promise<CosmiconfigResult>;
  clearLoadCache(): void;
  clearSearchCache(): void;
  clearCaches(): void;
}

Core API

File Loaders

Built-in loader functions for different file formats with customization options.

function loadJson(filepath: string, content: string): LoaderResult;
function loadYaml(filepath: string, content: string): LoaderResult;
function loadJs(filepath: string, content: string): Promise<LoaderResult>;
function loadTs(filepath: string, content: string): Promise<LoaderResult>;

const defaultLoaders: Readonly<{
  '.mjs': Loader;
  '.cjs': Loader;
  '.js': Loader;
  '.ts': Loader;
  '.json': Loader;
  '.yaml': Loader;
  '.yml': Loader;
  noExt: Loader;
}>;

File Loaders

Configuration Options

Comprehensive configuration options for customizing search behavior, loaders, and transforms.

interface Options {
  packageProp?: string | Array<string>;
  searchPlaces?: Array<string>;
  ignoreEmptySearchPlaces?: boolean;
  stopDir?: string;
  cache?: boolean;
  loaders?: Loaders;
  transform?: Transform;
}

interface Transform {
  (result: CosmiconfigResult): Promise<CosmiconfigResult> | CosmiconfigResult;
}

Configuration Options

Types

Core types used throughout the API:

type CosmiconfigResult = {
  config: any;
  filepath: string;
  isEmpty?: boolean;
} | null;

type LoaderResult = any | null;

type Loader = (filepath: string, content: string) => Promise<LoaderResult> | LoaderResult;

type LoaderSync = (filepath: string, content: string) => LoaderResult;