12factor-env

12factor-env

Environment variable validation for 12-factor apps

A TypeScript library for validating environment variables. Built on top of envalid.

Installation

npm install 12factor-env

Usage

import { env, str, num, bool, port, email, host } from '12factor-env';

const config = env(
  process.env,
  {
    // Required environment variables
    DATABASE_URL: str(),
    API_KEY: str()
  },
  {
    // Optional environment variables with defaults
    PORT: port({ default: 3000 }),
    DEBUG: bool({ default: false }),
    LOG_LEVEL: str({ default: 'info' })
  }
);

console.log(config.DATABASE_URL); // Validated string
console.log(config.PORT);         // Validated number

Fallback classes: withDefault / devDefault / required

The real question for any config value is not "optional vs required" but "is there an honest fallback?". These thin wrappers over any envalid validator make that intent explicit at the declaration site:

import { env, str, url, withDefault, devDefault, required } from '12factor-env';

const config = env(process.env, {}, {
  // Class 1 — honest fallback in every environment (ports, timeouts, flags)
  JOBS_SCHEMA:              withDefault(str, 'app_jobs'),

  // Class 2 — fallback in dev/test, but REQUIRED (throws) in production.
  // A localhost base domain is fine locally, a bug in prod.
  SYNC_GATEWAY_BASE_DOMAIN: devDefault(str, 'sync.localhost'),

  // Class 3 — no honest fallback; throws in every environment when absent.
  K8S_API_URL:             required(url)
});

Wrapper	unset in dev/test	unset in production	env value present
withDefault(v, x)	uses x	uses x	uses env value
devDefault(v, x)	uses x	throws	uses env value
required(v)	throws	throws	uses env value

House NODE_ENV semantics

devDefault is enforced in production. Crucially, envalid natively treats an unset NODE_ENV as production — which would make devDefault throw during ordinary local development where nobody sets NODE_ENV. This library normalizes NODE_ENV first (without mutating the caller's environment) so:

• explicit production → production
• explicit test/testing, or GITHUB_ACTIONS=true → test
• anything else, including unset → development

The same logic is exported as helpers:

import { getNodeEnv, isProduction, isTest, isDevelopment } from '12factor-env';

getNodeEnv();        // 'development' | 'production' | 'test'
isProduction();      // boolean

Lenient coercion

Envalid's built-in bool rejects values like TRUE or yes. boolish accepts true/1/yes case-insensitively (and is safe to combine with a boolean default). The underlying coercion helpers are also exported:

import { env, boolish, withDefault, parseEnvBoolean, parseEnvNumber } from '12factor-env';

const config = env(process.env, {}, {
  FEATURE_ENABLED: withDefault(boolish, false)   // accepts TRUE/yes/1
});

parseEnvBoolean('YES'); // true
parseEnvNumber('42');   // 42

Validators

All validators from envalid are re-exported:

Validator	Description
str()	String value
bool()	Boolean (true, false, 1, 0)
num()	Number
port()	Port number (1-65535)
host()	Hostname or IP address
url()	Valid URL
email()	Valid email address
json()	JSON string (parsed)

Validator Options

All validators accept options:

import { str, num } from '12factor-env';

const config = env(process.env, {
  API_KEY: str({ desc: 'API key for external service' }),
  TIMEOUT: num({ default: 5000, desc: 'Request timeout in ms' })
});

API

env(inputEnv, secrets, vars)

Main function to validate environment variables.

• inputEnv - The environment object (usually process.env)
• secrets - Required environment variables
• vars - Optional environment variables

Re-exports from envalid

The following are re-exported from envalid for convenience:

• cleanEnv - Low-level env cleaning function
• makeValidator - Create custom validators
• EnvError - Error class for validation errors
• EnvMissingError - Error class for missing required vars
• testOnly - Helper for test-only defaults

Education and Tutorials

• 🚀 Quickstart: Getting Up and Running Get started with modular databases in minutes. Install prerequisites and deploy your first module.

• 📦 Modular PostgreSQL Development with Database Packages Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.

• ✏️ Authoring Database Changes Master the workflow for adding, organizing, and managing database changes with pgpm.

• 🧪 End-to-End PostgreSQL Testing with TypeScript Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.

• ⚡ Supabase Testing Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.

• 💧 Drizzle ORM Testing Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.

• 🔧 Troubleshooting Common issues and solutions for pgpm, PostgreSQL, and testing.

Related Constructive Tooling

📦 Package Management

• pgpm: 🖥️ PostgreSQL Package Manager for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.

🧪 Testing

• pgsql-test: 📊 Isolated testing environments with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
• pglite-test: 🪶 Drop-in pgsql-test replacement backed by PGlite — in-process Postgres, no server required, instance-per-suite isolation.
• pgsql-seed: 🌱 PostgreSQL seeding utilities for CSV, JSON, SQL data loading, and pgpm deployment.
• supabase-test: 🧪 Supabase-native test harness preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
• graphile-test: 🔐 Authentication mocking for Graphile-focused test helpers and emulating row-level security contexts.
• pg-query-context: 🔒 Session context injection to add session-local context (e.g., SET LOCAL) into queries—ideal for setting role, jwt.claims, and other session settings.

🧠 Parsing & AST

• pgsql-parser: 🔄 SQL conversion engine that interprets and converts PostgreSQL syntax.
• libpg-query-node: 🌉 Node.js bindings for libpg_query, converting SQL into parse trees.
• pg-proto-parser: 📦 Protobuf parser for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
• @pgsql/enums: 🏷️ TypeScript enums for PostgreSQL AST for safe and ergonomic parsing logic.
• @pgsql/types: 📝 Type definitions for PostgreSQL AST nodes in TypeScript.
• @pgsql/utils: 🛠️ AST utilities for constructing and transforming PostgreSQL syntax trees.

📚 Documentation & Skills

• constructive-skills: 📖 Platform documentation and AI agent skills — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.

Install skills for AI coding agents:

# All platform skills (security, blueprints, codegen, billing, etc.)
npx skills add constructive-io/constructive-skills

# Individual repo skills (pgpm, testing, CLI, search, etc.)
npx skills add https://github.com/constructive-io/constructive --skill pgpm
npx skills add https://github.com/constructive-io/constructive --skill constructive-testing

Credits

🛠 Built by the Constructive team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on GitHub.

Disclaimer

AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.

No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.