{"id":15649307,"url":"https://github.com/sholladay/envy","last_synced_at":"2025-04-30T15:46:47.577Z","repository":{"id":57226073,"uuid":"106071550","full_name":"sholladay/envy","owner":"sholladay","description":"Load .env files and environment variables","archived":false,"fork":false,"pushed_at":"2020-09-12T05:30:56.000Z","size":1233,"stargazers_count":39,"open_issues_count":5,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-29T19:55:06.326Z","etag":null,"topics":["conf","config","configuration","dotenv","dotfile","env","envfile","environment","keys","loader","secrets","security","variables","vars"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sholladay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-07T04:32:54.000Z","updated_at":"2022-09-20T20:38:07.000Z","dependencies_parsed_at":"2022-08-24T10:40:31.650Z","dependency_job_id":null,"html_url":"https://github.com/sholladay/envy","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sholladay%2Fenvy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sholladay%2Fenvy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sholladay%2Fenvy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sholladay%2Fenvy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sholladay","download_url":"https://codeload.github.com/sholladay/envy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245907556,"owners_count":20691956,"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":["conf","config","configuration","dotenv","dotfile","env","envfile","environment","keys","loader","secrets","security","variables","vars"],"created_at":"2024-10-03T12:29:11.467Z","updated_at":"2025-03-31T15:31:02.515Z","avatar_url":"https://github.com/sholladay.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [![envy](media/header.png)](https://github.com/sholladay/envy)\n\n\u003e Load .env files and environment variables\n\n[![Build status for Envy](https://travis-ci.com/sholladay/envy.svg?branch=master \"Build Status\")](https://travis-ci.com/sholladay/envy \"Builds\")\n\nSecure and friendly alternative to [dotenv](https://npmjs.com/package/dotenv), using functional programming, with strong tests to prove its safety.\n\nFollows the [Twelve Factor App](https://12factor.net) methodology.\n\n## Contents\n\n - [Why?](#why)\n - [Install](#install)\n - [Usage](#usage)\n - [API](#api)\n - [Tips](#tips)\n - [FAQ](#faq)\n - [Resources](#resources)\n - [Related](#related)\n - [Contributing](#contributing)\n - [License](#license)\n\n## Why?\n\n - Safest environment loader around.\n - Validates file permissions are secure.\n - Validates required env vars are defined.\n - No side effects, does not modify [`process.env`](https://nodejs.org/api/process.html#process_process_env).\n - Returns property names in [camelCase](https://github.com/sindresorhus/camelcase).\n - Asserts that `.env` is ignored in git.\n\nYou want to keep your secrets safe, right? `envy` loads your app's configuration values from a `.env` file and prevents mistakes, such as accidentally committing the `.env` file to your repository, or leaving `.env` with unsafe permissions.\n\nHave you spent a day rotating passwords because a developer accidentally pushed them to the repository? Yeah, that actually happens and it can cause chaos at companies. It doesn't matter if you delete the commit. Once it's out there, game over. People who are authorized to read the repository may not be authorized to have those credentials, including third party tools and services. If the repository is public, search engines may have crawled it. Consider everything to be compromised.\n\nThe `envy` module helps you prevent that situation by providing a convenient mechanism for everyone to store credentials and other config locally and validate that it is correct without commiting them to the repository. It verifies that all relevant files have secure permissions and that the secrets file is explicitly ignored so that it cannot accidentally be commited.\n\n## Install\n\n```sh\nnpm install envy --save\n```\n\n## Usage\n\n```js\nconst envy = require('envy');\nconst env = envy();\nconsole.log(env);\n// {\n//     foo : 'bar'\n// }\n```\n\nA `.env.example` file is used as a template to determine which environment variables are required by your application. This file should be commited to your repository.\n\n```sh\n# .env.example\nFOO=\n```\n\nA `.env` file is used to provide the actual environment values. You must add this file to a local [`.gitignore`](https://help.github.com/articles/ignoring-files) to prevent leaking secrets and `envy` will check that you did this correctly.\n\n```sh\n# .env\nFOO=bar\n```\n\nEnvironment files look just like normal shell files (e.g. `.bashrc` and friends). Values may be optionally wrapped in `'` single quotes. This is recommended for shell compatibility, in case the value contains whitespace.\n\n```sh\n# This is a comment.\nFOO=bar\nSENTENCE='Hi, there!'\n```\n\nAfter assembling the environment from `.env` and [`process.env`](https://nodejs.org/api/process.html#process_process_env), it is filtered by a union of the properties in `.env` and `.env.example`. In other words, variables defined in either file will be returned and variables not defined in either file will be ignored. This is done to prevent surprising behavior, since `process.env` often contains a wide variety of variables, some of which are implicitly set without the user's direct knowledge. It is better to be explicit about the variables you use, which improves safety and debugging.\n\n## API\n\n### envy(filepath)\n\nReturns an `object` with environment variables derived from [`process.env`](https://nodejs.org/api/process.html#process_process_env) and the contents at `filepath`. If a variable is defined in both places, `process.env` takes precedence so that users can easily override values on the command line. If all required variables are present in `process.env`, then the `.env` file need not exist. All property names are returned in camelcase.\n\n#### filepath\n\nType: `string`\u003cbr\u003e\nDefault: `.env`\n\nPath to the file where environment variables are kept. Must be [hidden](https://en.wikipedia.org/wiki/Hidden_file_and_hidden_directory#macOS) (start with a `.`). Will also be used to compute the path of the example file (by appending `.example`).\n\n## Tips\n\n### Mixing with command line options\n\nMake a CLI with [meow](https://github.com/sindresorhus/meow) and use [joi](https://github.com/hapijs/joi) to further validate and parse the returned values.\n\n```js\n// cli.js\nconst meow = require('meow');\nconst envy = require('envy');\nconst joi = require('joi');\n\nconst cli = meow();\n\nconst input = Object.assign({}, envy(), cli.flags);\nconst config = joi.attempt(input, {\n    port : joi.number().positive().integer().min(0).max(65535)\n});\n// value.port has been parsed as a number\nconsole.log('port:', config.port);\n```\n```sh\n# .env.example\nPORT=\n```\n```sh\n# .env\nPORT=1000\n```\n\n```console\n$ node cli.js\nport: 1000\n$ PORT=2000 node cli.js\nport: 2000\n$ node cli.js --port=3000\nport: 3000\n$ PORT=2000 node cli.js --port=3000\nport: 3000\n```\n\n### Modifying `process.env`\n\nWe recommend not using `process.env` directly. But let's say you want to because a dependency expects you to set `NODE_ENV` and you want to define it in `.env`. No problem!\n\n*You should first ask the project to accept options as input so you don't need this.*\n\n```js\nconst envy = require('envy');\nconst decamelize = require('decamelize');\n\nconst override = Object.entries(envy()).reduce((result, [key, val]) =\u003e {\n    result[decamelize(key).toUpperCase()] = val;\n    return result;\n}, {});\nObject.assign(process.env, override);\n```\n\n## FAQ\n\n### Why not `dotenv` or `dotenv-safe`?\n\nI see this as a successor to those projects. But `envy` would not exist without them. `dotenv` brought `.env` files mainstream in Node.js projects. `dotenv-safe` improved on it by introducing the `.env.example` file. Now, `envy` takes this even further by securing your files and returning an object with camelcase keys rather than modifying `process.env`.\n\n## Resources\n\n - [Think about sensitive data](http://blog.arvidandersson.se/2013/06/10/credentials-in-git-repos)\n - [Manage secrets safely](https://digitalocean.com/community/tutorials/an-introduction-to-managing-secrets-safely-with-version-control-systems)\n - [Remove secrets from a repository](https://help.github.com/articles/removing-sensitive-data-from-a-repository/)\n - [Store config in the environment](https://12factor.net/config)\n\n# Related\n\n - [meow](https://github.com/sindresorhus/meow) - Make command line apps\n\n## Contributing\n\nSee our [contributing guidelines](https://github.com/sholladay/envy/blob/master/CONTRIBUTING.md \"Guidelines for participating in this project\") for more details.\n\n1. [Fork it](https://github.com/sholladay/envy/fork).\n2. Make a feature branch: `git checkout -b my-new-feature`\n3. Commit your changes: `git commit -am 'Add some feature'`\n4. Push to the branch: `git push origin my-new-feature`\n5. [Submit a pull request](https://github.com/sholladay/envy/compare \"Submit code to this project for review\").\n\n## License\n\n[MPL-2.0](https://github.com/sholladay/envy/blob/master/LICENSE \"License for envy\") © [Seth Holladay](https://seth-holladay.com \"Author of envy\")\n\nGo make something, dang it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsholladay%2Fenvy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsholladay%2Fenvy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsholladay%2Fenvy/lists"}