@catgirls/env 🐱

Nyaa~! Environment variables, but make them type-safe! •⩊•

What's This? uwu

A smol but powerful TypeScript library that makes handling environment variables not completely awful. It gives you:

• Full type safety with runtime validation via Zod 🛡️
• Clear separation of client/server env vars to avoid leaking secrets 🤫
• Proper error messages when things go boom 💥
• Zero-config transforms for common types like numbers and bools
• Built-in transformers for quick type conversion 🔄

Installation

pnpm add @catgirls/env
# or yarn/npm if you must :3

Usage

swishes tail excitedly First, define your env config schema:

import { z } from "zod";
import { createServerEnv, transformers } from "@catgirls/env";

const env = createServerEnv({
  DATABASE_URL: {
    schema: z.string().url(),
  },
  PORT: {
    schema: z.number(),
    transform: transformers.number, // Using built-in transformer!
  },
  DEBUG_MODE: {
    schema: z.boolean().optional(),
    transform: transformers.optionalBoolean, // Optional transformer
  },
  FEATURE_FLAGS: {
    schema: z.object({
      enableNewStuff: z.boolean(),
    }),
    transform: transformers.json, // Type-safe JSON parsing
  },
});

// Typescript knows all the types! *purrs*
env.DATABASE_URL; // string
env.PORT; // number
env.DEBUG_MODE; // boolean | undefined

Built-in Transformers

Meow! We provide several built-in transformers to make your life easier:

// Numbers
transformers.number(val: string) => number
transformers.optionalNumber(val?: string) => number | undefined

// Booleans
transformers.boolean(val: string) => boolean
transformers.optionalBoolean(val?: string) => boolean | undefined

// JSON
transformers.json<T>(val: string) => T

For client-side envs (like Next.js), use createClientEnv instead:

const clientEnv = createClientEnv({
  NEXT_PUBLIC_API_URL: {
    schema: z.string().url(),
  },
});

Why This? (｡♥‿♥｡)

Because raw process.env makes me hiss. No types, no validation, everything's a string - it's like living in the JavaScript stone age! This little package fixes that with:

• Runtime validation so things fail fast instead of in prod
• Proper TypeScript types that actually match your runtime checks
• Clear error messages when someone forgets required vars
• Client/server separation to avoid accidentally exposing secrets
• Built-in transformers for common type conversions

API

createServerEnv<T>

Server-side env validator that yells if you try to use it client-side.

createClientEnv<T>

Client-safe env validator that automatically prefixes keys with NEXT_PUBLIC_.

transformers

Collection of helper functions for common type conversions.

EnvValidationError

Pretty error when validation fails, with details about what went wrong.

License

MIT - Go wild! ₍⸍⸌̣ʷ̣̫⸍̣⸌₎

made with <3 by catgirls from vatican city

purrs contentedly at well-typed environment variables