typed-env

typed-env

Runtime environment validation with full TypeScript inference. createEnvironment wraps a standard-schema object schema and returns helpers for loading, validating, and documenting your environment.

Setup

import * as z from "zod";
import { createEnvironment } from "@stephansama/typed-env";

export const env = createEnvironment(
  z.object({
    DATABASE_URL: z.string().url(),
    API_KEY: z.string().min(1),
  }),
  true, // auto-load .env quietly via dotenvx
);

Call env.validate() once at application startup to fail fast with a descriptive error on missing or invalid values.

Core Patterns

Validate at startup

// src/env.ts
import * as z from "zod";
import { createEnvironment } from "@stephansama/typed-env";

export const env = createEnvironment(
  z.object({
    PORT: z.coerce.number().default(3000),
    DATABASE_URL: z.string().url(),
  }),
  true,
);

// src/main.ts
import { env } from "./env";

const config = await env.validate();
// config is fully typed: { PORT: number; DATABASE_URL: string }

Generate a .env.example file

import { env } from "./env";

// writes placeholder values (***) for each key in the schema
await env.generateExample(".env.example");

Run this as a script or CI step to keep .env.example in sync with the schema. Requires zod, valibot, or arktype — the schema's vendor field determines how keys are extracted.

Custom dotenvx options

export const env = createEnvironment(schema, {
  path: ".env.production",
  override: true,
});

Pass a DotenvConfigOptions object as the second argument instead of true for custom .env file paths, override behaviour, or encryption options.

Load env without auto-loading

export const env = createEnvironment(schema);
// load manually when needed
env.loadEnv({ path: ".env.local" });
const config = await env.validate();

Common Mistakes

CRITICAL Schema library other than zod, valibot, or arktype

Wrong:

import { Type } from "@sinclair/typebox";
const env = createEnvironment(Type.Object({ KEY: Type.String() }));
await env.generateExample(".env.example"); // throws: "invalid schema provider"