@cutticat/env

Library for loading, parsing, and generating environment variables.

Table of Contents

• 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:

• Project structure
• Scripts
• Style guide
• Contributing

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)