Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jaywcjlove/auto-config-loader

Find and load configuration from a package.json property, rc file, or CommonJS module.
https://github.com/jaywcjlove/auto-config-loader

config config-loader loader nodejs typescript

Last synced: about 1 month ago
JSON representation

Find and load configuration from a package.json property, rc file, or CommonJS module.

Awesome Lists containing this project

README 

        
Auto Config Loader

===



[![Buy me a coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-048754?logo=buymeacoffee)](https://jaywcjlove.github.io/#/sponsor)

[![CI](https://github.com/jaywcjlove/auto-config-loader/actions/workflows/main.yml/badge.svg)](https://github.com/jaywcjlove/auto-config-loader/actions/workflows/main.yml)

[![NPM version](https://img.shields.io/npm/v/auto-config-loader.svg?style=flat&label=npm)](https://npmjs.org/package/auto-config-loader)

[![Coverage Status](https://jaywcjlove.github.io/auto-config-loader/badges.svg)](https://jaywcjlove.github.io/auto-config-loader/lcov-report/)

[![npm Downloads](https://img.shields.io/npm/dm/auto-config-loader?style=flat)](https://www.npmjs.com/package/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](https://www.json.org), [JSONC](https://github.com/microsoft/node-jsonc-parser), [JSON5](https://json5.org/), [YAML](https://yaml.org/), [TOML](https://toml.io), [INI](https://en.wikipedia.org/wiki/INI_file), [CJS](http://www.commonjs.org), [Typescript](https://www.typescriptlang.org/), and ESM config load.

- Reads config from the nearest `package.json` file



## Install



```bash

$ npm i auto-config-loader

```



## Quick start



```js

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`.



```js

// => ./app/app.config.js

export default {

  name: 'app'

}

```



```ts

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



interface Config {

  name: string;

}



const result = loadConf('./app/app.config.js');

// => { name: 'app' }

```



## Option



```ts

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

export type LoaderFunc = (filepath: string, content: string, jsOption?: LoadConfOption) => T;

export type Loader = Record>;

export interface AutoConfOption {

  searchPlaces?: string[];

  /** An object that maps extensions to the loader functions responsible for loading and parsing files with those extensions. */

  loaders?: Loader;

  /** 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(namespace?: string, option?: AutoConfOption): {} & 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`:**



```js

[

  '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`:



```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:



```js

{

  "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`



```ts

import type { JITIOptions } from 'jiti/dist/types';

import { Options } from 'sucrase';

export interface LoadConfOption {

  jiti?: boolean;

  jitiOptions?: JITIOptions;

  transformOption?: Options;

}

export declare function loadConf(path: string, option?: LoadConfOption): T;

export declare function jsLoader(filepath: string, content: string, option?: LoadConfOption): T;

```



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



```js

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:



```ts

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



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

```



### `.ini`



```ts

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

```



example:



```ts

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



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

```



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



```ts

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

```



example:



```ts

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



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

```



### `.toml`



```ts

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

```



example:



```ts

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



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

```



### `.yaml`



```ts

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

```



example:



```ts

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.



```js

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



```ts

export declare const merge: {

  (object: TObject, source: TSource): TObject & TSource;

  (object: TObject_1, source1: TSource1, source2: TSource2): TObject_1 & TSource1 & TSource2;

  (object: TObject_2, source1: TSource1_1, source2: TSource2_1, source3: TSource3): TObject_2 & TSource1_1 & TSource2_1 & TSource3;

  (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



```ts

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

```



### getConfigPath



```ts

export declare const getConfigPath: () => string;

```



Example:



```ts

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



const data = autoConf('idoc');

const configPath = getConfigPath();

// => /.autoconfrc.js

```



## Related



- [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) Find and load configuration from a package.json property, rc file, or CommonJS module

- [cjson](https://www.npmjs.com/package/cjson) Comments enabled json loader (Commented JavaScript Object Notation)

- [Config Loader](https://www.npmjs.com/package/@web/config-loader) Load user config files for node js projects.

- [Lilconfig](https://www.npmjs.com/package/lilconfig) Zero-dependency nodejs config seeker.

- [proload](https://github.com/natemoo-re/proload) Searches for and loads your tool's JavaScript configuration files with full support for CJS, ESM, TypeScript and more.

- [rc](https://github.com/dominictarr/rc) The non-configurable configuration loader for lazy people.



Library | Last commit | Download | loaders | config ext

:-- | --- | --- | --- | ---

**auto-config-loader** | [![GitHub last commit](https://img.shields.io/github/last-commit/jaywcjlove/auto-config-loader?style=flat&label=)](https://github.com/jaywcjlove/auto-config-loader/commits) | [![NPM Downloads](https://img.shields.io/npm/dm/auto-config-loader.svg?style=flat&label=)](https://www.npmjs.com/package/auto-config-loader) | ✅ | `.js`, `.ts`, `.cjs`, `.mjs`, `.json`, `.jsonc`, `json5`, `.ini`, `.toml`, `.yaml` ++

cosmiconfig | [![GitHub last commit](https://img.shields.io/github/last-commit/cosmiconfig/cosmiconfig?style=flat&label=)](https://github.com/cosmiconfig/cosmiconfig/commits) | [![NPM Downloads](https://img.shields.io/npm/dm/cosmiconfig.svg?style=flat&label=)](https://www.npmjs.com/package/cosmiconfig) | ✅ | `.json`, `.yaml`, `.yml`, `.js`, `.mjs`, `.cjs`

~~rc~~ | [![GitHub last commit](https://img.shields.io/github/last-commit/dominictarr/rc?style=flat&label=)](https://github.com/dominictarr/rc/commits) | [![NPM Downloads](https://img.shields.io/npm/dm/rc.svg?style=flat&label=)](https://www.npmjs.com/package/rc) | ✅ | `.json`, `.yaml`, `.yml`, `.js`, `.mjs`, `.cjs`

@proload/core | [![GitHub last commit](https://img.shields.io/github/last-commit/natemoo-re/proload?style=flat&label=)](https://github.com/natemoo-re/proload/commits) | [![NPM Downloads](https://img.shields.io/npm/dm/@proload/core.svg?style=flat&label=)](https://www.npmjs.com/package/@proload/core) | ✅ | `.js`, `.ts`, `.cjs`, `.mjs`, `.json`, `.jsonc`, `json5`, `.ini`, `.toml`, `.yaml` ++

lilconfig | [![GitHub last commit](https://img.shields.io/github/last-commit/antonk52/lilconfig?style=flat&label=)](https://github.com/antonk52/lilconfig/commits) | [![NPM Downloads](https://img.shields.io/npm/dm/lilconfig.svg?style=flat&label=)](https://www.npmjs.com/package/lilconfig) | ✅ | `.js`, `.cjs`, `.mjs`, `.json` ++

~~cjson~~ | [![GitHub last commit](https://img.shields.io/github/last-commit/kof/node-cjson?style=flat&label=)](https://github.com/kof/node-cjson/commits) | [![NPM Downloads](https://img.shields.io/npm/dm/cjson.svg?style=flat&label=)](https://www.npmjs.com/package/cjson) | ✅ | `.json`

@web/config-loader | [![GitHub last commit](https://img.shields.io/github/last-commit/modernweb-dev/web?style=flat&label=)](https://github.com/modernweb-dev/web/commits) | [![NPM Downloads](https://img.shields.io/npm/dm/@web/config-loader.svg?style=flat&label=)](https://www.npmjs.com/package/@web/config-loader) | ❌ | `.js`, `.mjs`, `.cjs`



## Contributors



As always, thanks to our amazing contributors!





  




Made with [contributors](https://github.com/jaywcjlove/github-action-contributors).



## License



This package is licensed under the MIT License.