✓ valienv

A simple environment variables validator for Node.js, web browsers and React Native.

Installation

$ npm i valienv --save
# --- or ---
$ yarn add valienv

📘 Usage

This library exports a main function: validate. Using validators, you can parse, validate and type required environment variables (other variables will be excluded).

import { boolean, number, oneOf, string, validate } from "valienv";

// with process.env = {
//   ACCENT_COLOR: "#0099e5",
//   TIMEOUT_MS: "5000",
//   ENABLE_ANALYTICS: "true",
//   NODE_ENV: "development",
// }

export const env = validate({
  env: process.env,
  validators: {
    // we validate env using bundled validators
    ACCENT_COLOR: string,
    TIMEOUT_MS: number,
    ENABLE_ANALYTICS: boolean,
    NODE_ENV: oneOf("development", "test", "production"),
  },
});

// -> typeof env = Readonly<{
//   ACCENT_COLOR: string;
//   TIMEOUT_MS: number;
//   ENABLE_ANALYTICS: boolean;
//   NODE_ENV: "development" | "test" | "production";
// }>

⚠️  In case of incorrect environment variables, the function will throw an EnvValidationError exposing variables names (not their values) to prevent your application from starting.

overrides

The overrides option is useful to override some variables in some contexts.

import { string, validate } from "valienv";

// with process.env = {
//   CONTACT_EMAIL: "[email protected]",
// }

export const env = validate({
  env: process.env,
  validators: {
    CONTACT_EMAIL: string,
  },
  overrides: {
    ...(process.env.NODE_ENV === "test" && {
      CONTACT_EMAIL: "no-mail",
    }),
  },
});

// -> typeof env = Readonly<{ CONTACT_EMAIL: string }>

⚠️  The values set has to be correctly typed but are not validated.

Custom validators

By default, valienv exports 6 validators: string, number, boolean, url, port and email. It also offers oneOf, a helper to create validators for union of string literals.

It's very easy to write your own:

import { validate, Validator } from "valienv";

// A validator take raw input, try to parse it and
// returns the result in case of valid value:
const buffer: Validator<Buffer> = (value: string = "") => {
  const valid = /^[A-F\d]+$/i.test(value);

  if (valid) {
    return Buffer.from(value);
  }
};

// with process.env = {
//   COOKIE_KEY: "aba4a6fb2222ef28d81e4be445a51fba",
// }

export const env = validate({
  env: process.env,
  validators: {
    COOKIE_KEY: buffer,
  },
});

// -> typeof env = Readonly<{ COOKIE_KEY: Buffer }>

You can even go wild by using stricter types, complex parsing, your favorite validation library, etc! 🔥

import validator from "validator";
import { validate } from "valienv";

// with process.env = {
//   ETHEREUM_ADDRESS: "0xb794f5ea0ba39494ce839613fffba74279579268",
//   OPENED_COUNTRIES: "FR,BE,DE",
// }

export const env = validate({
  env: process.env,
  validators: {
    // inlined validators return types are correctly inferred
    ETHEREUM_ADDRESS: (value = "") => {
      if (validator.isEthereumAddress(value)) {
        return value;
      }
    },
    OPENED_COUNTRIES: (value = "") => {
      const array = value.split(",");

      if (array.every(validator.isISO31661Alpha2)) {
        return array;
      }
    },
  },
});

// -> typeof env = Readonly<{
//   ETHEREUM_ADDRESS: string;
//   OPENED_COUNTRIES: string[];
// }>

Optional values

As it's a common pattern to have some optional environment values, we provide optional, a small helper to wrap every validator with:

import { optional, string, validate } from "valienv";

const env = validate({
  env: process.env,
  validators: {
    FOO: optional(string),
  },
});

if (env.FOO.defined) {
  console.log(env.FOO.value); // FOO.value can only be accessed when defined is true
}

You can also wrap validators using a library of your choice. Here's an example with @swan-io/boxed:

import { string, validate } from "valienv";
import { Option } from "@swan-io/boxed";

const optional =
  <T>(validator: Validator<T>): Validator<Option<T>> =>
  (value) =>
    Option.fromUndefined(validator(value));

const env = validate({
  env: process.env,
  validators: {
    FOO: optional(string),
  },
});

env.FOO.match({
  Some: (value) => {
    // env.FOO is set, you can use its value
  },
  None: () => {
    // env.FOO isn't set
  },
});

❓ Questions

Why not handling NODE_ENV for us?

Frontend bundlers generally statically replace process.env.NODE_ENV values at build time, allowing minifiers like terser to eliminate dead code from production build. Aliasing NODE_ENV would prevent such optimisations. But if you are working with Node.js, feel free to use oneOf on NODE_ENV if you want.