{"id":16431830,"url":"https://github.com/coreybutler/localenvironment","last_synced_at":"2025-03-16T17:35:28.480Z","repository":{"id":35395925,"uuid":"39659955","full_name":"coreybutler/localenvironment","owner":"coreybutler","description":"Simply and optionally apply environment variables if they exist in env.json.","archived":false,"fork":false,"pushed_at":"2024-07-14T14:35:52.000Z","size":93,"stargazers_count":22,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-21T08:26:49.538Z","etag":null,"topics":["environment-configuration","environment-manager","environment-variables"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coreybutler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"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},"funding":{"github":["coreybutler"],"patreon":"coreybutler","open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2015-07-24T22:00:43.000Z","updated_at":"2024-08-27T22:33:58.000Z","dependencies_parsed_at":"2024-10-14T08:01:46.529Z","dependency_job_id":"ce0e73b4-12e4-4095-99fe-77513a0e2e7a","html_url":"https://github.com/coreybutler/localenvironment","commit_stats":{"total_commits":21,"total_committers":3,"mean_commits":7.0,"dds":0.1428571428571429,"last_synced_commit":"85d5b2ab190489a0869212d767b2da0f10e53a69"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coreybutler%2Flocalenvironment","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coreybutler%2Flocalenvironment/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coreybutler%2Flocalenvironment/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coreybutler%2Flocalenvironment/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coreybutler","download_url":"https://codeload.github.com/coreybutler/localenvironment/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221346872,"owners_count":16802122,"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":["environment-configuration","environment-manager","environment-variables"],"created_at":"2024-10-11T08:32:54.118Z","updated_at":"2024-10-27T11:00:00.565Z","avatar_url":"https://github.com/coreybutler.png","language":"JavaScript","funding_links":["https://github.com/sponsors/coreybutler","https://patreon.com/coreybutler"],"categories":[],"sub_categories":[],"readme":"# Local Environment\n\n**tl;dr** Create environment variables at runtime from a JSON configuration file, _if one exists_.\n\n## Usage\n\nThis module loads environment variables from a configuration file, _if the file exists_. Each attribute will be assigned to the `process.env` object. If the file does not exist, it does nothing (i.e. won't break the script).\n\nAs of version 1.1.0, the module looks for `env.json`, `.env.json`, and `.env` (expects JSON content). It is also possible to look for a file with a different name (see Custom Config section below). It only loads the first file it finds.\n\nAs of version 1.2.0, a command line tool was included, allowing other executables to be run with the local environment variables pre-applied to the runtime (see \"Executing Programs\" section for details).\n\nUsing the module is extremely simple (one line of JavaScript). Consider the following project directory:\n\n```sh\n\u003e dir\n  - env.json\n  - index.js\n```\n\nThe `env.json` may look like:\n\n```json\n{\n  \"MY_VARIABLE_1\": \"abc\",\n  \"MY_VARIABLE_2\": \"def\"\n}\n```\n\nThe `index.js` file would look like:\n\n```javascript\nrequire('localenvironment') // \u003c-- This is all the code you need.\nimport LE from 'localenvironment' // \u003c-- ES Module variation of the line above\n\nconsole.log(process.env.MY_VARIABLE_1)\nconsole.log(process.env.MY_VARIABLE_2)\n```\n\n_Here's what's happening..._\n\nRunning this code would output the following:\n\n```sh\nabc\ndef\n```\n\nThe module reads the `env.json` file and applies the variables in such a manner that they are accessible just like any other environment variable.\n\nNow consider the exact same `index.js` file run in a Docker container _without a config file_:\n\n```sh\ndocker run -e \"MY_VARIABLE_1=ghi\" -e \"MY_VARIABLE_2=jkl\" node index.js\n```\n_(This is pseduo code, for illustration purposes)_\n\nThe output would be:\n\n```sh\nghi\njkl\n```\n\nThe only difference between these examples is the first was configured through a local JSON file and the second was configured through Docker environment variables. The **JavaScript didn't change** from one environment to the other.\n\n## Custom File\n\nAs of version 1.1.0, it is possible to tell localenvironment to search for a custom filename. The name of the file can be passed to the module as an argument.\n\nFor example:\n\n```javascript\nlet myEnvironment = require('localenvironment')\nmyEnvironment.load('/path/to/myconfig.json')\n```\n\n## Additional Features\n\nThe module will return an object of the variables it injected into the environment.\n\n```javascript\nlet myEnvironment = require('localenvironment)\n\nconsole.log(myEnvironment)\n```\n\nThis would output the following:\n\n```json\n{\n  \"MY_VARIABLE_1\": \"abc\",\n  \"MY_VARIABLE_2\": \"def\"\n}\n```\n\nThis feature can be useful for understanding what was configured by the module and what wasn't.\n\n## Executing Programs\n\nThere are occasions where other programs need to be executed from npm scripts, using local environment variables. For example, Cloudflare workers use the `wrangler` executable to create a test environment. The test environment requires an API secret to be available in the environment variables. Instead of embedding this value in an npm script, it can remain in a `env.json` file (which should be in `.gitignore`/not committed), localenvironment can run it with the variable applied dynamically.\n\nFor example, consider a `package.json` file with the following npm script:\n\n`\"test\": \"CF_API_TOKEN=plaintext_secret wrangler dev --env development\"`\n\nThe API token would be committed in plain text in this file, which should be avoided. Instead, assume `env.json` contains the `CF_API_TOKEN` value. This can be applied with the following npm script:\n\n`\"test\": \"localenvironment wrangler dev --env development\"`\n\n`localenvironment` loads the environment variables from the `env.json` file, then runs the `wrangler dev --env development` command with those environment variables.\n\n---\n\n#### Intended Use\n\nIt's common practice to use a different configurations for development and production. For example, many people use Development API keys when creating on †heir workstation, but Production API keys when running the code on a live server.\n\nThis module allows developers to write one line of code that will run predictably in any environment.\n\n**The developer's responsibility is to configure environment variables correctly, _not to write conditional logic that manipulates the envionrment_.**\n\nThere are also programs written that function differently _if an environment variable exists_. This module won't fire an error if it doesn't find the `env.json`, so it's easy to manipulate the environment simply by commenting out some code or changing a file name.\n\nYour mileage will vary, but I've found this to be much simpler than writing shell/batch files and other wrappers to manage environment variables. The pattern is used so often I even [ported it to Golang](https://github.com/coreybutler/go-localenvironment).\n\nIf you came here looking for ways to force-require or detect local environment variables, have a look\nat [musthave](https://github.com/coreybutler/musthave) instead.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoreybutler%2Flocalenvironment","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoreybutler%2Flocalenvironment","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoreybutler%2Flocalenvironment/lists"}