{"id":19177747,"url":"https://github.com/jessety/env-smart","last_synced_at":"2025-05-07T20:41:59.156Z","repository":{"id":57225922,"uuid":"164069462","full_name":"jessety/env-smart","owner":"jessety","description":"Zero-dependency Node library for using .env files with default values and types in TS/JS","archived":false,"fork":false,"pushed_at":"2025-01-10T21:41:49.000Z","size":203,"stargazers_count":20,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-07T20:41:34.837Z","etag":null,"topics":["configuration","configuration-files","configuration-management","defaults","dotenv","dotenv-parser","dotenv-types","dotenv-typescript","env","environment","environment-configuration","environment-variables","environment-vars","node","nodejs","parse","types","typescript","zero-dependency"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/env-smart","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/jessety.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-01-04T06:47:06.000Z","updated_at":"2025-01-10T21:41:54.000Z","dependencies_parsed_at":"2024-06-18T21:30:28.982Z","dependency_job_id":"fbaa52fe-6418-4ee1-b87a-0fbbae106e6b","html_url":"https://github.com/jessety/env-smart","commit_stats":{"total_commits":107,"total_committers":4,"mean_commits":26.75,"dds":"0.11214953271028039","last_synced_commit":"81eecea848a7bc221dcffcf3e80e91bc17297f93"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jessety%2Fenv-smart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jessety%2Fenv-smart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jessety%2Fenv-smart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jessety%2Fenv-smart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jessety","download_url":"https://codeload.github.com/jessety/env-smart/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252954127,"owners_count":21830893,"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":["configuration","configuration-files","configuration-management","defaults","dotenv","dotenv-parser","dotenv-types","dotenv-typescript","env","environment","environment-configuration","environment-variables","environment-vars","node","nodejs","parse","types","typescript","zero-dependency"],"created_at":"2024-11-09T10:34:56.806Z","updated_at":"2025-05-07T20:41:59.121Z","avatar_url":"https://github.com/jessety.png","language":"TypeScript","readme":"# env-smart\n\nZero-dependency library for using .env files with types and default values\n\n[![ci](https://github.com/jessety/env-smart/workflows/ci/badge.svg)](https://github.com/jessety/env-smart/actions)\n[![coverage](https://codecov.io/gh/jessety/env-smart/branch/main/graph/badge.svg?token=F0L99B4KW5)](https://codecov.io/gh/jessety/env-smart)\n[![npm](https://img.shields.io/npm/v/env-smart.svg)](https://www.npmjs.com/package/env-smart)\n[![license](https://img.shields.io/github/license/jessety/env-smart.svg)](https://github.com/jessety/env-smart/blob/main/LICENSE)\n\n`env-smart` is a lightweight, zero-dependency library for loading configuration from environmental variables and `.env` files in JavaScript or TypeScript. It is designed to solve two common issues with environmental variables:\n\n- Variable types\n- Default values\n\nIn both situations, logic specific to the configuration (type casting, default checking) ends up seeping into the application logic. If any of these values are re-used in different parts of the app this can even lead to duplication.\n\nInstead, `env-smart` enables declaring default values and types for all environmental variables in additional configuration files. It loads the contents of the `.env` file if present, but defaults and type checking are applied to the process' env if not.\n\n## Installation\n\n```bash\nnpm install env-smart\n```\n\n## Usage\n\nCalling `.load()` populates `process.env` with the contents of a `.env` file in the root directory of your project, as well as the process' environmental variables.\n\n```javascript\n// Modules\nimport env from 'env-smart';\nenv.load();\n\n// CommonJS\nrequire('env-smart').load();\n\nconsole.log(process.env.PORT);\n```\n\nUsing a `.env` file to store environmental variables makes managing different configurations between deployments much easier. Example file:\n\n```ini\nPORT=8080\nVERBOSE=TRUE\nAPI_KEY=xyz\n```\n\n### Strictly Typed Configuration\n\nIf you're using TypeScript, the `config` function makes parsing strictly typed configurations simple:\n\n```typescript\nimport envSmart from 'env-smart';\n\n// Define config type\nexport type Configuration = {\n  host: string;\n  port: number;\n  verbose: boolean;\n};\n\n// Transform the dictionary into a configuration type\nexport const config = envSmart.config\u003cConfiguration\u003e((env) =\u003e {\n  // `env` is now populated from the .env file, process env, and defaults\n  return {\n    host: env.HOST,\n    port: env.PORT,\n    verbose: env.VERBOSE\n  };\n});\n\n// `config` is now strictly typed\nconsole.log(`Host: ${config.host} port: ${config.port} verbose: ${config.verbose} `);\n```\n\n### Types and Defaults\n\nIn addition to the main `.env` file, `env-smart` also checks for two additional optional configuration files: `.env.defaults` and `.env.types`.\n\nDefault values are set in the `.env.defaults` file:\n\n```ini\nPORT=80\nVERBOSE=FALSE\n```\n\nIf an environmental variable is otherwise empty empty, it's value from `.env.defaults` will be used.\n\nTypes are set in the `.env.types` file:\n\n```ini\nPORT=number\nVERBOSE=boolean\n```\n\nSupported types are: `string`, `number`, `boolean`, `object` and `array`.\n\nAlternatively, variable types may be declared inline in the `.env.defaults` file:\n\n```ini\nPORT=number=80\nVERBOSE=boolean=FALSE\n```\n\nOnce defaults and types are set, loading is a breeze:\n\n```javascript\nrequire('env-smart').load();\n\nconsole.log(`${process.env.PORT}: ${typeof process.env.PORT}`);\n// 80: number\n```\n\nProcess environmental variables take precedence over the contents of a `.env` file, and type checking is still applied.\n\n```bash\nexport PORT=8080 \u0026\u0026 node index.js\n```\n\n```javascript\nrequire('env-smart').load();\nconsole.log(`${process.env.PORT}: ${typeof process.env.PORT}`);\n// 8080: number\n```\n\nBoth `.env.defaults` and `.env.types` should not contain any secrets, and should be committed to version control systems. Be careful to never commit the `.env` file.\n\n### Options\n\nThe `load()` function supports a few optional parameters:\n\n```javascript\nrequire('env-smart').load({\n  directory: __dirname, // manually specify the directory to load .env files from\n  encoding: 'utf8', // manually specify the encoding of the .env files\n  lowercase: true, // make all keys lower case.\n  // uppercase: true, // make all keys upper case\n  verbose: true, // output debug information to the console\n  process: false, // if set to false, don't parse the process env, only dotfiles\n  inlineTypes: false, // don't allow inline type declarations in .env or .env.defaults, e.g. PORT=number=8080\n\n  envFilename: '.env', //  manually specify .env file name\n  envDefaultsFilename: '.env.defaults', // manually specify .env.defaults file name\n  envTypesFilename: '.env.types' // manually specify .env.types file name\n});\n\n// The 'PORT' value has been re-named 'port' by including the `lowercase` option\nconsole.log(`${process.env.port}: ${typeof process.env.port}`);\n```\n\nInclude `replace: false` option to return the parsed values without replacing the contents of `process.env`:\n\n```javascript\nconst settings = require('env-smart').load({ replace: false, lowercase: true });\n\nconsole.log(settings.port);\n```\n\n## License\n\nMIT © Jesse T Youngblood\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjessety%2Fenv-smart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjessety%2Fenv-smart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjessety%2Fenv-smart/lists"}