Auto Config Loader

Find and load configuration from a package.json property, rc file, or CommonJS module. It has smart default based on traditional expectations in the JavaScript ecosystem. But it's also flexible enough to search anywhere you want and load whatever you want.

Features

Support JSON, JSONC, JSON5, YAML, TOML, INI, CJS, Typescript, and ESM config load.
Reads config from the nearest package.json file

Install

$ npm i auto-config-loader

Quick start

const autoConf = require('auto-config-loader');

import { autoConf } from 'auto-config-loader';

// will look for:
// process.cwd() + '.namespacerc'
// process.cwd() + '.namespacerc.js'
// process.cwd() + '.namespacerc.ts'
// process.cwd() + '.namespacerc.mjs'
// process.cwd() + '.namespacerc.cjs'
// process.cwd() + '.namespacerc.json'
// process.cwd() + '.namespacerc.json5'
// process.cwd() + '.namespacerc.jsonc'
// process.cwd() + '.namespacerc.yaml'
// process.cwd() + '.namespacerc.yml'
// process.cwd() + '.namespacerc.toml'
// process.cwd() + 'namespace.config.mjs'
// process.cwd() + 'namespace.config.cjs'
// process.cwd() + 'namespace.config.js'
// ........
const data = autoConf('namespace', {
  default: {
    testItem2: 'some value'
  }
});

Load JS

Load the JS file and return the result, support .js, .cjs, .mjs, .ts.

// => ./app/app.config.js
export default {
  name: 'app'
}

import { loadConf } from 'auto-config-loader/load-conf';

interface Config {
  name: string;
}

const result = loadConf<Config>('./app/app.config.js');
// => { name: 'app' }

Option

import { LoadConfOption } from 'auto-config-loader';
export type LoaderFunc<T> = (filepath: string, content: string, jsOption?: LoadConfOption) => T;
export type Loader<T> = Record<string, LoaderFunc<T>>;
export interface AutoConfOption<T> {
  searchPlaces?: string[];
  /** An object that maps extensions to the loader functions responsible for loading and parsing files with those extensions. */
  loaders?: Loader<T>;
  /** Specify default configuration. It has the lowest priority and is applied after extending config. */
  defaluts?: T;
  /** Resolve configuration from this working directory. The default is `process.cwd()` */
  cwd?: string;
  /** Default transform js configuration */
  jsOption?: LoadConfOption;
  /** @deprecated use `mustExist` instead */
  ignoreLog?: boolean;
  mustExist?: boolean;
}
/**
 * Find and load configuration from a `package.json` property, `rc` file, or `CommonJS` module.
 * @param namespace {string} Configuration base name. The default is `autoconf`.
 * @param option 
 */
export default function autoConf<T>(namespace?: string, option?: AutoConfOption<T>): {} & T;

Discover configurations in the specified directory order. When configuring a tool, you can use multiple file formats and put these in multiple places. Usually, a tool would mention this in its own README file, but by default, these are the following places, where ${moduleName} represents the name of the tool:

Default searchPlaces:

[
  'package.json',
  `.${moduleName}rc`,
  `.${moduleName}rc.json`,
  `.${moduleName}rc.json5`,
  `.${moduleName}rc.jsonc`,
  `.${moduleName}rc.yaml`,
  `.${moduleName}rc.yml`,
  `.${moduleName}rc.toml`,
  `.${moduleName}rc.ini`,
  `.${moduleName}rc.js`,
  `.${moduleName}rc.ts`,
  `.${moduleName}rc.cjs`,
  `.${moduleName}rc.mjs`,
  `.config/${moduleName}rc`,
  `.config/${moduleName}rc.json`,
  `.config/${moduleName}rc.json5`,
  `.config/${moduleName}rc.jsonc`,
  `.config/${moduleName}rc.yaml`,
  `.config/${moduleName}rc.yml`,
  `.config/${moduleName}rc.toml`,
  `.config/${moduleName}rc.ini`,
  `.config/${moduleName}rc.js`,
  `.config/${moduleName}rc.ts`,
  `.config/${moduleName}rc.cjs`,
  `.config/${moduleName}rc.mjs`,
  `${moduleName}.config.js`,
  `${moduleName}.config.ts`,
  `${moduleName}.config.cjs`,
  `${moduleName}.config.mjs`,
]

Configurations are loaded sequentially, and the configuration file search is terminated when a configuration file exists.

The content of these files is defined by the tool. For example, you can add a semi configuration value to false using a file called .config/autoconfig.yml:

semi: true

Additionally, you have the option to put a property named after the tool in your package.json file, with the contents of that property being the same as the file contents. To use the same example as above:

{
  "name": "your-project",
  "autoconfig": {
    "semi": true
  }
}

This has the advantage that you can put the configuration of all tools (at least the ones that use auto-config-loader) in one file.

Loader

`.js`,`.ts`,`.cjs`,`.mjs`

import type { JITIOptions } from 'jiti/dist/types';
import { Options } from 'sucrase';
export interface LoadConfOption {
  jiti?: boolean;
  jitiOptions?: JITIOptions;
  transformOption?: Options;
}
export declare function loadConf<T>(path: string, option?: LoadConfOption): T;
export declare function jsLoader<T>(filepath: string, content: string, option?: LoadConfOption): T;

Modify default .js,.ts,.cjs,.mjs loader parameters.

import load, { jsLoader } from 'auto-config-loader';

function loadJS(filepath, content) {
  return jsLoader(filepath, content, {
    // change option...
  });
}

const data = load('namespace', {
  loaders: {
    '.js': loadJS,
    '.ts': loadJS,
    '.cjs': loadJS,
    '.mjs': loadJS,
  },
  default: {
    testItem2: 'some value'
  }
});

example:

import { jsLoader } from 'auto-config-loader';

const data = jsLoader('/path/to/file/name.js')

`.ini`

export declare function iniLoader<T>(_: string, content: string): T;

example:

import { iniLoader } from 'auto-config-loader';

const data = iniLoader(undefined, `...`)

`.json`,`.jsonc`, `json5`

export declare function jsonLoader<T>(_: string, content: string): T;

example:

import { jsonLoader } from 'auto-config-loader';

const data = jsonLoader(undefined, `{ "a": 123 }`)

`.toml`

export declare function tomlLoader<T>(_: string, content: string): T;

example:

import { tomlLoader } from 'auto-config-loader';

const data = tomlLoader(undefined, `...`)

`.yaml`

export declare function yamlLoader<T>(_: string, content: string): T;

example:

import { yamlLoader } from 'auto-config-loader';

const data = yamlLoader(undefined, `...`)

Custom `Yaml` loader

This is an example, the default yaml/yml does not require a loader.

import load from 'auto-config-loader';
import yaml from 'yaml';

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

const data = load('namespace', {
  searchPlaces: [
    '.namespacerc.yaml',
    '.namespacerc.yml',
  ],
  loaders: {
    '.yaml': loadYaml,
    '.yml': loadYaml,
  },
  default: {
    testItem2: 'some value'
  }
});

Utils

merge

export declare const merge: {
  <TObject, TSource>(object: TObject, source: TSource): TObject & TSource;
  <TObject_1, TSource1, TSource2>(object: TObject_1, source1: TSource1, source2: TSource2): TObject_1 & TSource1 & TSource2;
  <TObject_2, TSource1_1, TSource2_1, TSource3>(object: TObject_2, source1: TSource1_1, source2: TSource2_1, source3: TSource3): TObject_2 & TSource1_1 & TSource2_1 & TSource3;
  <TObject_3, TSource1_2, TSource2_2, TSource3_1, TSource4>(object: TObject_3, source1: TSource1_2, source2: TSource2_2, source3: TSource3_1, source4: TSource4): TObject_3 & TSource1_2 & TSource2_2 & TSource3_1 & TSource4;
  (object: any, ...otherArgs: any[]): any;
};

findConfigFile

export declare function findConfigFile(moduleName: string, root: string, searchPlaces?: string[]): string;

getConfigPath

export declare const getConfigPath: () => string;

Example:

import { autoConf, getConfigPath } from 'auto-config-loader';

const data = autoConf<Config>('idoc');
const configPath = getConfigPath();
// => /.autoconfrc.js

cosmiconfig Find and load configuration from a package.json property, rc file, or CommonJS module
cjson Comments enabled json loader (Commented JavaScript Object Notation)
Config Loader Load user config files for node js projects.
Lilconfig Zero-dependency nodejs config seeker.
proload Searches for and loads your tool's JavaScript configuration files with full support for CJS, ESM, TypeScript and more.
rc The non-configurable configuration loader for lazy people.

Library	loaders	config ext
auto-config-loader	✅	`.js`, `.ts`, `.cjs`, `.mjs`, `.json`, `.jsonc`, `json5`, `.ini`, `.toml`, `.yaml` ++
cosmiconfig	✅	`.json`, `.yaml`, `.yml`, `.js`, `.mjs`, `.cjs`
rc	✅	`.json`, `.yaml`, `.yml`, `.js`, `.mjs`, `.cjs`
@proload/core	✅	`.js`, `.ts`, `.cjs`, `.mjs`, `.json`, `.jsonc`, `json5`, `.ini`, `.toml`, `.yaml` ++
lilconfig	✅	`.js`, `.cjs`, `.mjs`, `.json` ++
~~cjson~~	✅	`.json`
@web/config-loader	❌	`.js`, `.mjs`, `.cjs`