@021.is/spine-env

@021.is/spine-env

Type-safe, zod-validated environment loader. Fails LOUDLY at module-load time when a variable is missing or invalid.

Use

// lib/env.ts
import { defineEnv, common } from "@021.is/spine-env";
import { z } from "zod";

export const env = defineEnv({
  schema: {
    NODE_ENV: common.nodeEnv(),
    DATABASE_URL: common.pgUrl(),
    APP_URL: common.httpsUrl(),
    RESEND_API_KEY: common.secret(),
    PORT: common.number(),
    SIGN_UPS_OPEN: common.boolean(),
    MAX_UPLOAD: common.bytes(),
    AUTH_CLIENT_ID: z.string().startsWith("app_"),
  },
});

Now env.DATABASE_URL is typed string, env.PORT is typed number, etc. Reading a typo at the call site is a compile error.

Why

• Fail at startup, not at request 100. A missing RESEND_API_KEY should crash the boot, not silently 500 the first email.
• Single source of truth. Every app's env shape lives in one file.
• Free type narrowing. No more process.env.X!.trim() everywhere.
• .env.example writes itself. Run the schema against {} and the error message lists every required key.

common helpers

For anything else, just use raw zod (z.string(), z.enum([...])).