@victorfaruna/typed-env

Type-safe environment variable validation for Node.js, Bun, and modern runtimes. Zero dependencies.

Install

npm install @victorfaruna/typed-env

Usage

import { defineConfig } from "@victorfaruna/typed-env";

const env = defineConfig({
  DATABASE_URL: { type: "url", required: true },
  PORT: { type: "number", default: "3000" },
  DEBUG: { type: "boolean", default: "false" },
  API_KEY: { type: "string", required: true },
});

console.log(env.DATABASE_URL); // URL object
console.log(env.PORT); // 3000
console.log(env.DEBUG); // false
console.log(env.API_KEY); // "sk-abc123..."

Schema Options

Each key in the schema accepts:

| Option | Type | Description | | ---------- | --------- | ----------------------------------------------------------------- | | type | string | Required. One of "string", "number", "boolean", "url" | | required | boolean | Throws if the variable is missing | | default | string | Fallback value if the variable is not set |

Supported Types

| Type | Output | Example Value | | --------- | --------- | ------------------------------- | | string | string | "hello" | | number | number | "3000" → 3000 | | boolean | boolean | "true" → true | | url | URL | "https://example.com" → URL |

Error Handling

If any variables fail validation, all errors are collected and thrown at once:

Error: DATABASE_URL is required but missing
PORT Value must be a number

Runtime Support

This package reads from process.env and has zero dependencies — bring your own env loader.

| Runtime | Setup | | ---------- | ----------------------------------------------------- | | Node | Use dotenv or node --env-file=.env (v20.6+) | | Bun | Works out of the box — .env is loaded automatically | | Deno | Use --env-file flag or @std/dotenv | | Docker | Env vars injected via docker run -e or Compose |

Node.js example

import "dotenv/config";
import { defineConfig } from "@victorfaruna/typed-env";

const env = defineConfig({ ... });

Bun example

// No extra imports needed — Bun loads .env automatically
import { defineConfig } from "@victorfaruna/typed-env";

const env = defineConfig({ ... });

License

ISC