New: Built-in AES-256 Encryption

Stop scattering process.env across your codebase

One schema. Multiple sources. Full type safety. Define your configuration with Zod, load from anywhere, and get autocomplete, validation, and documentation for free.

See the ProblemGitHub
$npm install @zonfig/zonfig
The Problem

Configuration is a mess

Scattered process.env calls, no type safety, runtime crashes, and documentation that's always out of date.

Without zonfig

Scattered, untyped, error-prone

server.ts
// Scattered across 20+ files...
const port = process.env.PORT || '3000';
const dbUrl = process.env.DATABASE_URL;

// Oops, typo - fails silently at runtime
const secret = process.env.JWT_SECRT;

// Is this a string or number? Who knows!
const timeout = process.env.TIMEOUT;

// Forgot to check if it exists
db.connect(dbUrl); // 💥 Runtime crash

With zonfig

Centralized, typed, validated

config.ts
const config = await defineConfig({
  schema: z.object({
    port: z.number().default(3000),
    database: z.object({
      url: z.string().url(),
    }),
    jwt: z.object({
      secret: z.string().min(32),
    }),
    timeout: z.number().default(5000),
  }),
});

// ✅ Type-safe, validated at startup
config.get('database.url'); // string
How It Works

Multiple sources, one typed config

Load configuration from environment variables, JSON files, YAML, .env files, or even secret stores. Later sources override earlier ones.

config.jsonDefault values
→
.envLocal overrides
→
EnvironmentRuntime vars
→
SecretsAWS, Vault, etc.
→
Typed Config
Validated & frozen
config.ts
const config = await defineConfig({
  schema,
  sources: [
    { type: 'file', path: './config/default.json' },
    { type: 'file', path: './.env', format: 'dotenv' },
    { type: 'env', prefix: 'APP_' },
    { type: 'plugin', name: 'aws-secrets', options: { secretId: 'prod/api' } },
  ],
});

// Each source overrides the previous one
// Final config is validated against your Zod schema
// Result is frozen - no accidental mutations
Validation

Errors that actually help

No more cryptic runtime crashes. Get clear, actionable errors at startup that tell you exactly what's wrong and where.

Your config sources
# .env
DATABASE_URL=not-a-valid-url
SERVER_PORT=99999
API_TIMEOUT=fast
# JWT_SECRET is missing entirely
What you see at startup
Configuration validation failed
database.url
Invalid URL format
Source: .env → DATABASE_URL
server.port
Number must be ≤ 65535
Source: .env → SERVER_PORT
api.timeout
Expected number, received string
Source: .env → API_TIMEOUT
jwt.secret
Required field is missing
Source: none
CLI Tools

Migrate in minutes, not days

Our CLI analyzes your existing project, finds all your config sources, and generates a type-safe schema automatically.

  • zonfig analyze

    Scans .env files, config folders, and source code to find all your config values

  • zonfig docs

    Generate markdown docs, .env.example, or JSON Schema from your Zod schema

  • zonfig validate

    Validate config files against your schema in CI/CD pipelines

  • zonfig encrypt

    Encrypt secrets at rest with AES-256-GCM, safely commit configs to git

  • zonfig decrypt

    Decrypt encrypted config files for viewing or editing

$ npx zonfig analyze --dry-run
Analyzing project: ./my-express-app
 
Found:
  .env files: 3 (.env, .env.local, .env.example)
  Config files: 2 (config/default.json, config/production.json)
  process.env usage: 14 variables across 8 files
  Framework: Express
  Existing libs: dotenv
 
Generated schema with 14 config values:
  • server (host, port)
  • database (url, poolSize)
  • redis (url)
  • auth (jwtSecret, sessionTtl)
  • ...
Features

Everything you need

Built for real-world applications with sensible defaults and escape hatches when you need them.

Built-in Encryption

Encrypt secrets at rest with AES-256-GCM. Safely commit config to git with auto-decrypt on load.

Full TypeScript Inference

Your Zod schema becomes your types. Get autocomplete for config paths and inferred return types.

Validated at Startup

Bad config? Know immediately. No more runtime crashes from missing or malformed values.

Plugin System

Load secrets from AWS Secrets Manager, HashiCorp Vault, or build your own custom loaders.

Auto Documentation

Generate CONFIG.md, .env.example, and JSON Schema directly from your Zod schema.

Environment Profiles

Different sources for dev, staging, production. Switch with a single env var.

Framework Agnostic

Works with Next.js, Express, Fastify, NestJS, or any Node.js application.

Ready to fix your config?

Stop the config chaos. Get type safety, validation, and documentation in under 5 minutes.

Get StartedRead the Docs