{"id":19816699,"url":"https://github.com/welldone-software/env-config","last_synced_at":"2026-03-08T01:34:46.569Z","repository":{"id":46947221,"uuid":"122996511","full_name":"welldone-software/env-config","owner":"welldone-software","description":"Dead simple yet powerful config library","archived":false,"fork":false,"pushed_at":"2023-01-03T15:15:42.000Z","size":980,"stargazers_count":14,"open_issues_count":9,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-10-05T07:21:22.293Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/welldone-software.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":"2018-02-26T16:24:16.000Z","updated_at":"2022-09-19T14:27:35.000Z","dependencies_parsed_at":"2023-02-01T07:01:01.872Z","dependency_job_id":null,"html_url":"https://github.com/welldone-software/env-config","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/welldone-software/env-config","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/welldone-software%2Fenv-config","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/welldone-software%2Fenv-config/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/welldone-software%2Fenv-config/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/welldone-software%2Fenv-config/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/welldone-software","download_url":"https://codeload.github.com/welldone-software/env-config/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/welldone-software%2Fenv-config/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30240902,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T00:58:18.660Z","status":"ssl_error","status_checked_at":"2026-03-08T00:55:48.608Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":"2024-11-12T10:10:23.236Z","updated_at":"2026-03-08T01:34:46.546Z","avatar_url":"https://github.com/welldone-software.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Overview\nHave your configuration in one place, organized in a js native structure, possbily hirarchial, but still easily configurable and overideable by environment variables, as recommended by the [Twelve-Factor App methodology](https://en.wikipedia.org/wiki/Twelve-Factor_App_methodology)\n\nYour config objects can look like below, and still fully support environment variables:\n```js\n{\n  port: 1234,                     // PORT=1234\n  isCors: true                    // IS_CORS=true\n  db: {\n    hostName: 'example.com',      // DB__HOST_NAME=example.com\n    port: 4321,                   // DB__PORT=4321\n  },\n  friends: ['Adam', 'Rachel'],    // FRIENDS__0=Adam FRIENDS__1=Rachel\n}\n```\n\nThis tiny and powerfull config library reads keys from the config object and searches proccess.env for corresponding keys according to a naming convension.\n\nIt allows your apps to use config objects that fully support literal objects, literal arrays, numbers, strings and booleans , while stil being configured/overidden by env vars.\n\n# Sample\n\n## config.js\n```js\nconst {mapEnv} = require('@welldone-software/env-config')\n\nmodule.exports = mapEnv({\n  port: 1234,\n  db: {\n    hostName: 'example.com',\n    port: 4321,\n    user: '',\n    password: '',\n  },\n  friends: ['Adam', 'Rachel'],\n  isCors: true\n})\n```\n\n## Environment variables (specified in .env file or at runtime)\n```\nDB__HOST_NAME=mydomain.com\nDB__PORT=3060\nDB__USER=ADMIN\nDB__PASSWORD=ygIYDG*\u0026h8\u0026ADSGH\nIS_CORS=false\nANOTHER_KEY=anothervalue\nFRIENDS__1=Sara\n```\n\n\n### At runtime, the result will be\n``` js\n{\n  port: 1234,\n  db: {\n    hostName: 'mydomain.com',\n    port: 3060,\n    user: 'ADMIN',\n    password: 'ygIYDG*\u0026h8\u0026ADSGH',\n  },\n  friends: ['Adam', 'Sara'],\n  isCors: false\n}\n```\n\n# Installing\n\n```bash\nyarn add @welldone-software/env-config\n# or the npm version:\nnpm i @welldone-software/env-config\n```\n\n# Importing\n\n```js\nimport {mergeEnv, mapEnv, getEnvKeys, getDotEnvFileFormat} from '@welldone-software/env-config';\n// or the node version:\nconst {mergeEnv, mapEnv, getEnvKeys, getDotEnvFileFormat} = require('@welldone-software/env-config');\n```\n\n# API\n\n### mergeEnv(config: Object) : Object\nRecrusively applies values from the environment (environment variables) onto the fileds of the config object parameter and returns the same object, after it has been changed. \nNote: this changes the object itself, and breaches immutablity thus we recommend using `mapEnv`.\n\n### mapEnv(config: Object) : Object\nA pure function version of `mergeEnv`. This keeps the config object parameter immutable. It creates and returns a new object which is a combination of the original config object values and the values applied from the environment.\n\n### getEnvKeys(config: Object) : string[]\nA utility function that returns the list of environment keys expected/supported for a given config object. \n\n### getDotEnvFileFormat(config: Object) : string\nA utility function that returns the dot env file (keys and values) for a given config object.\n\n# Conventions\n\n## JS\n* The JS config object should be a literal object with `camalCase` members.\n* Object can be nested, aka have members which are objects themselves.\n* Object fields can be of of either _Object, _String_, _Boolean_, _Number_ or _Array_ type.\n\n## ENV\n* Environment variables are expected in `UPPER_SNAKE_CASE` convention.\n* A single underscore (`_`) singinfied a word change and is mapped to case changes in js's `camalCase`.\n* Two underscores (`__`) mean nesting, e.g. DB_SETTINGS__CONNECTION_STRING translated to dbSettings.connectionString\n* Boolean values are `true` and `false`\n* Arrays values are modeled like sub objects, e.g. `VAR_NAME__0`. Note the _double_ underscore.\n\n## Type resolution\nTypes are determined by defaults in the config object, so you should have a defalut value on each field of the config object. The type of the value will determine the type and shape expected of the corresponding evironment variable.\n\n# Advantages\n\n* Single source of truth - one place to define all posibble config keys.\n* Simple to use but still allows for rather complex configurations: not just strings and not just flat structures.\n* Uses 'native' naming convention in each environment so configs look natural both in JS and in ENV. \n* Much more readable than the alternative: \u003cs\u003e`const port = proccess.env.PORT || 1000`\u003c/s\u003e\n\n\n# Roadmap\n* Add typing support (typescript and Flow)\n* Support initial prefix (only merge prefixed env vars, with and without omitting the prefix)\n\n# License\n[MIT License](LICENSE)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwelldone-software%2Fenv-config","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwelldone-software%2Fenv-config","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwelldone-software%2Fenv-config/lists"}