@lacspace/env

Typed, validated environment variables — fail fast at boot, not in production.

Declare a schema, validate process.env once at startup, and get a typed, frozen object. Missing or malformed variables throw one clear error listing everything wrong — so a bad deploy fails immediately instead of 500-ing at 2am. A zero-dependency t3-env / envalid alternative.

• 🔒 Types inferred from the schema — env.PORT is a number, guaranteed present
• 💥 Fail-fast with an aggregated, readable error
• 🧰 Validators: str · num · int · port · bool · url · email · oneOf · json
• 🎚️ default, optional, min/max per field
• ⚡ Zero dependencies · 🌍 isomorphic · 📦 ESM + CJS · fully typed

Install

npm install @lacspace/env      # or pnpm add / yarn add / bun add

Define once, use everywhere

// env.ts
import { createEnv, str, port, url, bool, oneOf } from "@lacspace/env";

export const env = createEnv({
  NODE_ENV: oneOf(["development", "production", "test"], { default: "development" }),
  PORT: port({ default: 3000 }),
  DATABASE_URL: url(),
  SMTP_HOST: str(),
  SMTP_PORT: port({ default: 587 }),
  DEBUG: bool({ default: false }),
  ADMIN_EMAILS: str({ optional: true }),
});

import { env } from "./env";

env.PORT;      // number — 3000 unless set
env.DEBUG;     // boolean
env.NODE_ENV;  // "development" | "production" | "test"

If DATABASE_URL is missing and SMTP_PORT is "abc", startup throws:

EnvError: Invalid environment variables:
  • "DATABASE_URL" is required but was not set
  • "SMTP_PORT" must be a number, got "abc"

Validators

| Validator | Parses to | Options | | --- | --- | --- | | str(opts?) | string | default, optional, allowEmpty | | num / int | number | default, optional, min, max | | port(opts?) | number (1–65535) | default, optional | | bool(opts?) | boolean | accepts true/1/yes/on, false/0/no/off | | url / email | validated string | default, optional | | oneOf(values, opts?) | union of literals | default, optional | | json<T>(opts?) | parsed JSON | default, optional |

Not just process.env

createEnv(schema, import.meta.env); // Vite
createEnv(schema, Deno.env.toObject());

The Lacspace WebKit

| Package | For | | --- | --- | | @lacspace/seo | Metadata & JSON-LD | | @lacspace/env | Typed env variables (this package) | | @lacspace/rate-limit | Rate limiting | | @lacspace/otp | TOTP/HOTP 2FA | | @lacspace/next | Next.js SDK integration |

Licensing

This package is free under the Lacspace Free Licence — MIT-equivalent freedoms. Use it in personal and commercial projects at no cost; just keep the notice.

Not every Lacspace package is free. We also offer Commercial (paid), Client-specific, and Private (proprietary) packages under separate terms. See the full Lacspace Licence Centre.

Part of the Lacspace ecosystem — 35 zero-dependency, isomorphic TypeScript packages.

All packages ↗ · npm org ↗ · Licence Centre ↗ · GitHub ↗