@cutticat/env

Library for loading, parsing, and generating environment variables.

Overview
Installation
Quick Start
Entry Points
API
Features
Documentation
Requirements

Overview

The library provides functions for parsing environment variables through Zod, loading from .env files, and generating .env content. Supports nested objects — keys are automatically converted to SNAKE_CASE (e.g. db.host → DB_HOST).

Installation

Requires Zod 4 as a peer dependency (the same copy as in your application):

pnpm add @cutticat/env zod

Quick Start

import { z } from "zod"
import { parseEnv, toEnvTemplate, generateEnvContent } from "@cutticat/env"
import { loadObjectFromEnv } from "@cutticat/env/node"

// Config schema
const schema = z.object({
  db: z.object({
    host: z.string(),
    port: z.number(),
  }),
})

// Parse from a ready-made object (neutral)
const config = parseEnv(schema, process.env, {
  envPrefix: "APP_",
  removeEnvPrefix: true,
})

// Load from .env file (node)
const configFromFile = loadObjectFromEnv(schema, {
  envPrefix: "APP_",
  dotenvPath: ".env.local",
})

// Generate .env content
const template = toEnvTemplate({ db: { host: "localhost", port: 5432 } })
generateEnvContent(template, "APP_")
// "APP_DB_HOST=localhost\nAPP_DB_PORT=5432\n"

Entry Points

@cutticat/env — neutral bundle: types, parsing, generation, paths. No Node.js dependencies.
@cutticat/env/node — node bundle: same as above + loadObjectFromEnv (dotenv, process.env).

API

Functions

parseEnv(schema, env, options?) — parses env into a typed object using a Zod schema
loadObjectFromEnv(schema, options?) — loads .env, then parses (only @cutticat/env/node)
toEnvTemplate(value, prefix?) — converts an object into a flat template with SNAKE_CASE keys
generateEnvContent(env, prefix?) — generates an .env string from a template
toEnvKey(path) — converts path ["db", "host"] to key "DB_HOST"

Types

EnvTemplate — environment variable template
ObjectToEnv<T> — converts object type to env type (SNAKE_CASE keys)
ParseEnvOptions — parsing options (envPrefix, removeEnvPrefix, base)
LoadObjectFromEnvOptions — loading options (env, envPrefix, dotenvPath, etc.)

Features

Arrays in toEnvTemplate — one key with an array value: { hosts: ["a","b"] } → { HOSTS: ["a","b"] }. In generateEnvContent such an array is serialized as CSV on a single line.
null in generateEnvContent — keys with null are skipped (the .env format does not support null).
Auto-conversion in parseEnv — strings "true"/"false" → boolean, purely numeric strings → number. Empty string "" remains a string. A \ prefix disables auto-conversion (e.g. \true → string "true").
Primitive arrays in parseEnv — either a single CSV variable (IDS=1,2,3, empty → []), or indexed keys IDS_0, IDS_1, … (if env contains at least one key of the form IDS_<n> without a suffix after _<n>, the indexed format is used; CSV in IDS is then ignored). In CSV elements: \, and \\; in generateEnvContent for string arrays — the same escaping.
Object arrays in parseEnv — indexed keys HOSTS_0_NAME, HOSTS_1_PORT, …; empty array is set explicitly: HOSTS= (same as IDS= for primitives). In the template from toEnvTemplate the array sits entirely under HOSTS; in env for objects you still need indexed keys or the sentinel HOSTS=.
base in parseEnv — you can pass an object with defaults: it is merged with what was read from env; env values take priority when paths match.

Documentation

Detailed documentation:

Full API documentation is available in JSDoc comments. Use IDE autocomplete to browse it.

Requirements

Node.js >= 22.0.0
pnpm >= 10.17.0
TypeScript >= 5.9.0
zod ^4 (peer dependency)