🔒 typesafe-env

Zero-runtime-error environment variables for TypeScript

Stop debugging missing env vars in production. @harmand66/typesafe-env validates and types your environment variables at boot time — with zero dependencies and full TypeScript inference.

The Problem

// 💥 Crashes at runtime, not at startup
const port = parseInt(process.env.PORT); // NaN if missing
const db = process.env.DATABASE_URL;     // string | undefined — not safe!

The Solution

import { createEnv } from '@harmand66/typesafe-env';

const env = createEnv({
  PORT:         { type: 'number',  default: 3000 },
  DATABASE_URL: { type: 'string',  required: true },
  DEBUG:        { type: 'boolean', default: false },
});

// ✅ TypeScript knows PORT is a number — not string | undefined
env.PORT + 1        // 3001
env.DATABASE_URL    // string — guaranteed
env.DEBUG           // boolean — never a string

If any required variable is missing or has the wrong type, your app fails immediately at startup with a clear error — not 3 hours later in production.

Install

npm install @harmand66/typesafe-env
# or
pnpm add @harmand66/typesafe-env
# or
yarn add @harmand66/typesafe-env

Usage

Basic

import { createEnv } from '@harmand66/typesafe-env';

const env = createEnv({
  PORT:         { type: 'number',  default: 3000 },
  DATABASE_URL: { type: 'string',  required: true },
  DEBUG:        { type: 'boolean', default: false },
  APP_NAME:     { type: 'string',  default: 'myapp' },
});

With Express

// env.ts — validate once at the top of your app
import { createEnv } from '@harmand66/typesafe-env';

export const env = createEnv({
  PORT:         { type: 'number', default: 3000 },
  DATABASE_URL: { type: 'string', required: true },
  JWT_SECRET:   { type: 'string', required: true },
});

// server.ts
import { env } from './env';
app.listen(env.PORT); // ✅ number, not string

With Next.js

// lib/env.ts
import { createEnv } from '@harmand66/typesafe-env';

export const env = createEnv({
  NEXT_PUBLIC_API_URL: { type: 'string', required: true },
  DATABASE_URL:        { type: 'string', required: true },
  NEXTAUTH_SECRET:     { type: 'string', required: true },
});

What happens on error

❌ typesafe-env validation failed:
  • Missing required env var: DATABASE_URL
  • Missing required env var: JWT_SECRET
  • PORT must be a number, got "abc"

All errors are collected and shown at once — no more fixing one at a time.

API

createEnv(schema, source?)

| Parameter | Type | Default | |-----------|------|---------| | schema | Record<string, EnvFieldConfig> | required | | source | NodeJS.ProcessEnv | process.env |

EnvFieldConfig

| Option | Type | Default | Description | |--------|------|---------|-------------| | type | 'string' \| 'number' \| 'boolean' | required | The expected type | | required | boolean | true | Whether the var is required | | default | matching type | undefined | Fallback value if missing |

Why not just use Zod?

Zod is great, but it's a 57kb dependency with a verbose API for this specific use case. @harmand66/typesafe-env is zero dependencies, laser-focused on env vars, and fits in a single import.

Contributing

PRs and issues are welcome! Please open an issue before submitting large changes.

git clone https://github.com/giannielloemmanuele-lgtm/typesafe-env.git
cd typesafe-env
npm install
npm test

License

MIT © giannielloemmanuele-lgtm