{"id":25297437,"url":"https://github.com/coditorium/nodejs-read-config","last_synced_at":"2025-10-28T03:30:41.875Z","repository":{"id":24413578,"uuid":"27814380","full_name":"coditorium/nodejs-read-config","owner":"coditorium","description":"Node.js - JSON configuration loader","archived":false,"fork":false,"pushed_at":"2022-01-05T08:10:59.000Z","size":80,"stargazers_count":7,"open_issues_count":5,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-01-12T04:31:32.643Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coditorium.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-12-10T10:21:58.000Z","updated_at":"2022-06-07T11:47:56.000Z","dependencies_parsed_at":"2022-08-22T22:10:15.286Z","dependency_job_id":null,"html_url":"https://github.com/coditorium/nodejs-read-config","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coditorium%2Fnodejs-read-config","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coditorium%2Fnodejs-read-config/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coditorium%2Fnodejs-read-config/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coditorium%2Fnodejs-read-config/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coditorium","download_url":"https://codeload.github.com/coditorium/nodejs-read-config/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238461528,"owners_count":19476343,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-13T03:29:31.998Z","updated_at":"2025-10-28T03:30:36.572Z","avatar_url":"https://github.com/coditorium.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nodejs-read-config\n\n[![Travis build status](https://travis-ci.org/coditorium/nodejs-read-config.png?branch=master)](https://travis-ci.org/coditorium/nodejs-read-config)\n[![dependencies](https://david-dm.org/coditorium/nodejs-read-config.png)](https://david-dm.org/coditorium/nodejs-read-config)\n[![Coverage Status](https://coveralls.io/repos/coditorium/nodejs-read-config/badge.svg)](https://coveralls.io/r/coditorium/nodejs-read-config)\n\n[![NPM info](https://nodei.co/npm/read-config.png?downloads=true)](https://www.npmjs.com/package/read-config)\n\nMulti format configuration loader for Node.js.\nFeatures:\n\n- Environmental variables replacement\n- Configuration variables replacement\n- Overriding configuration properties via environmental variables\n- Variable default values\n- Hierarchical configurations\n- Supported format:\n  - [JSON5](http://json5.org/)\n  - [YAML](http://en.wikipedia.org/wiki/YAML)\n  - [Properties](http://en.wikipedia.org/wiki/.properties)\n\n## How to use\n\n### Environment variable replacement\n\n/tmp/config.json:\n``` javascript\n{ env1: \"%{ENV_VAR1}\", env2: \"%{ENV_VAR2|def}\" }\n```\nindex.js:\n``` javascript\nvar readConfig = require('read-config'),\n    config = readConfig('/tmp/config.json');\n\nconsole.log(config);\n\n//  $ ENV_VAR1=abc node index.js\n//  { env1: 'abc', env2: 'def' }\n```\n\n- It is possible to change `%` to any other character. Just use `replaceEnv` configuration option.\n- It is possible to use default values when environmental variable is not set.\n\n### Configuration overriding with system variables\n\n/tmp/config.json:\n``` javascript\n{\n    rootProp: \"rootProp\",\n    objProp: {\n\t\tx: 'X'\n\t}\n}\n```\nindex.js:\n``` javascript\nvar readConfig = require('read-config'),\n    config = readConfig('/tmp/config.json', { override: true });\n\nconsole.log(config);\n\n//  $ ENV_VAR1=abc node index.js\n//  { rootProp: 'rootProp', objProp: { x: 'X'} }\n\n//  $ CONFIG_objProp_x=abc node index.js\n//  { rootProp: 'rootProp', objProp: { x: 'abc'} }\n```\n\n- It is possible to change `CONFIG` to any other character. Just use `override` configuration option.\n- It is possible to override existing value or create new one.\n\n### Configuration variable replacement\n\n/tmp/config.json:\n``` javascript\n{\n    text1: \"def\",\n    text2: \"abc-@{text1}-ghi\"\n    number1: 1,\n    number2: \"@{number1}\",\n    boolean1: true,\n    boolean2: \"@{boolean1}\",\n    null1: null,\n    null2: \"@{null1}\",\n\tobj1: {\n\t\tx: 'X',\n\t\ty: '@{./x}', // same as @{obj1.x}\n\t\tz: '@{../text1}' // same as @{text1}\n\t},\n\tobj2: \"@{obj1}\"\n}\n```\nindex.js:\n``` javascript\nvar readConfig = require('read-config'),\n    config = readConfig('/tmp/config.json');\n\nconsole.log(config);\n\n//  $ node index.js\n//  {\n//    text1: \"def\",\n//    text2: \"abc-def-ghi\"\n//    number1: 1,\n//    number2: 1,\n//    boolean1: true,\n//    boolean2: true,\n//    null1: null,\n//    null2: null,\n//    obj1: {\n//      x: 'X',\n//      y: 'X',\n//      z: 'def'\n//    },\n//    obj2: {\n//      x: 'X',\n//      y: 'X',\n//      z: 'def'\n//    }\n//  }\n```\n\n- It is possible to use nested paths like `@{x.y.z}`\n- It is possible to use relative paths like `@{./x}` and `@{../y}`\n- It is possible to concatenate variables like `@{x}abc@{y}def@{ghi}`\n\n### Configuration hierarchy\n\n/tmp/config-1.json:\n``` javascript\n{\n    a: \"a\",\n    b: \"b\",\n    arr: [1, 2, 3]\n}\n```\n/tmp/config-2.json:\n``` javascript\n{\n    __parent: \"/tmp/config-1.json\",\n    // same as: __parent: \"./config-1.json\",\n    b: \"bb\",\n    c: \"aa\",\n    arr: []\n}\n```\nindex.js:\n``` javascript\nvar readConfig = require('read-config'),\n    config = readConfig('/tmp/config-2.json');\n\nconsole.log(config);\n\n//  $ node index.js\n//  {\n//    a: \"a\"\n//    b: \"bb\",\n//    c: \"aa\",\n//    arr: []\n//  }\n\n```\n\n### Hierarchy and basedir\n\n/tmp/config-1.json:\n``` javascript\n{\n    a: \"a\",\n    b: \"b\",\n    arr: [1, 2, 3]\n}\n```\n/home/xxx/config-2.json:\n``` javascript\n{\n    __parent: \"config-1\", // no directory \u0026 extension specified\n    b: \"bb\",\n    c: \"aa\",\n    arr: []\n}\n```\nindex.js:\n``` javascript\nvar readConfig = require('read-config'),\n    config = readConfig('/tmp/config-2.json');\n\nconsole.log(config);\n\n//  $ node index.js\n//  {\n//    a: \"a\"\n//    b: \"bb\",\n//    c: \"aa\",\n//    arr: []\n//  }\n```\n\n### YAML config format\n\nUsing YAML representation lookout for special characters like: '%' and '@'.\n\n/tmp/config.yml:\n``` javascript\na: \"@{LOCAL_VAR}\"\nb: \"%{ENV_VAR}\"\nc: No quotes needed!\n```\n\n## API\n\n### Functions\n\n- **readConfig(paths, [opts])** - Alias for `readConfig.sync(paths, [opts])`.\n- **readConfig.sync(paths, [opts])** - Loads configuration file synchronously.\n- **readConfig.async(paths, [opts], callback)** - Loads configuration file asynchronously.\n\nAll json files are loaded using [JSON5](https://www.npmjs.com/package/json5) library. It means you can add comments, and skip quotes in your config files - thank you json5;).\n\n### Parameters\n\n- **paths** (String/Array) - path (or array of paths) to configuration file. If passed an array of paths than every configuration is resolved separately than merged hierarchically (like: [grand-parent-config, parent-config, child-config]).\n- **opts** (Object, optional) - configuration loading options\n    - **parentField** - (Boolean/String, default: true) if specified enables configuration hierarchy. It's value is used to resolve parent configuration file. This field will be removed from the result. A string value overrides `__parentField` property name.\n    - **optional** - (String/Array, default: []) list of configuration paths that are optional. If any configuration path is not resolved and is not optional it's treated as empty file and no exception is raised.\n    - **basedir** - (String/Array, default: []) base directory (or directories) used for searching configuration files. Mind that `basedir` has lower priority than a configuration directory, process basedir, and absolute paths.\n    - **replaceEnv** - (Boolean/String, default: false, constraint: A string value must be different than `replaceLocal`) if specified enables environment variable replacement. Expected string value e.g. `%` that will be used to replace all occurrences of `%{...}` with environment variables. You can use default values like: %{a.b.c|some-default-value}.\n    - **replaceLocal** - (Boolean/String, default: '@', constraint: A string value must be different than `replaceEnv`) if specified enables configuration variable replacement. Expected string value e.g. `@` that will be used to replace all occurrences of `@{...}` with configuration variables. You can use default values like: @{a.b.c|some-default-value}.\n    - **override** - (Boolean/String, default: false) If specified enables configuration overriding with environmental variables like `CONFIG_\u003cpropertyName\u003e`.\n    - **skipUnresolved** - (Boolean, default: false) `true` blocks error throwing on unresolved variables.\n\nDefault **opts** values:\n``` javascript\n{\n    parentField: \"__parent\",\n    optional: [],\n    basedir: null,\n    replaceEnv: \"%\",\n    replaceLocal: \"@\",\n    skipUnresolved: false\n}\n```\n\n## Flow\n\nFlow of the configuration loader:\n\n1. Merge all configs passed in **path** parameter with all of their parents (merging all hierarchy)\n2. Merge all results to one json object\n3. Override configuration with environment variables\n4. Resolve environment variables\n5. Resolve local variables\n\n### Gulp commands:\n\n- `gulp checkstyle` - runs jshint and jscsrc analysis\n- `gulp test` - runs tests\n- `gulp test --file test/loader.js` - runs single test file `./test/loader.js`\n- `gulp` - alias for `gulp jshint test`\n- `gulp test-cov` - runs instrumented tests, generates reports to `./build/test`\n- `gulp test-cov --file test/loader.js` - runs single instrumented test file `./test/loader.js`\n- `gulp clean` - removes `./build` folder\n- `gulp ci` - alias for `gulp clean checkstyle test-cov`\n\n### NPM commands:\n\n- `npm test` - alias for `gulp test`\n- `npm run ci` - alias for `gulp ci`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoditorium%2Fnodejs-read-config","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoditorium%2Fnodejs-read-config","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoditorium%2Fnodejs-read-config/lists"}