🌿 envwise

Environment Contracts for Node.js
Deterministic runtime validation powered by statically generated schema manifests.

envwise gives you code-first env declarations (builder + decorators), AST extraction at build time, and a strict runtime that validates from a committed manifest (envwise.schema.json) with zero runtime scanning.

✨ Why envwise?

• 🎯 Deterministic by design: runtime only reads schema + configured sources.
• 🧩 Hybrid workflow: author in code, ship generated artifacts.
• 🧪 Strict parsing: bool, int, float, json, list<T>, url, duration, bytes.
• 🔗 Serializable rule DSL: cross-field rules that survive extraction.
• 🔐 Security-first diagnostics: secrets masked by default.
• ✅ CI drift enforcement: ensure schema/docs/templates stay in sync.

🧠 How it works

Code (builder / decorators)
          |
          | envwise generate  (AST extraction)
          v
envwise.schema.json + outputs
(.env.example, markdown, html, k8s, json-schema)
          |
          | loadEnv({ schema, sources })
          v
Deterministic runtime validation

📌 Feature matrix

Capability	envwise
Builder API (TS + JS)	✅
Decorator API (TS)	✅
Runtime file/module scanning	❌
Startup / Lazy / Manual modes	✅
Strict typed parsing	✅
Serializable cross-field rules	✅
.env.example / docs / html / k8s / json-schema outputs	✅
CI schema drift checks	✅

🚀 Quickstart

1) Install

pnpm add @envwise/core
pnpm add -D @envwise/cli

2) Define environment contract (builder)

import { defineEnv, rule } from '@envwise/core';

export const schema = defineEnv({ projectName: 'my-app' })
  .string('NODE_ENV').oneOf(['development', 'production']).default('development')
  .int('PORT').default(3000).min(1).max(65535)
  .bool('USE_DB').default(false)
  .string('DB_URL').optional().secret().mode('lazy')
  .rule(rule('db-required', (r) => r.when('USE_DB').equals(true).thenRequire(['DB_URL'])))
  .build();

3) Generate manifest + outputs

envwise generate \
  --entry ./src/env.ts \
  --out ./envwise.schema.json \
  --formats dotenv,markdown,html,json-schema,k8s,table

4) Validate at runtime

import manifest from './envwise.schema.json';
import { loadEnv, processEnvSource, dotenvSource, argvSource } from '@envwise/core';

const env = loadEnv({
  schema: manifest,
  sources: [dotenvSource({ optional: true }), processEnvSource(), argvSource()],
});

console.log(env.get('PORT'));

🧱 Authoring styles

Builder API (TS/JS)

Use fluent, chainable declarations with type-safe runtime access.

Decorator API (TS)

import { EnvSchema, EnvVar, Rule } from '@envwise/decorators';
import { rule } from '@envwise/core';

@EnvSchema({ projectName: 'my-app' })
@Rule(rule('db-required', (r) => r.when('USE_DB').equals(true).thenRequire(['DB_URL'])))
class AppEnv {
  @EnvVar({ key: 'PORT', type: 'int', default: 3000 })
  port!: number;

  @EnvVar({ key: 'USE_DB', type: 'bool', default: false })
  useDb!: boolean;

  @EnvVar({ key: 'DB_URL', type: 'string', required: false, mode: 'lazy', secret: true })
  dbUrl!: string;
}

🛠️ CLI

envwise generate --entry ./src/schema.ts --out ./envwise.schema.json
envwise check --entry ./src/schema.ts --out ./envwise.schema.json

Config file support: envwise.config.ts | envwise.config.js | envwise.config.json.

📦 Generated outputs

• 📄 Contract manifest (envwise.schema.json)
• 🔧 .env.example
• 📝 Markdown docs
• 🌐 HTML docs
• 📚 JSON schema for manifest
• ☸️ Kubernetes templates (ConfigMap + Secret placeholders)

🔐 Security model

• Diagnostics levels: safe | verbose | off
• Secret values are masked by default
• Secret values require explicit nuclear opt-in (allowSecretValueLogging: true)

🧪 CI enforcement

envwise check fails if generated files drift from source declarations.

Recommended CI steps:

pnpm install
pnpm lint
pnpm test
pnpm build
pnpm envwise:generate
pnpm envwise:check

⚖️ Comparison

envwise vs Zod

Zod is excellent for runtime object validation; envwise focuses on env contracts + static extraction + deterministic startup/runtime env validation + generated infra/docs artifacts.

envwise vs envalid

envalid focuses on runtime env parsing; envwise adds extraction, manifest versioning, richer outputs, decorator support, and CI schema drift checks.

🔁 Migration & guides

• Quickstart
• Builder Guide
• Decorators Guide
• CI Enforcement Guide
• Migration from Zod/envalid
• API Reference
• AI Agent Usage Guide

🗂️ Monorepo packages

• @envwise/schema: shared manifest types + JSON schema
• @envwise/core: runtime, parser, rule engine, outputs, sources
• @envwise/decorators: decorator authoring API
• @envwise/cli: AST extraction + generators + drift checks

💻 Local development

pnpm install
pnpm lint
pnpm test
pnpm build
pnpm envwise:generate
pnpm envwise:check

🚢 Publishing

Local publish (no provenance, required outside GitHub Actions OIDC):

npm login
pnpm npm:whoami
pnpm changeset:publish:local

CI publish (with provenance):

• Uses .github/workflows/release.yml
• Sets NPM_CONFIG_PROVENANCE=true
• Uses npm trusted publishing (OIDC) or NPM_TOKEN

If publish fails with 404 for @envwise/*, ensure your npm account/org owns the @envwise scope and has publish permission.

📄 License

MIT.