README.md

Local Environment

tl;dr Create environment variables at runtime from a JSON configuration file, if one exists.

Usage

This 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).

As 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.

As 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).

Using the module is extremely simple (one line of JavaScript). Consider the following project directory:

> dir
  - env.json
  - index.js

The env.json may look like:

{
  "MY_VARIABLE_1": "abc",
  "MY_VARIABLE_2": "def"
}

The index.js file would look like:

require('localenvironment') // <-- This is all the code you need.
import LE from 'localenvironment' // <-- ES Module variation of the line above

console.log(process.env.MY_VARIABLE_1)
console.log(process.env.MY_VARIABLE_2)

Here's what's happening...

Running this code would output the following:

abc
def

The module reads the env.json file and applies the variables in such a manner that they are accessible just like any other environment variable.

Now consider the exact same index.js file run in a Docker container without a config file:

docker run -e "MY_VARIABLE_1=ghi" -e "MY_VARIABLE_2=jkl" node index.js

(This is pseduo code, for illustration purposes)

The output would be:

ghi
jkl

The 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.

Custom File

As 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.

For example:

let myEnvironment = require('localenvironment')
myEnvironment.load('/path/to/myconfig.json')

Additional Features

The module will return an object of the variables it injected into the environment.

let myEnvironment = require('localenvironment)

console.log(myEnvironment)

This would output the following:

{
  "MY_VARIABLE_1": "abc",
  "MY_VARIABLE_2": "def"
}

This feature can be useful for understanding what was configured by the module and what wasn't.

Executing Programs

There 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.

For example, consider a package.json file with the following npm script:

"test": "CF_API_TOKEN=plaintext_secret wrangler dev --env development"

The 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:

"test": "localenvironment wrangler dev --env development"

localenvironment loads the environment variables from the env.json file, then runs the wrangler dev --env development command with those environment variables.

---

Intended Use

It'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.

This module allows developers to write one line of code that will run predictably in any environment.

The developer's responsibility is to configure environment variables correctly, not to write conditional logic that manipulates the envionrment.

There 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.

Your 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.

If you came here looking for ways to force-require or detect local environment variables, have a look at musthave instead.