Airlock (Wrkspace Env)

Airlock (@wrkspace-co/env) is a migration-first environment contract system for Node.js projects. You define env evolution with TypeScript migrations, then generate schema/docs/artifacts and validate targets (dev, preview, prod) from a single source of truth.

Docs: https://wrkspace-co.github.io/env/

Benefits

• Single source of truth. Your env contract lives in env/migrations/*.ts, not scattered .env* files.
• Safe iterative changes. Add, rename, deprecate, and remove keys with reviewable migration history.
• CI-ready validation. Run strict checks with stable JSON output for automation.

Features

• Chain-based migration API (ctx.key(...).define(...).value(...).remove())
• Migration integrity and rollback support
• Generated artifacts: .env*, env/schema.generated.json, env/ENV.md, env/env.audit.json
• Environment validation, audit, and deprecation checks
• Provider sync/diff/export workflows (Vercel/Heroku + export formats)
• TypeScript-first

Install

pnpm add -D @wrkspace-co/env

Run the local CLI with npx:

npx airlock --help

If you also use the Wrkspace wrapper, install both packages:

pnpm add -D @wrkspace-co/cli @wrkspace-co/env

Quick start

1. Create migration:

npx airlock migrate:make bootstrap-env

2. Edit migration:

import type { EnvMigrationContext } from "@wrkspace-co/env";

export async function up(ctx: EnvMigrationContext) {
  ctx.setPrefixPolicy("nextjs");

  ctx.url("DATABASE_URL")
    .scope("server")
    .requiredIn("prod");

  ctx.url("NEXT_PUBLIC_SITE_URL")
    .scope("client")
    .requiredIn(["dev", "preview", "prod"])
    .value("https://example.com");

  ctx.enum("LOG_LEVEL")
    .values(["debug", "info", "warn", "error"])
    .requiredIn(["dev", "preview", "prod"])
    .defaultValue("info");

  ctx.string("OLD_TOKEN")
    .requiredIn("prod")
    .deprecate("NEW_TOKEN", "2026-12-31", "Rotate to NEW_TOKEN");
}

export async function down(ctx: EnvMigrationContext) {
  ctx.key("DATABASE_URL").remove();
  ctx.key("NEXT_PUBLIC_SITE_URL").remove();
  ctx.key("LOG_LEVEL").remove();
  ctx.key("OLD_TOKEN").remove();
  ctx.setPrefixPolicy(undefined);
}

3. Apply migrations:

npx airlock migrate

4. Validate target:

npx airlock check --target prod --json

Common commands

npx airlock migrate:status --json
npx airlock generate --write-local --write-target-files
npx airlock audit --json
npx airlock deprecations --json

npx airlock <cmd> and wrkspace env <cmd> use the same command handlers and options.

If you want a bare airlock command in your shell, install the package globally instead of as a local dev dependency.

Learn more

Full documentation

Credits Airlock is a part of Wrkspace Co. © group.