Simple, declarative, and type-safe access to process.env variables.

import { env } from '@kaminooni/env'

enum Environment {
  Production = 'production',
  Development = 'development'
}

const config = {
  environment: env('NODE_ENV').enum(Environment),
  debug: env('DEBUG', false).boolean(),
  port: env('PORT', 3000).range(0, 65536),
  app: {
    name: env('APP_NAME', 'My App').string(),
    secret: env('APP_SECRET').string(),
    apiVersion: env('API_VERSION', 'v3').whitelist(['v1', 'v2', 'v3']),
    emails: env('EMAILS', ['[email protected]']).json<string[]>(),
    retries: env('RETRIES', 5).number(),
  },
}

env(key: string, defaultValue?: string) => VariableBuilder

This function takes Env variable name, reads this variable from process.env and returns the instance of VariableBuilder

VariableBuilder helps you to validate, transform, and cast the env variables to a type of your choice. All values are considered required, unless the default value is provided. If you try to access the non-existent variable, the builder will throw an error.

Converts env variable to string

env('APP_NAME').string()

Converts env variable to boolean Returns true if env value equals 'true' (case-insensitive). Returns false otherwise.

env('DEBUG').boolean()

Converts env variable to number.

NOTE: Empty string '' will be converted to 0.

env('MAX_CONNECTIONS').number()

Verifies that value is in the white list. Throws an Error if it's not.

env('API_VERSION').whitelist(['v1', 'v2', 'v3'])

Verifies that value is a number in the specified range. Both limits are inclusive. Throws an Error if value is not in the specified range.

env('SERVER_PORT', 3000).range(0, 65536)

Converts variable to the member of specified enum. Throws an Error if the value is not a member of the provided Enum.

enum Environment {
  Production = 'production',
  Development = 'development'
}

const ENVIRONMENT: Environment = env('NODE_ENV').enum(Environment)

Converts env variable to JS object using JSON.parse() function

NOTE: This functions doesn't check that JSON comply with the specified type.

const emails: string[] = env('EMAILS', ['[email protected]']).json<string[]>()