celery-env

Celery validates process.env with a schema you can read, then generates a small validator you can ship without a runtime dependency. It is built for app configuration: defaults, production-only secrets, typed output, good error messages, and fast startup.

Install

Generated mode:

npm install -D celery-env

Runtime mode:

npm install celery-env

Other package managers:

pnpm add -D celery-env
yarn add -D celery-env
bun add -d celery-env

60-Second Setup

Infer a schema from existing env files and source references:

npx celery-env infer --schema env.schema.mjs

This writes a starter schema and refuses overwrite unless you pass --force. Review it before generating; inference cannot know every production-only rule.

Or create a schema manually:

// env.schema.mjs
import { bool, defineEnv, int, oneOf, str, url } from "celery-env";

export default defineEnv({
  NODE_ENV: oneOf(["development", "test", "production"], { default: "development" }),
  DATABASE_URL: url({ protocols: ["postgres"] }),
  PORT: int({ default: 3000, min: 1, max: 65535 }),
  DEBUG: bool({ default: false }),
  SESSION_SECRET: str({
    optional: true,
    requiredWhen: (env) => env.NODE_ENV === "production"
  })
});

Generate the validator:

npx celery-env generate \
  --schema env.schema.mjs \
  --out src/env.mjs \
  --types src/env.d.ts \
  --example .env.example \
  --minify

Use it at app startup:

// src/config.js
import { loadEnv } from "./env.mjs";

export const env = loadEnv(process.env);

Celery validates the env object you pass. Load .env with your platform, shell, or dotenv before calling loadEnv.

That is the main path: infer or write env.schema.mjs, generate src/env.mjs, and use the typed result everywhere else.

When To Use Celery

Use Celery when you want env validation to be:

• focused on app configuration instead of general object validation;
• generated once and cheap at startup;
• dependency-free in production;
• typed without hand-written config types;
• strict about missing production secrets without printing secret values.

If you already use Zod for forms, API payloads, or general data validation, keep using it there. Celery is for the narrower process.env problem where defaults, examples, generated files, and startup cost matter.

Quick Comparison

| Choose | When | | --- | --- | | Celery generated mode | You want a committed standalone validator, generated TypeScript declarations, generated .env.example, no production dependency, or lower cold-start cost. | | Celery runtime mode | You like Celery's schema API but cannot add generation yet. | | Zod | You need general object, form, API, or nested data validation. | | Envalid / Envsafe / env-var | You want mature runtime-only env validation with no generated files. |

Why Use It

• Generated validator: no schema walk during app startup.
• Zero runtime dependencies in generated mode.
• Small output: the measured small generated validator is 526 gzip bytes.
• Typed config through generated .d.ts files or InferEnv.
• Env-specific rules like devDefault, testDefault, and requiredWhen.
• Secret-safe errors that do not print rejected secret values.
• Runtime mode available when you do not want a build step.

Runtime Mode

Generated mode is recommended for apps, but direct parsing is available:

import { defineEnv, int, parseEnv, str } from "celery-env";

const schema = defineEnv({
  DATABASE_URL: str({ min: 1 }),
  PORT: int({ default: 3000 })
});

export const env = parseEnv(schema, process.env);

Benchmarks

Snapshot: Node v26.3.0, macOS arm64, Apple M3, generated on 2026-06-24. Higher ops/sec is better; lower milliseconds and bytes are better. Generated-mode numbers exclude compile/generation cost.

| Tool / mode | Real schemas ops/sec | Real process.env ops/sec | Invalid ops/sec | Cold first validation | Gzip snapshot | | --- | ---: | ---: | ---: | ---: | ---: | | Celery generated | 1,411,473 | 228,570 | 112,361 | 1.849 ms | 526 B | | Celery runtime | 776,241 | 185,124 | 96,846 | 2.598 ms | 2,779 B | | Zod | 516,820 | 141,126 | 39,760 | 33.999 ms | 20,894 B | | Valibot | 454,925 | 109,584 | 84,841 | 6.925 ms | 2,055 B | | Envalid | 125,202 | 85,436 | 16,731 | 9.598 ms | 7,318 B | | Envsafe | 940,564 | 184,818 | 19,359 | 5.694 ms | 3,292 B | | env-var | 51,287 | 44,727 | 31,922 | 7.679 ms | 2,969 B | | T3 Env Core | 316,627 | 168,740 | 10,264 | 32.366 ms | 19,531 B |

The benchmark corpus includes realistic API, web, worker, list-heavy, and JSON-heavy env schemas. Results are workload-specific; real process.env access narrows some gaps compared with frozen plain env objects.

Package metadata snapshot. Celery is this branch's npm pack --dry-run; competitors were checked with npm view on 2026-06-25.

| Package | Version checked | Runtime deps | Unpacked npm size | Files | | --- | ---: | ---: | ---: | ---: | | celery-env | 0.1.4 | 0 | 119.2 kB | 26 | | zod | 4.4.3 | 0 | 4.56 MB | 718 | | valibot | 1.4.1 | 0 | 1.84 MB | 9 | | envalid | 8.2.0 | 1 | 88.8 kB | 39 | | envsafe | 2.0.3 | 0 | 91.4 kB | 27 | | env-var | 7.5.0 | 0 | 42.9 kB | 30 |

Documentation

• Getting Started
• Schema API
• CLI
• TypeScript
• Examples
• Runtime Mode
• Comparison
• Troubleshooting
• Benchmarks
• Migration Guide
• Security

License

MIT