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.

V1 To V2 Migration

Features

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

Install

1$ npm i auto-config-loader

Quick start

1const autoConf = require('auto-config-loader');
2
3import { autoConf } from 'auto-config-loader';
4
5// will look for:
6// process.cwd() + '.namespacerc'
7// process.cwd() + '.namespacerc.js'
8// process.cwd() + '.namespacerc.ts'
9// process.cwd() + '.namespacerc.mjs'
10// process.cwd() + '.namespacerc.cjs'
11// process.cwd() + '.namespacerc.json'
12// process.cwd() + '.namespacerc.json5'
13// process.cwd() + '.namespacerc.jsonc'
14// process.cwd() + '.namespacerc.yaml'
15// process.cwd() + '.namespacerc.yml'
16// process.cwd() + '.namespacerc.toml'
17// process.cwd() + 'namespace.config.mjs'
18// process.cwd() + 'namespace.config.cjs'
19// process.cwd() + 'namespace.config.js'
20// ........
21const data = await autoConf('namespace', {
22  default: {
23    testItem2: 'some value'
24  }
25});

Load JS

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

1// => ./app/app.config.js
2export default {
3  name: 'app'
4}

1import { loadConf } from 'auto-config-loader/load-conf';
2
3interface Config {
4  name: string;
5}
6
7const result = await loadConf<Config>('./app/app.config.js');
8// => { name: 'app' }

Option

1import { LoadConfOption } from 'auto-config-loader';
2export type LoaderFunc<T> = (filepath: string, content: string, jsOption?: LoadConfOption) => T | Promise<T>;
3export type Loader<T> = Record<string, LoaderFunc<T>>;
4export interface AutoConfOption<T> {
5  searchPlaces?: string[];
6  /** An object that maps extensions to the loader functions responsible for loading and parsing files with those extensions. */
7  loaders?: Loader<T>;
8  /** Specify default configuration. It has the lowest priority and is applied after extending config. */
9  default?: T;
10  /** Resolve configuration from this working directory. The default is `process.cwd()` */
11  cwd?: string;
12  /** Default transform js configuration */
13  jsOption?: LoadConfOption;
14  /** @deprecated use `mustExist` instead */
15  ignoreLog?: boolean;
16  mustExist?: boolean;
17}
18export declare const getConfigPath: () => string;
19/**
20 * Find and load configuration from a `package.json` property, `rc` file, or `CommonJS` module.
21 * @param namespace {string} Configuration base name. The default is `autoconf`.
22 * @param option
23 */
24export declare function autoConf<T>(namespace?: string, option?: AutoConfOption<T>): Promise<{} & T>;
25export default autoConf;

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:

1[
2  'package.json',
3  `.${moduleName}rc`,
4  `.${moduleName}rc.json`,
5  `.${moduleName}rc.json5`,
6  `.${moduleName}rc.jsonc`,
7  `.${moduleName}rc.yaml`,
8  `.${moduleName}rc.yml`,
9  `.${moduleName}rc.toml`,
10  `.${moduleName}rc.ini`,
11  `.${moduleName}rc.js`,
12  `.${moduleName}rc.ts`,
13  `.${moduleName}rc.cjs`,
14  `.${moduleName}rc.mjs`,
15  `.config/${moduleName}rc`,
16  `.config/${moduleName}rc.json`,
17  `.config/${moduleName}rc.json5`,
18  `.config/${moduleName}rc.jsonc`,
19  `.config/${moduleName}rc.yaml`,
20  `.config/${moduleName}rc.yml`,
21  `.config/${moduleName}rc.toml`,
22  `.config/${moduleName}rc.ini`,
23  `.config/${moduleName}rc.js`,
24  `.config/${moduleName}rc.ts`,
25  `.config/${moduleName}rc.cjs`,
26  `.config/${moduleName}rc.mjs`,
27  `${moduleName}.config.js`,
28  `${moduleName}.config.ts`,
29  `${moduleName}.config.cjs`,
30  `${moduleName}.config.mjs`,
31]

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:

1semi: 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:

1{
2  "name": "your-project",
3  "autoconfig": {
4    "semi": true
5  }
6}

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

1import type jiti from 'jiti';
2import { Options } from 'sucrase';
3type Jiti = ReturnType<typeof jiti>;
4type JITIOptions = Jiti['options'];
5export interface LoadConfOption {
6    jiti?: boolean;
7    jitiOptions?: JITIOptions;
8    transformOption?: Options;
9}
10export declare function loadConf<T>(path: string, option?: LoadConfOption): Promise<T>;
11export declare function jsLoader<T>(
12  filepath: string,
13  content: string,
14  option?: LoadConfOption
15): Promise<T>;

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

1import load, { jsLoader } from 'auto-config-loader';
2
3function loadJS(filepath, content) {
4  return jsLoader(filepath, content, {
5    // change option...
6  });
7}
8
9const data = await load('namespace', {
10  loaders: {
11    '.js': loadJS,
12    '.ts': loadJS,
13    '.cjs': loadJS,
14    '.mjs': loadJS,
15  },
16  default: {
17    testItem2: 'some value'
18  }
19});

example:

1import { jsLoader } from 'auto-config-loader';
2
3const data = jsLoader('/path/to/file/name.js')

.ini

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

example:

1import { iniLoader } from 'auto-config-loader';
2
3const data = iniLoader(undefined, `...`)

.json,.jsonc, json5

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

example:

1import { jsonLoader } from 'auto-config-loader';
2
3const data = jsonLoader(undefined, `{ "a": 123 }`)

.toml

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

example:

1import { tomlLoader } from 'auto-config-loader';
2
3const data = tomlLoader(undefined, `...`)

.yaml

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

example:

1import { yamlLoader } from 'auto-config-loader';
2
3const data = yamlLoader(undefined, `...`)

Custom Yaml loader

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

1import load from 'auto-config-loader';
2import yaml from 'yaml';
3
4function loadYaml(filepath, content) {
5  return yaml.parse(content);
6}
7
8const data = await load('namespace', {
9  searchPlaces: [
10    '.namespacerc.yaml',
11    '.namespacerc.yml',
12  ],
13  loaders: {
14    '.yaml': loadYaml,
15    '.yml': loadYaml,
16  },
17  default: {
18    testItem2: 'some value'
19  }
20});

Utils

merge

1export declare const merge: {
2  <TObject, TSource>(object: TObject, source: TSource): TObject & TSource;
3  <TObject, TSource1, TSource2>(object: TObject, source1: TSource1, source2: TSource2): TObject & TSource1 & TSource2;
4  <TObject, TSource1, TSource2, TSource3>(object: TObject, source1: TSource1, source2: TSource2, source3: TSource3): TObject & TSource1 & TSource2 & TSource3;
5  <TObject, TSource1, TSource2, TSource3, TSource4>(object: TObject, source1: TSource1, source2: TSource2, source3: TSource3, source4: TSource4): TObject & TSource1 & TSource2 & TSource3 & TSource4;
6  (object: any, ...otherArgs: any[]): any;
7};

findConfigFile

1export declare function findConfigFile(
2  moduleName: string,
3  root: string,
4  searchPlaces?: string[]
5): string;

getConfigPath

1export declare const getConfigPath: () => string;

Example:

1import { autoConf, getConfigPath } from 'auto-config-loader';
2
3const data = autoConf<Config>('idoc');
4const configPath = getConfigPath();
5// => /.autoconfrc.js

V1 To V2 Migration

This guide provides the steps to migrate to the latest version of the configuration loader API.

Key Changes

1. Loader Functions Support Async

   • LoaderFunc<T> now supports returning T or Promise<T>.
   • Update custom loaders to handle asynchronous operations if needed.

   Example:

   1export type LoaderFunc<T> = (
   2  filepath: string,
   3  content: string,
   4  jsOption?: LoadConfOption
   5) => T | Promise<T>;

2. autoConf Returns a Promise

   • The autoConf function now returns a Promise instead of a synchronous result.
   • Update your code to handle asynchronous calls.

   Example:

   1export declare function autoConf<T>(
   2  namespace?: string,
   3  option?: AutoConfOption<T>
   4): Promise<{} & T>;

Migration Steps

1. Update Custom Loader Functions

If you have custom loaders, update their return types to support asynchronous operations:

Example:

1const jsonLoader: LoaderFunc<MyConfig> = async (
2  filepath, content
3) => JSON.parse(content);

2. Handle Asynchronous autoConf Calls

Update all calls to autoConf to use await or .then to handle Promises:

Example Using await:

1const config = await autoConf('myNamespace', options);
2console.log(config);

Example Using .then:

1autoConf('myNamespace', options).then(config => {
2  console.log(config);
3});

Related

• 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	Last commit	Download	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

Contributors

As always, thanks to our amazing contributors!

Made with contributors.

License

This package is licensed under the MIT License.