{"id":14155645,"url":"https://github.com/LeoBakerHytch/ts-dotenv","last_synced_at":"2025-08-06T01:31:59.256Z","repository":{"id":35088500,"uuid":"205031766","full_name":"LeoBakerHytch/ts-dotenv","owner":"LeoBakerHytch","description":"Strongly-typed environment variables for Node.js","archived":false,"fork":false,"pushed_at":"2024-04-01T15:44:59.000Z","size":510,"stargazers_count":44,"open_issues_count":5,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-08-17T08:05:44.784Z","etag":null,"topics":["12-factor","dotenv","env","environment","environment-variables","node","nodejs","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/LeoBakerHytch.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-28T22:08:22.000Z","updated_at":"2024-07-23T02:27:41.000Z","dependencies_parsed_at":"2024-06-18T15:32:33.277Z","dependency_job_id":"a144e883-7a5c-4d7b-b784-f858f9fed103","html_url":"https://github.com/LeoBakerHytch/ts-dotenv","commit_stats":{"total_commits":158,"total_committers":5,"mean_commits":31.6,"dds":"0.38607594936708856","last_synced_commit":"1f31c2679bb9312c6b35ae47c20c8c50853c4ec5"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeoBakerHytch%2Fts-dotenv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeoBakerHytch%2Fts-dotenv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeoBakerHytch%2Fts-dotenv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeoBakerHytch%2Fts-dotenv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LeoBakerHytch","download_url":"https://codeload.github.com/LeoBakerHytch/ts-dotenv/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228821409,"owners_count":17977168,"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":["12-factor","dotenv","env","environment","environment-variables","node","nodejs","typescript"],"created_at":"2024-08-17T08:04:40.769Z","updated_at":"2024-12-09T02:31:30.165Z","avatar_url":"https://github.com/LeoBakerHytch.png","language":"TypeScript","funding_links":[],"categories":["typescript"],"sub_categories":[],"readme":"# ts-dotenv\n\nStrongly-typed Node.js environment variables from `.env` and `process.env`.\n\n[![Version](https://badgen.net/npm/v/ts-dotenv)](https://npmjs.org/package/ts-dotenv)\n[![License](https://badgen.net/github/license/LeoBakerHytch/ts-dotenv)](https://github.com/LeoBakerHytch/ts-dotenv/blob/master/LICENSE)\n[![Coveralls](https://badgen.net/coveralls/c/github/LeoBakerHytch/ts-dotenv)](https://coveralls.io/github/LeoBakerHytch/ts-dotenv)\n![Downloads](https://img.shields.io/npm/dt/ts-dotenv.svg)\n\n## Motivation\n\nLoad environment variables from a `.env` file for development, but deploy to an environment that injects them directly\n(on `process.env`) with no logic needed to differentiate dev from prod. Values from disk are merged with the process\nenvironment (you decide whether `process.env` or `.env` takes precedence), validated against a simple schema, and\ncoerced to the appropriate types.\n\n`ts-dotenv` maintains [dev/prod parity][0] by not caring whether variables come from `.env` or `process.env`, as long as\nthey’re all present and the correct types. Otherwise, it fails fast, so your alarms should start going off and/or your\nrolling releases will abort. The thrown error details which variables are missing or have the wrong types.\n\n**Caution**: Be careful removing variables from your prod environment; be sure to first remove them from the schema,\notherwise your server won’t boot and it will have nothing to roll back to. (Or you could catch the error `ts-dotenv`\nthrows, and do your own logging or alerts, but you’ll lose automatic protection from pushing out builds with missing\nvariables. It’s a trade-off.)\n\n[0]: https://12factor.net/dev-prod-parity\n\n## Usage\n\n```env\n# Comments are supported\nTRACING=true\nPORT=3000\nNODE_ENV=production\nAPP_NAME=test-app\nBASE_URL=https://api.example.com\n#BASE_URL=https://development-api.example.com\nBASE64_ENCODED=8J+agA==\nEXTRA=true\n```\n\n```typescript\nimport { strict as assert } from 'assert';\nimport { load } from 'ts-dotenv';\n\nconst env = load({\n    TRACING: Boolean,\n    PORT: Number,\n    APP_NAME: /^[-a-z]+$/,\n    BASE_URL: String,\n    NODE_ENV: ['production' as const, 'development' as const],\n    BASE64_ENCODED: Buffer,\n});\n\nassert.ok(env.TRACING === true);\nassert.ok(env.PORT === 3000);\nassert.ok(env.APP_NAME === 'test-app');\nassert.ok(env.NODE_ENV === 'production');\nassert.ok(env.BASE_URL === 'https://api.example.com');\nassert.ok(env.BASE64_ENCODED === Buffer.from('🚀'));\nassert.ok(env.EXTRA === undefined);\n```\n\nNote:\n\n-   `Number` only supports integers\n-   Only string unions are supported\n-   Use `as const` with string unions, to ensure a proper resulting environment type\n-   All values may be surrounded by leading and / or trailing whitespace, which is ignored (unless it’s quoted: see below)\n\n### Strings\n\nStrings may be single- or double-quoted. Leading and / or trailing whitespace is ignored, unless it’s inside the quotes.\n\n```env\nUNQUOTED= Lorem ipsum\nSINGLE_QUOTED= 'Lorem ipsum'\nDOUBLE_QUOTED= \"Lorem ipsum\"\nQUOTED_WITH_PRESERVED_WHITESPACE= \" Lorem ipsum \"\n```\n\nWithin double quotes, escaped newlines (`\\n`) / carriage returns (`\\r`) are converted to their corresponding literal\ncharacters.\n\n```env\nDOUBLE_QUOTED_WITH_NEWLINE=\"Lorem\\nipsum\"\nDOUBLE_QUOTED_WITH_CR=\"Lorem\\ripsum\"\n```\n\n### Optionals \u0026 defaults\n\nOptional fields and default values can be defined with an extended schema specifier; for example:\n\n```typescript\nconst schema = {\n    TRACING: {\n        type: Boolean,\n        optional: true,\n    },\n    NODE_ENV: {\n        type: String,\n        default: 'local',\n    },\n} as const;\n```\n\n### Boot\n\nRun `ts-dotenv` from your app’s entry, to ensure variables are loaded before you wire up services and start serving\nrequests. The following pattern makes for easy, type-safe consumption of variables throughout your app:\n\n#### `index.ts`\n\n```typescript\nimport { loadEnv } from './env';\n\nloadEnv(); // Executed synchronously before the rest of your app loads\n\nrequire('./server'); // Your server’s actual entry\n```\n\n#### `env.ts`\n\n```typescript\nimport { EnvType, load } from 'ts-dotenv';\n\nexport type Env = EnvType\u003ctypeof schema\u003e;\n\nexport const schema = {\n    NODE_ENV: String,\n};\n\nexport let env: Env;\n\nexport function loadEnv(): void {\n    env = load(schema);\n}\n```\n\n#### `example-module.ts`\n\n```typescript\nimport { env } from './env';\n\nif (env.NODE_ENV === 'production') {\n    // ...\n}\n```\n\n### Options\n\nBy default:\n\n-   Values in `process.env` take precedence\n-   `.env` is the expected file name, loaded from the working directory\n\nChange this through options:\n\n```typescript\nimport { resolve } from 'path';\nimport { load } from 'ts-dotenv';\nconst env = load(schema, 'lib/.env');\n```\n\n```typescript\nimport { resolve } from 'path';\nimport { load } from 'ts-dotenv';\n\nconst env = load(schema, {\n    path: resolve(__dirname, '.env'),\n    encoding: 'iso-8859-1',\n    overrideProcessEnv: true,\n});\n```\n\n## Acknowledgements\n\nThis was inspired by [`dotenv`][1] and [`dotenv-extended`][2], but written for first-class use in a TypeScript project.\n\n[1]: https://www.npmjs.com/package/dotenv\n[2]: https://www.npmjs.com/package/dotenv-extended\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLeoBakerHytch%2Fts-dotenv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FLeoBakerHytch%2Fts-dotenv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLeoBakerHytch%2Fts-dotenv/lists"}