npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

localenvironment

v1.2.1

Published

Apply environment variables if they exist in env.json.

Downloads

35

Readme

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.