env-universal

Standard environment definition, utilities and constants for browser and node JavaScript applications

Introduction

This package provides utilities for working with environment configuration consistently in different runtimes via configuration objects or environment variables.

We created this at WeWork to provide our applications a more consistent runtime. We use it with tools like dotenv and webpack in universal JavaScript applications.

Environment configuration

We use a matrix of variables to define the environment of our applications:

Env | Condition | Notes | ------------ | -----------|----------| development| NODE_ENV is undefined or 'development' | Should only be true in local development environments | production | APP_ENV is 'production' | NODE_ENV should be 'production' for deployments | staging | APP_ENV is 'staging' | NODE_ENV should be 'production' for deployments | preprod | APP_ENV is 'preprod' | NODE_ENV should be 'production' for deployments | qa | APP_ENV is 'qa' | NODE_ENV should be 'production' for deployments | test | NODE_ENV is 'test' or 'testCI' | |

Note that NODE_ENV=production only indicates that the app is deployed (vs running locally in development) and that APP_ENV specifies the environment.

Runtime | Condition | ------------ | -----------| server | SERVER has any value | client | CLIENT has any value |

By default, config is read from environment variables (process.env), but you can also pass in your own configuration object.

Usage

See the documentation. Note that most util functions expect to receive process.env when not calling the root env function.

This package is bundled as a CommonJS module in dist and can be required like any other. The ES2015 source is also exposed via the jsnext:main field in the package.json for loaders that support module syntax directly.

Webpack

utils.getPublicEnv is very handy to safely expose environment config for a client bundle. See docs for getPublicEnv, and our own use of it in test/browser/webpack.config.js.

Examples

import getEnv from 'env-universal';
const env = getEnv();

console.log(env.version);
console.log(env.is.client);
console.log(env.is.server);
console.log(env.is.deployed);
console.log(env.is.production);
console.log(env.is.dev);

Development

1. Checkout this repo
2. Run npm install
3. Make changes in a feature branch and open a PR to master

In lieu of a formal style guide, please:

• follow the conventions present in the codebase
• respect the linter
• keep tests green
• maintain test coverage

npm scripts

npm scripts

Target | Behavior ------------ | ------------- npm test | Runs tests in browser and node runtimes npm run tdd | Runs tests, bundles and re-runs on file changes npm run test:coverage | Runs tests and outputs a code coverage report to /coverage npm run test:ci | Runs tests, outputs code coverage npm run lint | (Run as a git pre-commit hook) Runs eslint npm run docs | Generates API.md from JSDoc comments in /src npm run security-scan | (Run as a git pre-push hook) Checks npm dependencies for security vulnerabilities npm run release <version> | Generates a changelog, updates package version, tags and pushes via np. This should only be run on an up-to-date master by a maintainer of this package. Version can be a semver level: patch | minor | major | prepatch | preminor | premajor | prerelease, or a valid semver version: 1.2.3.

npm run will list all npm scripts