@novaedgedigitallabs/envkit

Framework-agnostic environment variable validation with Zod, secrets masking, and smart .env.example auto-generation.

A zero-dependency (other than zod) utility library for loading, validating, and masking environment variables in any JavaScript/TypeScript project. Ships with a CLI and runtime tools to keep your .env.example automatically up to date without overwriting existing values.

Install

npm install @novaedgedigitallabs/envkit zod

Quick Start

import { createEnv } from '@novaedgedigitallabs/envkit';
import { z } from 'zod';

export const env = createEnv({
  schema: {
    DATABASE_URL: z.string().url(),
    JWT_SECRET: z.string().min(32),
    PORT: z.coerce.number().default(3000),
    NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  },
  secrets: ['JWT_SECRET', 'DATABASE_URL'],
  generateExample: true, // Automatically append new keys to .env.example
});

// Fully typed!
env.PORT         // number
env.JWT_SECRET   // string (real value)

// Secrets are automatically masked when logged
console.log(env); 
// → { PORT: 3000, NODE_ENV: 'development', JWT_SECRET: '[MASKED]', DATABASE_URL: '[MASKED]' }

What's New in v0.1.5

| Feature | Description | |---|---| | Smart Appending | The CLI and runtime generator now strictly append new missing keys to .env.example. They will never overwrite or delete your existing values or comments. | | Graceful Fallbacks | If .env is missing when running the CLI, it skips gracefully instead of crashing your terminal scripts. | | Runtime Generation | generateExample: true now parses the Zod schema to find variable names and safely appends them to your .env.example in CI/CD or fresh setups. |

CLI Reference

generate

Syncs your .env keys to .env.example safely. It reads both files and appends only the new keys missing from the example file.

npx envkit generate
# → ✓ .env.example updated with 4 new keys

If you use custom environment files, you can specify them:

npx envkit generate --env .env.production --out .env.production.example

API Reference

createEnv(options)

The main function to load, validate, and mask your environment variables.

createEnv(options: EnvkitOptions): ValidatedEnv

| Option | Type | Default | Description | |---|---|---|---| | schema | ZodRawShape | required | Your Zod schema defining the expected environment variables. | | secrets | string[] | [] | Keys to mask in logs (e.g., ['JWT_SECRET']). | | envPath | string | '.env' | Path to the .env file to load. | | skipDotenv | boolean | false | Skip .env file loading entirely (useful for Docker/Vercel environments). | | generateExample| boolean | false | Automatically append missing keys to .env.example based on the Zod schema at runtime. | | onError | function | throws | Custom error handler for validation failures. |

Why envkit?

| Feature | dotenv | t3-env | envkit | |---|---|---|---| | .env loading | ✅ | ✅ | ✅ | | Zod validation | ❌ | ✅ | ✅ | | Framework agnostic | ✅ | ⚠️ | ✅ | | Secrets masking in logs | ❌ | ❌ | ✅ | | Auto .env.example generation | ❌ | ❌ | ✅ | | ESM + CJS support | ✅ | ESM only | ✅ |

Support

If envkit saved you time → novaedgedigitallabs.tech/pay

License

MIT © Amit Kumar Raikwar / NovaEdge Digital Labs