auto-config-loader
v2.0.2
Published
Find and load configuration from a package.json property, rc file, or CommonJS module.
Downloads
91,997
Maintainers
Readme
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 = await 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 = await 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 | Promise<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. */
default?: 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;
}
export declare const getConfigPath: () => string;
/**
* 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 declare function autoConf<T>(namespace?: string, option?: AutoConfOption<T>): Promise<{} & T>;
export 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
:
[
'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 jiti from 'jiti';
import { Options } from 'sucrase';
type Jiti = ReturnType<typeof jiti>;
type JITIOptions = Jiti['options'];
export interface LoadConfOption {
jiti?: boolean;
jitiOptions?: JITIOptions;
transformOption?: Options;
}
export declare function loadConf<T>(path: string, option?: LoadConfOption): Promise<T>;
export declare function jsLoader<T>(
filepath: string,
content: string,
option?: LoadConfOption
): Promise<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 = await 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 = await 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, TSource1, TSource2>(object: TObject, source1: TSource1, source2: TSource2): TObject & TSource1 & TSource2;
<TObject, TSource1, TSource2, TSource3>(object: TObject, source1: TSource1, source2: TSource2, source3: TSource3): TObject & TSource1 & TSource2 & TSource3;
<TObject, TSource1, TSource2, TSource3, TSource4>(object: TObject, source1: TSource1, source2: TSource2, source3: TSource3, source4: TSource4): TObject & TSource1 & TSource2 & TSource3 & 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
V1 To V2 Migration
This guide provides the steps to migrate to the latest version of the configuration loader API.
Key Changes
Loader Functions Support Async
LoaderFunc<T>
now supports returningT
orPromise<T>
.- Update custom loaders to handle asynchronous operations if needed.
Example:
export type LoaderFunc<T> = ( filepath: string, content: string, jsOption?: LoadConfOption ) => T | Promise<T>;
autoConf
Returns a Promise- The
autoConf
function now returns aPromise
instead of a synchronous result. - Update your code to handle asynchronous calls.
Example:
export declare function autoConf<T>( namespace?: string, option?: AutoConfOption<T> ): Promise<{} & T>;
- The
Migration Steps
1. Update Custom Loader Functions
If you have custom loaders, update their return types to support asynchronous operations:
Example:
const jsonLoader: LoaderFunc<MyConfig> = async (
filepath, content
) => JSON.parse(content);
2. Handle Asynchronous autoConf
Calls
Update all calls to autoConf
to use await
or .then
to handle Promises:
Example Using await
:
const config = await autoConf('myNamespace', options);
console.log(config);
Example Using .then
:
autoConf('myNamespace', options).then(config => {
console.log(config);
});
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.