{"id":15396804,"url":"https://github.com/axe312ger/sane-config","last_synced_at":"2025-11-07T23:30:21.342Z","repository":{"id":89046151,"uuid":"78132399","full_name":"axe312ger/sane-config","owner":"axe312ger","description":":yin_yang: sane, simple but opinionated cascading configuration management","archived":false,"fork":false,"pushed_at":"2017-04-02T19:13:02.000Z","size":112,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-25T18:41:21.984Z","etag":null,"topics":["config","configuration","configuration-management","schema-validation"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/axe312ger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-05T17:09:08.000Z","updated_at":"2022-01-27T21:14:20.000Z","dependencies_parsed_at":"2023-03-29T03:47:47.273Z","dependency_job_id":null,"html_url":"https://github.com/axe312ger/sane-config","commit_stats":{"total_commits":22,"total_committers":3,"mean_commits":7.333333333333333,"dds":0.2727272727272727,"last_synced_commit":"e91421030ec59f5e4a5d42add80443dcc94b5cde"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axe312ger%2Fsane-config","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axe312ger%2Fsane-config/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axe312ger%2Fsane-config/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axe312ger%2Fsane-config/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/axe312ger","download_url":"https://codeload.github.com/axe312ger/sane-config/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239541855,"owners_count":19656102,"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":["config","configuration","configuration-management","schema-validation"],"created_at":"2024-10-01T15:34:58.361Z","updated_at":"2025-11-07T23:30:21.065Z","avatar_url":"https://github.com/axe312ger.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sane-config\n\n\u003e Simple opinionated cascading configuration management. Heavily influenced by [konphyg](https://github.com/pgte/konphyg) but more features, easier usage and less code.\n\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://axe312.mit-license.org)\n[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://github.com/feross/standard)\n[![Build Status](https://img.shields.io/circleci/project/axe312ger/sane-config.svg?maxAge=2592000)](https://circleci.com/gh/axe312ger/sane-config)\n[![CodeCov Badge](https://img.shields.io/codecov/c/github/axe312ger/sane-config.svg?maxAge=2592000)](https://codecov.io/gh/axe312ger/sane-config)\n[![semantic-release](https://img.shields.io/badge/%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n\n## Features\n\n* Simple usage: Just require `sane-config` in your code and the assigned variable will contain your config. DONE!\n* Supports `json` and `js` files.\n* Set up within 5 minutes without headache.\n* Works for node and browser.\n* Automatically selects matching configuration based on the `NODE_ENV`.\n* Cascading configuration. Define a default, overwrite some values on production. No problem!\n* Validation of configuration files made easy via [json-schema](http://json-schema.org/)\n* Developers can overwrite any configuration in case they have special settings on their machine.\n* Uses [debug](https://www.npmjs.com/package/debug) to display the chosen configuration files.\n* All of this with just about 100 lines of code and a few small dependencies. Let's keep stuff simple!\n\n## Install\n\n```js\nyarn add sane-config || npm install --save sane-config\n```\n\n## Preparations\n\nTwo simple steps to reach the goal:\n\n### First – Create a config directory\n\nStore your configuration files in a directory called `config` in your project root.\n\n**(Optional) Tell sane-config to use another directory:**\n\nIf you prefer some other location, you have two options:\n\n* Set the `config['sane-config'].directory` parameter in your `package.json` [config object](https://docs.npmjs.com/files/package.json#config) to whatever you like.\n* Add the `--configurationDirectory` argument to your process call\n\nHint: The path may be relative or absolute.\n\n### Second – Name your config files\n\nYou have to split your configuration files into sections, which will be merged to a single config object. This gives you basic organization and separation.\n\nTo achieve this, they must follow this naming structure:\n\n`[Section].[Level].js(on)`\n\n1. `[Section]` - Might be anything you want. All files with the same section will be merge into one config object property. Use it for separation like `database`, `paths`, `tokens`, ...\n2. `[Level]` - Indicates the cascading priority for the files of one section. `sane-config` will load and\nmerge the configurations in the following order:\n  * default\n  * `process.env.NODE_ENV`\n  * local\n  * schema\n3. `js` or `json` file extension\n\nYour config directory later may look like this:\n```sh\ndb.default.js\ndb.local.js # local overwrite for developer environment\ndb.production.json # should be only present on server\ndb.schema.json # optional file for config validation\n```\n\n## Usage (Node)\n\nLet's assume we have the following configuration files in our configuration directory:\n\n### `database.json`\n```json\n{\n  \"user\": \"frank\",\n  \"port\": 5432\n}\n```\n\n### `database.production.json`\n```json\n{\n  \"user\": \"peter\"\n}\n```\n\nYou can access your configuration like this:\n```js\nimport config from 'sane-config'\n\nconsole.log(config.database.user)\n// --\u003e frank\n```\n\nThats how the whole configuration would look like for **development**:\n```js\nimport config from 'sane-config'\n\nconsole.log(JSON.stringify(config, null, 2))\n// {\n//   \"database\": {\n//     \"user\": \"frank\",\n//     \"port\": 5432\n//   }\n// }\n```\n\nAnd here for **production**:\n```js\nimport config from 'sane-config'\n\nconsole.log(JSON.stringify(config, null, 2))\n// {\n//   \"database\": {\n//     \"user\": \"peter\", \u003c-- user got overwritten\n//     \"port\": 5432\n//   }\n// }\n```\n\n### Usage within Webpack apps (Browser)\n\nJust add your processed config as global via the [DefinePlugin](https://webpack.js.org/plugins/define-plugin/). This ensures it only runs once and does not fail\nsince sane-config uses the [file system](https://nodejs.org/api/fs.html) to read your configs which only works in node environments.\n\n```js\nimport config from 'sane-config'\n\n...\nnew Webpack.DefinePlugin({\n  APP_CONFIG: JSON.stringify(config)\n})\n...\n```\n\nMake sure that you don't forget the `JSON.stringify()`\n\n## Validation\nsane-config also provides a way to validate your configuration. In later states of your project, this can help a lot to ensure configuration of new or long-time inactive team members are up to date.\n\nJust add a json file with [JSON Schema](http://json-schema.org/) information next to your configuration files. It must follow this naming structure:\n\n`[Section].schema.json`\n\nThe generator at http://jsonschema.net/ might help you to create your first schema definition.\n\n## Development\n\nThis project follows the [standard](https://github.com/feross/standard) coding and the [conventional changelog](https://github.com/conventional-changelog/conventional-changelog-angular/blob/master/convention.md) commit message style. Also it is configured to never decrease the code coverage of its tests.\n\nAlso make sure you check out all available npm scripts via `npm run`.\n\n## Contributing\n\nPull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/axe312ger/sane-config/issues/new).\nBut before doing anything, please read the [CONTRIBUTING.md](./CONTRIBUTING.md) guidelines.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxe312ger%2Fsane-config","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faxe312ger%2Fsane-config","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxe312ger%2Fsane-config/lists"}