{"id":19621339,"url":"https://github.com/commenthol/dotconfig","last_synced_at":"2026-01-27T10:32:52.942Z","repository":{"id":143648289,"uuid":"616534447","full_name":"commenthol/dotconfig","owner":"commenthol","description":"Config helper to (magically) override application settings with environment variables.","archived":false,"fork":false,"pushed_at":"2024-11-21T07:18:27.000Z","size":136,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-28T01:52:05.192Z","etag":null,"topics":["configuration","dotconfig","dotenv","dotenv-parser"],"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/commenthol.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2023-03-20T15:17:53.000Z","updated_at":"2024-11-21T07:18:32.000Z","dependencies_parsed_at":"2024-01-23T00:16:20.504Z","dependency_job_id":"cecbd400-0a45-42cb-b53d-7abc203f0b18","html_url":"https://github.com/commenthol/dotconfig","commit_stats":{"total_commits":25,"total_committers":1,"mean_commits":25.0,"dds":0.0,"last_synced_commit":"44033a54ce35bbfa4b941c1bf5ae449db3448df1"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/commenthol/dotconfig","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commenthol%2Fdotconfig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commenthol%2Fdotconfig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commenthol%2Fdotconfig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commenthol%2Fdotconfig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/commenthol","download_url":"https://codeload.github.com/commenthol/dotconfig/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commenthol%2Fdotconfig/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28811945,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T07:41:26.337Z","status":"ssl_error","status_checked_at":"2026-01-27T07:41:08.776Z","response_time":168,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["configuration","dotconfig","dotenv","dotenv-parser"],"created_at":"2024-11-11T11:22:25.855Z","updated_at":"2026-01-27T10:32:52.924Z","avatar_url":"https://github.com/commenthol.png","language":"JavaScript","readme":"[![npm badge][npm-badge]][npm]\n![types badge][types-badge]\n![monthly downloads badge][npm-dm]\n\n# dotconfig\n\nConfig helper to (magically) override application settings with environment\nvariables.\n\nComes packaged with a dotenv file loader.\n\nWorks with [dotenvx][] encrypted .env files and its .env.keys file. Uses same\n[secp256k1](https://en.bitcoin.it/wiki/Secp256k1) encryption.\n\nComes bundled with a helper CLI to encryt and decrypt environment variables more\neasily. See [Encryption](#encryption)\n\n# Install\n\nAdd to your project:\n\n```\nnpm i @commenthol/dotconfig\n```\n\n# Usage\n\nFile: `./config.js`\n\n```js\nimport { dotconfig } from '@commenthol/dotconfig'\n\n// loads process env vars from .env file and process env-vars\nexport const config = dotconfig({\n  port: 8080,\n  http: {\n    proxy: undefined,\n  },\n  https: {\n    cert: '',\n    key: ''\n  },\n  sso: {\n    serverUrl: 'https://my.sso',\n    clientId: 'myClientId',\n    clientSecret: undefined,\n  },\n  isProd: false,\n  names: [], // arrays must be defined!\n  user: {\n    __group: true // groups env vars into object\n                  // Here env-var MUST have min 3 parts with min 2 dashes!\n  },\n  // if loading from file default config var must contain at least `file://`\n  loadFile: 'file://'\n})\n```\n\nwith file: `./.env`\n\n```sh\nexport PORT=3000\nexport HTTP_PROXY=my-proxy:1234\nexport SSO_SERVER_URL=https://other.sso/path\nexport SSO_CLIENT_SECRET=ƚɘɿƆɘƧ\nexport NAMES_0=Alice\nexport NAMES_1=Bob\nexport NAMES_2=Charlie\nexport USER_0_USERNAME=Alice\nexport USER_0_PASSWORD=\"correct horse battery staple\"\nexport USER_1_USERNAME=Bob\nexport USER_1_PASSWORD=ʇǝɹɔǝs\nexport IS_PROD=true\nexport ANY_OTHER_VALUE=1234\n# Multi line values are supported (set them in quotes!)\nexport HTTPS_KEY=\"-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----\"\nexport HTTPS_CERT='-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----'\n# loads content from file relative: `file://./relative` absolute: `file:///absolute`\nexport LOAD_FILE='file://./cert.key'\n# use encrypted values together with a .env.keys file containing DOTENV_PRIVATE_KEY\nDOTENV_PUBLIC_KEY=\"03d599cf2e4febf5e149ab727132117314a640e560f0d5c2395742e8219e9dbeee\"\nHELLO=\"encrypted:BOyGm1Oug6X4b+...wtJ2/j7+PtP1nThQ6YCw\"\n```\n\nresults in `config` being exported as\n\n```js\nconst config = {\n  http: {\n    proxy: 'my-proxy:1234'\n  },\n  https: {\n    key: '-----BEGIN PRIVATE KEY-----\\nMIIE...\\n-----END PRIVATE KEY-----',\n    cert: '-----BEGIN CERTIFICATE-----\\nMIID...\\n-----END CERTIFICATE-----'\n  },\n  port: 3000,\n  sso: {\n    serverUrl: 'https://other.sso/path',\n    clientId: 'myClientId',\n    clientSecret: 'ƚɘɿƆɘƧ'\n  },\n  names: ['Alice', 'Bob', 'Charlie'],\n  user: {\n    0: {\n      username: 'Alice',\n      password: 'correct horse battery staple'\n    },\n    1: {\n      username: 'Bob',\n      password: 'ʇǝɹɔǝs'\n    }\n  },\n  isProd: true,\n  anyOtherValue: '1234',\n  // the content from `LOAD_FILE`\n  loadFile: '-----BEGIN PRIVATE KEY-----\\nMIIE...\\n-----END PRIVATE KEY-----',\n  // decrypted values nor private keys show up in `process.env` object\n  hello: 'world'\n}\n```\n\n\u003ca id=\"encryption\"\u003e \u003c/a\u003e\n\n# Encryption\n\nCan work with [dotenvx](https://dotenvx.com/docs/env-keys-file#encryption)\nencrypted .env files for handling value encryption.\n\nComes bundled with own CLI to handle encryption of values in .env files:\n\n```sh\n# add package to your project first\nnpm i @commenthol/dotconfig\n# get some help\nnpx dotconfig --help\n# create a new .env file with encrypted value \"foo\"\nnpx dotconfig encrypt foo bar\n# lookup decrypted value on stdout\nnpx dotconfig decrypt foo --stdout\n```\n\nℹ️ **NOTE:** Never commit your `.env.keys` file. Keep it in a save place.\n\nTo use a different `.env.keys` file you may use DOTENV_PRIVATE_KEYS_PATH\nenv-var.\n\nDecrypted values only appear in the config object but never in `process.env`.\nPrivate keys are also only used internally for decryption and are deleted if\nthey appear in `process.env`.\n\n# API\n\n## dotconfig\n\ndotconfig calls `dotenv.config()` first before passing the parsed `process.env`\nvariables through `getConfig()`.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ci\u003eTypes\u003c/i\u003e\u003c/summary\u003e\n\n```ts\nfunction dotconfig(\n    /**\n     * The default configuration object\n     */\n    defaultConfig: object, \n    /**\n     * optional configuration options.\n     */\n    options?: DotConfigOptions\n): Record\u003cstring, any\u003e | {};\n\ntype DotConfigOptions = {\n    /**\n     * The path to the dotenv file. Default is '.env' in the current working \n     * directory. May be set via DOTENV_CONFIG_PATH env var.\n     */\n    path?: string | URL | undefined;\n    /**\n     * The encoding of the dotenv file. \n     * May be set via DOTENV_CONFIG_ENCODING env var.\n     */\n    encoding?: BufferEncoding | undefined;\n    /**\n     * Whether to override existing process environment variables. \n     * Default is false. May be set with DOTENV_CONFIG_OVERRIDE=true env var.\n     */\n    override?: boolean | undefined;\n    /**\n     * The process environment object to update. Default is `process.env`.\n     */\n    processEnv?: NodeJS.ProcessEnv | object;\n    /**\n     * if `false` do not add additional props on top-level not part of defaultConfig\n     */\n    additionalProps?: boolean | undefined;\n    /**\n     * if `false` do not add any additional props that are not part of defaultConfig\n     */\n    additionalPropsAll?: boolean | undefined;\n    /**\n     * default=true; Throw on decryption error\n     */\n    throwOnDecryptionError?: boolean | undefined;\n};\n```\n\n\u003c/details\u003e\n\n## dotenv\n\ndotenv comes with two methods `parse()` and `config()`.\n\n`dotenv.config()` returns the parsed `.env` file (if found).\n\n_Usage_\n\n```js\nimport { dotenv } from '@commenthol/dotconfig'\n\n// loads `.env` in current working directory\ndotenv.config()\n\n// loads `.env-local` relative to file\ndotenv.config({\n  path: new URL('./.env-local', import.meta.url)\n})\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ci\u003eTypes\u003c/i\u003e\u003c/summary\u003e\n\n```ts\nfunction config(\n  /**\n   * optional configuration options.\n   * see types above at dotconfig.\n   */\n  options?: DotenvConfigOptions\n): ConfigResult\n\ntype DotenvConfigOptions = {\n  /**\n   * The path to the dotenv file. Default is '.env' in the current working directory. May be set via DOTENV_CONFIG_PATH env var.\n   */\n  path?: string | URL | undefined\n  /**\n   * The encoding of the dotenv file. May be set via DOTENV_CONFIG_ENCODING env var.\n   */\n  encoding?: BufferEncoding | undefined\n  /**\n   * Whether to override existing process environment variables. Default is false. May be set by DOTENV_CONFIG_OVERRIDE env var.\n   */\n  override?: boolean | undefined\n  /**\n   * The process environment object to update. Default is `process.env`.\n   */\n  processEnv?: NodeJS.ProcessEnv | object\n}\n\nexport type ConfigResult = {\n  /** parsed .env file */\n  parsed: Record\u003cstring, string | number | boolean\u003e | {}\n}\n```\n\n\u003c/details\u003e\n\n## getConfig\n\nApplies the lower camel-cased `process.env` variables onto the default\nconfiguration.\n\n_Usage_\n\n```js\nimport { getConfig } from '@commenthol/dotconfig'\n\nprocess.env.HTTP_PORT = '8080'\nprocess.env.HTTPS_PORT = '8443'\n\nconst config = getConfig({\n  http: { port: 80 },\n  https: { port: 443 }\n})\n//\u003e config = {\n//\u003e  http: { port: 8080 },\n//\u003e  https: { port: 8443 }\n//\u003e }\n```\n\n# License\n\nMIT licensed\n\n[npm-badge]: https://badgen.net/npm/v/@commenthol/dotconfig\n[npm]: https://www.npmjs.com/package/@commenthol/dotconfig\n[npm-dm]: https://badgen.net/npm/dm/@commenthol/dotconfig\n[types-badge]: https://badgen.net/npm/types/@commenthol/dotconfig\n[dotenvx]: https://github.com/dotenvx/dotenvx\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommenthol%2Fdotconfig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcommenthol%2Fdotconfig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommenthol%2Fdotconfig/lists"}