lilconfig

Lilconfig ⚙️

A zero-dependency alternative to cosmiconfig with the same API.

Installation

npm install lilconfig

Usage

import {lilconfig, lilconfigSync} from 'lilconfig';

// all keys are optional
const options = {
    stopDir: '/Users/you/some/dir',
    searchPlaces: ['package.json', 'myapp.conf.js'],
    ignoreEmptySearchPlaces: false
}

lilconfig(
    'myapp',
    options // optional
).search() // Promise<LilconfigResult>

lilconfigSync(
    'myapp',
    options // optional
).load(pathToConfig) // LilconfigResult

/**
 * LilconfigResult
 * {
 *   config: any; // your config
 *   filepath: string;
 * }
 */

ESM

ESM configs can be loaded with async API only. Specifically js files in projects with "type": "module" in package.json or mjs files.

Difference to cosmiconfig

Lilconfig does not intend to be 100% compatible with cosmiconfig but tries to mimic it where possible. The key difference is no support for YAML files out of the box(lilconfig attempts to parse files with no extension as JSON instead of YAML). You can still add the support for YAML files by providing a loader, see an example below.

Option difference between the two.

cosmiconfig option	lilconfig
cache	✅
loaders	✅
ignoreEmptySearchPlaces	✅
packageProp	✅
searchPlaces	✅
stopDir	✅
transform	✅

Loaders examples

Yaml loader

If you need the YAML support, you can provide your own loader

import {lilconfig} from 'lilconfig';
import yaml from 'yaml';

function loadYaml(filepath, content) {
    return yaml.parse(content);
}

const options = {
    loaders: {
        '.yaml': loadYaml,
        '.yml': loadYaml,
        // loader for files with no extension
        noExt: loadYaml
    }
};

lilconfig('myapp', options)
    .search()
    .then(result => {
        result // {config, filepath}
    });

Version correlation

• lilconfig v1 → cosmiconfig v6
• lilconfig v2 → cosmiconfig v7
• lilconfig v3 → cosmiconfig v8

Similar packages

Other packages similar to lilconfig

cosmiconfig

Cosmiconfig is a similar package that searches for and loads configuration files. It supports various file formats and has a larger feature set, including caching and transforming configurations. It is more widely used than lilconfig but is also more complex and heavier.

rc

The 'rc' package is another alternative that loads configuration from multiple sources, including command-line arguments, environment variables, and configuration files. It is less focused on file discovery and more on aggregating configuration from different sources.

config

The 'config' package is designed for managing configurations across different deployment environments. It is more opinionated and structured than lilconfig, with a predefined way of organizing configuration files based on the deployment environment.