@fimbul-works/zodenv

A tiny TypeScript utility for parsing and validating environment variables using Zod.

Features

• 🎯 Type-safe environment validation using Zod schemas
• 📝 Clear error messages with detailed validation feedback
• 🚀 Zero configuration - works out of the box with process.env
• 🔄 Configurable - throw errors, exit the process, or stay silent
• 🔍 TypeScript first - full type inference from your schemas

Installation

npm install @fimbul-works/zodenv zod picocolors

Quick Start

import { z } from "zod";
import { parseEnv } from "@fimbul-works/zodenv";

const env = parseEnv(
  z.object({
    NODE_ENV: z.enum(["development", "test", "production"]),
    PORT: z.string().default("3000"),
    DEBUG: z.boolean().optional(),
  }),
);

console.log(env.NODE_ENV); // fully typed!
console.log(env.PORT);     // string (default: "3000")

If validation fails, you’ll see a nicely formatted error:

Invalid Environment Configuration:
NODE_ENV: "staging"
  Invalid option: expected one of "development"|"test"|"production"

Options

parseEnv(schema, options?)

| Option | Type | Default | Description | | ------------- | ------------------------ | ------------- | ---------------------------------------------------- | | env | Record<string,unknown> | process.env | Source of variables | | exitOnError | boolean | true | Whether to call process.exit on validation failure | | exitCode | number | 1 | Exit code when exitOnError is true | | colors | boolean | true | Enable/disable colored error output |

Custom Error Handling

If you’d rather throw errors instead of exiting:

const env = parseEnv(schema, { exitOnError: false });

try {
  // ...
} catch (err) {
  console.error("Environment validation failed", err);
}

Using in Tests

You can pass a custom env object for isolation:

const env = parseEnv(
  schema,
  { env: { NODE_ENV: "test", PORT: "4000" }, exitOnError: false }
);

License

MIT License - See LICENSE file for details.

Built with ⚡ by FimbulWorks