DEV Community: Odejobi Abiola Samuel

I Built a Sync Engine for a 0-Dep Client-Side Database, Here's What I Learned

Odejobi Abiola Samuel — Sun, 05 Jul 2026 09:42:24 +0000

I spent three months adding offline sync to ctrodb — a client-side database I'd been working on for about a year before that. The database itself was straightforward: schema validation, queries, a reactive signal system. Couple thousand lines. Nothing wild.

Sync was different.

It took more code than the rest of the database combined. I rewrote the conflict resolver three times. I shipped a transport system I later threw out. I learned what "eventually consistent" actually means when you're the one who has to implement it.

This is what I learned.

npm: npm install ctrodb
GitHub: github.com/ctrotech-tutor/ctrodb
Docs: ctrodb.vercel.app/docs

The Hard Part Is Not the Data Transfer

When I started, I thought sync would be: get data from server, merge with local data, done.

The first version was exactly that. A push endpoint, a pull endpoint, a simple merge. It worked for the demo. Then I tried editing the same record on two devices at once.

The second device's push would silently overwrite the first device's changes. Data gone. No notification. No way to recover.

That's when I realized sync isn't about moving bytes. It's about knowing what changed, in what order, and what to do when two changes conflict.

Change Tracking: The Foundation

The sync engine is a plugin that hooks into the database's write pipeline. When you create, update, or delete a record, the plugin writes a change record to an internal change log.

interface SyncChangeRecord {
  id: string
  collection: string
  recordId: string
  type: "create" | "update" | "delete"
  data: Record<string, unknown> | null
  prevData: Record<string, unknown> | null
  timestamp: string
  status: "pending" | "syncing" | "committed" | "failed"
  retries: number
  errorMessage: string | null
  createdAt: string
  updatedAt: string
}

The change log write happens inside the same transaction as the main data write. If one fails, both fail. No orphaned changes.

The plugin hooks are onAfterCreate, onAfterUpdate, and onAfterDelete. Each one appends to the change log.

const plugin: CtroDBPlugin = {
  name: "sync",
  async onDatabaseInit(db) {
    tracker = new ChangeTracker(db._getAdapter())
    engine = new SyncEngine(db, config)
    await engine.init()
  },
  async onAfterCreate(collection, record) {
    await tracker.append("create", collection, record.id, record)
  },
  async onAfterUpdate(collection, id, record, oldRecord) {
    await tracker.append("update", collection, id, record, oldRecord ?? null)
  },
  async onAfterDelete(collection, id, oldRecord) {
    await tracker.append("delete", collection, id, null, oldRecord ?? null)
  },
}

The plugin also registers store indexes — the change log is an IndexedDB object store with indexes on status and timestamp.

Pull: Cursor-Based Pagination

Pull requests ask the server for changes since the last sync. The actual implementation uses cursor-based pagination, not sequence numbers.

interface SyncTransport {
  pull(options?: {
    cursor?: string | null
    collections?: string[]
    batchSize?: number
    signal?: AbortSignal
  }): Promise<{
    changes: SyncChangeRecord[]
    cursor: string | null
    hasMore: boolean
  }>
}

The cursor is an opaque token — usually a timestamp or a record ID. The client sends cursor: null for the first pull (fetch everything) and the last cursor from the previous sync for subsequent pulls.

The server returns changes plus the next cursor. If hasMore is true, the client keeps pulling in a loop (up to 1000 pages, safety valve).

Push: Batch and Retry

Push collects all pending and failed changes, sends them in batches, and processes the server's response.

async function pushChanges() {
  const pending = await tracker.getPending() // pending + failed, sorted by timestamp
  if (pending.length === 0) return

  const batch = pending.slice(0, pushBatchSize)
  await tracker.markSyncing(batchIds)

  try {
    const result = await transport.push(batch, { signal })
    for (const accepted of result.accepted) tracker.markCommitted(accepted.id, ...)
    for (const conflict of result.conflicts) await resolveConflict(conflict)
    for (const err of result.errors) await tracker.markFailed(err.id, err.error)
  } catch {
    // Mark back as pending on network failure
  }
}

The server returns three lists: accepted (applied), conflicts (need resolution), errors (rejected). Each is handled differently.

Conflict Resolution: The Part I Got Wrong

My first conflict resolver used last-write-wins (strategy: "lww"). Whoever wrote last, their data survives. Simple. Wrong.

Consider this: Alice edits a note's title on her phone while offline. Bob edits the same note's body on his laptop, also offline. Both sync when they reconnect. With last-write-wins, whichever syncs second loses. Bob's body edit gets wiped because Alice's phone happened to flush its sync queue a few seconds later.

That's not Bob's fault. He changed different fields. The data should merge.

The built-in strategies are:

type ConflictStrategy = "lww" | "client-wins" | "server-wins" | "custom"

"lww" — last-write-wins by timestamp. Default.
"client-wins" — local version always wins.
"server-wins" — remote version always wins.
"custom" — you provide a conflictResolver function.

For field-level merge, use the custom resolver:

const db = new Database({
  name: "my-app",
  schema: { ... },
  plugins: [syncPlugin({
    transport,
    strategy: "custom",
    conflictResolver: (conflict) => {
      const merged = { ...conflict.local, ...conflict.remote }
      return { resolution: "merged", merged }
    },
  })],
})

The conflict object gives you both versions and a list of conflicting fields:

interface SyncConflict {
  changeId: string
  recordId: string
  collection: string
  local: Record<string, unknown> | null
  remote: Record<string, unknown> | null
  localTimestamp: string
  remoteTimestamp: string
  fieldConflicts: string[]
}

The resolver returns a ConflictResolution:

type ConflictResolution = {
  resolution: "local" | "remote" | "merged"
  merged?: Record<string, unknown> | null
}

If you return "local", the server version is discarded. "remote" overwrites local. "merged" applies your merged object.

Transport: HTTP with a Single URL

The HTTP transport takes a single base URL, not separate push/pull URLs. It appends /push and /pull paths automatically.

const transport = new HttpTransport({
  url: "https://api.myapp.com/sync",
  headers: { Authorization: "Bearer ..." },
  timeoutMs: 10000,
})

It implements connect(), disconnect(), isConnected(), push(), and pull(). Push sends a POST to /push, pull sends a POST (or GET) to /pull.

I added rate limiting detection — if the server returns 429, the transport parses the Retry-After header and surfaces it. The sync engine uses this to back off.

WebSocket transport is available for real-time push scenarios, but most apps don't need it. HTTP is simpler, stateless, and easier to debug.

What I'd Do Differently

Test with real offline scenarios earlier. My first tests used simulated networks with controlled latency. Real offline is messier — partial connectivity, brief flips between online and offline, race conditions on reconnect. I added a faulty transport helper that drops every nth request and randomizes delay. That caught bugs throttling never triggered.

Build devtools from day one. Debugging sync is hard because the state is distributed. The devtools — inspectSyncQueue(db), getSyncStats(db), retryFailedSync(db) — saved me more times than I can count. I added them halfway through. Should have been first.

import { inspectSyncQueue, retryFailedSync } from "ctrodb"

const queue = await inspectSyncQueue(db)
console.log(queue.stats)
// { total: 42, pending: 3, syncing: 0, committed: 38, failed: 1 }

await retryFailedSync(db) // marks failed items back to pending and triggers sync

Don't try to handle every edge case. I spent two weeks on a sync ordering dependency system — ensuring referenced records sync before their dependents. The database already handled this at the app level. I removed it and sync worked fine.

Trade-offs I'm Still Thinking About

The current design trades real-time collaboration for simplicity. Two users on the same document won't see each other's changes until they sync. True real-time would need a CRDT or OT layer.

But for most apps — todos, notes, offline-first dashboards — the sync-every-few-seconds model works. The complexity of CRDTs isn't worth it until you're building Google Docs.

npm: npm install ctrodb
Sync code: github.com/ctrotech-tutor/ctrodb (in src/sync/)
Sync docs: ctrodb.vercel.app/docs/sync/overview

ctrodb 1.4: Offline Sync for the Browser, Zero Dependencies

Odejobi Abiola Samuel — Thu, 02 Jul 2026 22:01:55 +0000

ctrodb is a client-side database for TypeScript. Schema validation, MongoDB-like queries, full-text search, relations — all in about 8KB gzipped with zero runtime dependencies.

v1.4 is the biggest release yet. It adds offline sync.

npm install ctrodb

GitHub: github.com/ctrotech-tutor/ctrodb
Docs: ctrodb.vercel.app/docs

What's in v1.4

Sync engine with change tracking. Every create, update, and delete is recorded in a local change log and pushed to your server when connectivity returns.

import { Database, syncPlugin, HttpTransport } from "ctrodb"

const transport = new HttpTransport({
  url: "https://api.myapp.com/sync",
})

const db = new Database({
  name: "my-app",
  schema: { ... },
  plugins: [syncPlugin({ transport })],
})

await db.connect()

Three conflict strategies out of the box — last-write-wins, client-wins, server-wins — plus a custom resolver hook. Field-level merge isn't built in as a strategy but you can implement it in the custom resolver.

const db = new Database({
  name: "my-app",
  schema: { ... },
  plugins: [syncPlugin({
    transport,
    strategy: "custom",
    conflictResolver: (conflict) => {
      return { resolution: "merged", merged: { ...conflict.local, ...conflict.remote } }
    },
  })],
})

HTTP transport works with any backend. WebSocket transport for real-time push. Trigger sync manually, on interval, or let the auto-sync handle it.

await db.sync()

React hooks for sync status and queue inspection:

import { useSyncStatus, useSyncQueue } from "ctrodb/react"

function SyncIndicator() {
  const { isSyncing, pendingChanges } = useSyncStatus()
  if (isSyncing) return <span>Syncing...</span>
  if (pendingChanges > 0) return <span>{pendingChanges} pending</span>
  return <span>All changes saved</span>
}

Devtools component for debugging:

import { SyncDevPanel } from "ctrodb/react"

// Shows queue, event log, manual sync trigger
if (import.meta.env.DEV) <SyncDevPanel />

Devtools utilities — inspect, retry, compact, stats — all take the database instance:

import { inspectSyncQueue, retryFailedSync, getSyncStats, compactSyncQueue } from "ctrodb"

const queue = await inspectSyncQueue(db)
const stats = await getSyncStats(db)
await retryFailedSync(db)

What else

New useDoc hook for single-record subscriptions
useSync hook for manual sync control with event callbacks
DatabaseProvider for React context
Custom adapter support
CDN usage (IIFE build in npm package)

Environment Variables Don't Have to Suck

Odejobi Abiola Samuel — Thu, 02 Jul 2026 13:11:14 +0000

I've lost count of how many times I've seen this in production:

const port = parseInt(process.env.PORT || "3000", 10)
const dbUrl = process.env.DATABASE_URL
if (!dbUrl) throw new Error("DATABASE_URL is required")

It's in every codebase. The same six lines, copy-pasted across a dozen files. Half the time someone forgets parseInt exists and the port becomes the string "3000". The other half the error message is misleading because someone renamed the variable in the schema but forgot to update the check.

I got tired of fixing these bugs and built something small.

The core idea

One function. A typed schema. Zero dependencies.

import { defineEnv, string, number } from "@ctroenv/core"

const env = defineEnv({
  DATABASE_URL: string().url(),
  PORT: number().port().default(3000),
})

// env.DATABASE_URL is `string`
// env.PORT is `number` — coerced from the env var string

That's it. You describe what you expect, and you get a typed, frozen object back. If the actual environment doesn't match, you get a clear error instead of a cryptic undefined downstream.

What it actually does at runtime

When you call defineEnv(), it:

Reads each variable from process.env (or any source you give it)
Runs it through the validator
Applies defaults for missing optional vars
Freezes the result object

No hidden file reads. No global state. No runtime dependencies.

Where this saves real time

1. No more startup crashes with bad types

const env = defineEnv({
  REDIS_PORT: number().port(),
})
// If REDIS_PORT is "abc" or "99999", this throws immediately
// with: "REDIS_PORT: Expected a port number (1-65535), received 99999"

Instead of your app starting, connecting to Redis, and then failing with some obscure connection error 30 seconds later, you get the failure at import time.

2. Boolean coercion that actually makes sense

const env = defineEnv({
  DEBUG: boolean(),
})
// Coerces common boolean strings: "true", "1", "yes", "on" → true

No more comparing strings to "true" manually.

3. Secrets that don't leak in logs

const env = defineEnv({
  JWT_SECRET: string().min(32).secret(),
})

console.log(env.JWT_SECRET) // "********"
console.log(env.meta.get("JWT_SECRET")) // actual value

The Proxy wrapper masks secret values on direct access. You have to explicitly use .meta.get() to read them. This means a stray console.log(env) in a request handler won't dump your secrets.

The CLI is worth mentioning

I use this more than the library itself some days:

ctroenv validate          # Check env against your schema
ctroenv check --strict    # CI gate — exits non-zero on mismatch
ctroenv generate          # Create .env.example from schema

The check command is what runs in CI. It diffs the .env file against the schema and exits 1 if anything's missing or wrong. The --warn-unknown flag also catches typos in your .env file (like DATABASE_URLL with a suggestion for DATABASE_URL).

How it handles real-world mess

Next.js (server/client split)

import { defineEnv } from "@ctroenv/nextjs"

export const env = defineEnv({
  server: {
    DATABASE_URL: string().url(),
    JWT_SECRET: string().secret(),
  },
  client: {
    NEXT_PUBLIC_API_URL: string().url(),
  },
})

Server-only variables throw if accessed on the client. The types are merged so you get one typed object.

Vite plugin

import { ctroenvPlugin } from "@ctroenv/vite"

export default defineConfig({
  plugins: [ctroenvPlugin({ schema: "./src/env.ts" })],
})

Validates env at build time. If you forgot to set VITE_API_URL, the build fails before you deploy.

Watching for changes

import { watchEnv } from "@ctroenv/core"

const env = watchEnv(schema, {
  pollInterval: 200,
  onChange(key, oldVal, newVal) {
    console.log(`${key} changed: ${oldVal} → ${newVal}`)
  },
})

Useful for local dev servers that need to react to .env file changes without a restart.

What I left out

I deliberately kept validators minimal. No hex() or base64(). The philosophy is: ship the 80% case, and let people write custom validators for the rest.

import { createValidator, applyChain, parseOk, singleError, errType, errInvalid } from "@ctroenv/core"

function hexColor() {
  const base = createValidator<string>(
    (input, ctx) => {
      if (typeof input !== "string")
        return singleError(errType(ctx.key, typeof input, "hex color"))
      if (!/^#[0-9a-fA-F]{3,6}$/.test(input))
        return singleError(errInvalid(ctx.key, input, "not a valid hex color"))
      return parseOk(input)
    },
    { typeLabel: "hexcolor" },
  )
  return applyChain(base)
}

Sixteen lines. No base class. No decorator magic.

The numbers

Core package: zero dependencies, ~4 KB gzipped
480 tests, 98% line coverage
Works in Node 18+, Bun, Deno, Cloudflare Workers, Vite, Next.js

You can find it at github.com/ctrotech-tutor/ctroenv.

I wrote this library because I was tired of debugging "cannot read properties of undefined" that traced back to a missing env var. If you've been there too, give it a try — or don't. Either way, stop writing manual process.env checks.

Shipping Reusable Env Schemas

Odejobi Abiola Samuel — Thu, 02 Jul 2026 10:37:31 +0000

Your library needs DATABASE_URL. Another needs JWT_SECRET. Instead of documenting requirements in a README that goes stale, ship them as CtroEnv schemas.

Publishing a Schema from Your Library

defineSchema() is an identity function at runtime — it returns the same object you pass in. At the type level, it preserves exact validator types for composition.

// @myapp/database/src/env.ts
import { defineSchema, string, number, pick } from "@ctroenv/core"

export const databaseSchema = defineSchema({
  DATABASE_URL: string().url().describe("PostgreSQL connection string"),
  DB_POOL_SIZE: number().int().min(1).max(100).default(10),
  DB_SSL: pick(["require", "prefer", "disable"] as const).default("prefer"),
})

Consumers extend it:

// consumer/src/env.ts
import { defineEnv, extendSchema } from "@ctroenv/core"
import { databaseSchema } from "@myapp/database"

const env = defineEnv(
  extendSchema(databaseSchema, {
    PORT: number().port().default(3000),
    JWT_SECRET: string().min(32).secret(),
  }),
)

The consumer's env has all four database vars plus their own. Types merge automatically.

Conflict Handling

If the base and extension define the same key, extension wins:

const base = defineSchema({ PORT: number().default(3000) })
const extended = extendSchema(base, { PORT: number().default(4000) })
// PORT resolves to 4000

In development mode, a warning is logged when conflicts occur.

Building Custom Validators

For domain-specific formats not covered by built-in validators, use createValidator():

import {
  createValidator, applyChain,
  parseOk, singleError,
  errType, errInvalid,
} from "@ctroenv/core"

function hexColor() {
  const base = createValidator<string>(
    (input, ctx) => {
      if (typeof input !== "string") {
        return singleError(errType(ctx.key, typeof input, "hex color"))
      }
      if (!/^#[0-9a-fA-F]{3,6}$/.test(input)) {
        return singleError(errInvalid(ctx.key, input, "not a valid hex color"))
      }
      return parseOk(input)
    },
    { typeLabel: "hexcolor" },
  )
  return applyChain(base) // adds .optional(), .default(), .secret(), etc.
}

const env = defineEnv({
  THEME_PRIMARY: hexColor().default("#3b82f6"),
  THEME_SECONDARY: hexColor().optional(),
})

Error Helpers

Function	Error Code	When
`errMissing(key)`	`missing_required`	Variable not found
`errType(key, received, expected)`	`type_mismatch`	Wrong JavaScript type
`errInvalid(key, value, msg)`	`invalid_value`	Failed validation
`errWrap(key, value, msg, code)`	Custom	Generic wrapper

Adding Refinement Methods

Custom validators can expose type-specific methods like .v4() on ip():

function ip() {
  const base = createValidator<string>(/* ... */)
  const chainable = applyChain(base) as typeof applyChain<string>
    & { v4(): typeof chainable }

  chainable.v4 = () => {
    const original = chainable
    const wrapped = createValidator<string>(
      (input, ctx) => {
        const r = original.parse(input, ctx)
        if (!r.success) return r
        if (r.value.includes(":"))
          return singleError(errInvalid(ctx.key, r.value, "not IPv4"))
        return r
      },
      original.metadata,
    )
    return applyChain(wrapped) as typeof chainable
  }
  return chainable
}

Schema Composition in Monorepos

The recommended monorepo layout:

packages/
  shared/           ← defineSchema with shared validators
  api/              ← extendSchema + defineEnv
  worker/           ← extendSchema + defineEnv (different subset)

// packages/shared/src/index.ts
export const base = defineSchema({
  NODE_ENV: pick(["dev", "staging", "prod"] as const).default("dev"),
  LOG_LEVEL: pick(["debug", "info", "warn", "error"] as const).default("info"),
})

// packages/api/src/env.ts
const schema = extendSchema(base, {
  PORT: number().port().default(3000),
  DATABASE_URL: string().url(),
})

// packages/worker/src/env.ts
const schema = extendSchema(base, {
  QUEUE_CONCURRENCY: number().int().min(1).default(5),
})

Each package imports only what it needs. Adding a shared var in the base schema propagates to all packages on rebuild.

Auto-Generated Docs

Run ctroenv docs to generate ENVIRONMENT.md from your schema:

npx ctroenv docs --output ENVIRONMENT.md

Every variable with its type, default, and .describe() text — always in sync with the schema.

Testing Schemas

Export your schema for testing:

// schema.test.ts
import { defineEnv, objectSource } from "@ctroenv/core"
import { databaseSchema } from "./schema"

it("validates with defaults", () => {
  const env = defineEnv(databaseSchema, {
    source: objectSource({
      DATABASE_URL: "postgresql://localhost:5432/test",
    }),
  })
  expect(env.DB_POOL_SIZE).toBe(10) // default
})

Summary

Pattern	What	Why
`defineSchema()`	Publishable schema block	Reusable across packages
`extendSchema()`	Compose schemas	Don't repeat definitions
`createValidator()`	Custom validator	Domain-specific formats
`ctroenv docs`	Auto-generated docs	Always in sync
`objectSource()`	Test with mock env	No global pollution

npm install @ctroenv/core

Links: GitHub · Docs · npm

Previous: Testing and Debugging Your Env Config

Testing and Debugging Your Env Config

Odejobi Abiola Samuel — Thu, 02 Jul 2026 10:30:11 +0000

Environment variables are global state. Testing them usually means mutating process.env and hoping you clean up after. CtroEnv gives you better tools.

Testing with objectSource

objectSource() wraps a plain object as an environment source — no globals involved:

import { describe, expect, it } from "vitest"
import { defineEnv, objectSource, string, number } from "@ctroenv/core"

function makeEnv(overrides: Record<string, string> = {}) {
  return defineEnv(
    {
      DATABASE_URL: string().url(),
      PORT: number().port().default(3000),
      JWT_SECRET: string().min(32).secret(),
    },
    { source: objectSource(overrides) },
  )
}

it("parses valid env vars", () => {
  const env = makeEnv({
    DATABASE_URL: "postgresql://localhost:5432/db",
    JWT_SECRET: "a".repeat(32),
  })
  expect(env.DATABASE_URL).toBe("postgresql://localhost:5432/db")
  expect(env.PORT).toBe(3000) // default
})

it("throws on missing required vars", () => {
  expect(() => makeEnv({ PORT: "4000" })).toThrow()
})

No beforeEach/afterEach cleanup. No global mutation. Each test gets a fresh environment.

Testing Validation Errors

Catch and inspect specific errors:

import { CtroEnvError } from "@ctroenv/core"

it("reports invalid URL", () => {
  try {
    makeEnv({
      DATABASE_URL: "not-a-url",
      JWT_SECRET: "a".repeat(32),
    })
  } catch (e) {
    expect(e).toBeInstanceOf(CtroEnvError)
    expect((e as CtroEnvError).errors[0].code).toBe("invalid_value")
    expect((e as CtroEnvError).errors[0].key).toBe("DATABASE_URL")
  }
})

it("collects all errors at once", () => {
  try {
    makeEnv({}) // both required vars missing
  } catch (e) {
    expect((e as CtroEnvError).errors).toHaveLength(2)
  }
})

No fix-one-find-another cycle. Every error surfaces in one throw.

Testing Secret Masking

it("masks secret values", () => {
  const env = makeEnv({
    DATABASE_URL: "postgresql://localhost:5432/db",
    JWT_SECRET: "x".repeat(32),
  })
  expect(env.JWT_SECRET).toBe("********")
  expect(env.meta.get("JWT_SECRET")).toBe("x".repeat(32))
})

it("supports custom mask", () => {
  const env = defineEnv(
    { KEY: string().secret() },
    { source: objectSource({ KEY: "value" }), maskWith: "***" },
  )
  expect(env.KEY).toBe("***")
})

Debugging with Error Codes

CtroEnv has four error codes. Each tells you exactly what went wrong:

Code	Meaning	Example
`missing_required`	Variable not in source	`DATABASE_URL` not set
`type_mismatch`	Wrong JavaScript type	String for number validator
`invalid_value`	Failed refinement	Invalid URL, port out of range
`validation_failed`	Custom `.validate()` rejected	API key format wrong

formatErrors

import { formatErrors } from "@ctroenv/core"

try {
  defineEnv(schema)
} catch (e) {
  if (e instanceof CtroEnvError) {
    process.stderr.write(formatErrors(e.errors))
    // Groups errors by type with colors
  }
}

CI/CD Integration

CtroEnv's CLI runs in CI without importing your schema — it parses config files directly.

Fast Key Check

npx ctroenv check --source .env.example

Compares keys only. Runs in under a second. Perfect for every PR.

Strict Validation

npx ctroenv check --source .env.staging --strict

Validates values against their validators — catches invalid URLs, out-of-range ports.

Unknown Key Warnings

npx ctroenv check --source .env --warn-unknown

Detects keys in your .env that aren't in the schema. Uses Levenshtein distance for suggestions:

⚠ Unknown key: "DATABSE_URL"
  → Did you mean "DATABASE_URL"?

JSON Output

npx ctroenv check --source .env --json

{
  "clean": false,
  "summary": { "missing": 1, "unused": 0, "matched": 4 },
  "validationErrors": null
}

Pipe into Slack notifications, monitoring dashboards, or your own tooling.

GitHub Actions

name: Env Check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx ctroenv check --source .env.example

Build-Time Validation

Framework plugins validate during the build:

// Vite
ctroenvPlugin({ schema: "./src/env.ts", failOnError: true })

// Next.js
export default withCtroEnv(schema, nextConfig)

If validation fails, the build exits with code 1. No deployment reaches production with a missing DATABASE_URL.

Links: GitHub · Docs · npm

Previous: Framework-Specific Env Patterns
Next: Shipping Reusable Env Schemas

Framework-Specific Env Patterns

Odejobi Abiola Samuel — Sat, 27 Jun 2026 09:43:39 +0000

Your schema is portable. But each runtime loads environment variables differently. CtroEnv adapters bridge the gap — same validation logic, different data sources.

Node.js: process.env + .env Files

The @ctroenv/node adapter loads .env files and wraps process.env:

import { defineEnv, string, number } from "@ctroenv/core"
import { loadEnv } from "@ctroenv/node"

const env = defineEnv(schema, { source: loadEnv() })

loadEnv() resolves files in order:

.env — shared defaults
.env.{NODE_ENV} — environment-specific (.env.development, .env.production)
.env.local — local overrides (gitignored)

Later files override earlier ones. process.env takes precedence unless override: true.

Monorepo Root

loadEnv({ path: "../.." }) // look up two directories for root .env

Native Node 22+

Node 22 has built-in process.loadEnvFile(). Use native: true to delegate:

loadEnv({ native: true }) // uses process.loadEnvFile() if available

Falls back to the custom parser on older Node versions.

System Fallback

By default, only file values are returned. With system: true, missing keys fall through to process.env:

loadEnv({ system: true })

Standalone Parser

Use parseEnvFile() directly for custom file loading:

import { parseEnvFile } from "@ctroenv/node"

const content = readFileSync(".env.custom", "utf-8")
const vars = parseEnvFile(content)

Handles quotes, multiline values (backslash continuation), interpolation (${VAR}), comments, and export prefix.

Vite: Build-Time Validation

The @ctroenv/vite plugin validates during the build:

// vite.config.ts
import { ctroenvPlugin } from "@ctroenv/vite"

export default defineConfig({
  plugins: [
    ctroenvPlugin({ schema: "./src/env.ts" }),
  ],
})

If DATABASE_URL is missing, the build fails — no broken artifacts shipped.

Schema Options

Pass a file path or inline definition:

// File path — imports the module, looks for `schema` export
ctroenvPlugin({ schema: "./src/env.ts" })

// Inline definition
ctroenvPlugin({
  schema: {
    DATABASE_URL: string().url(),
    PORT: number().port().default(3000),
  },
})

Fail on Error

ctroenvPlugin({ schema: "./src/env.ts", failOnError: false })
// warns instead of failing — useful for optional env vars

viteSource()

Use with defineEnv() directly in Vite code:

import { defineEnv } from "@ctroenv/core"
import { viteSource } from "@ctroenv/vite"

const env = defineEnv(schema, { source: viteSource() })

viteSource() reads from import.meta.env first, then falls back to process.env.

Next.js: Server/Client Split

Next.js bundles code for the browser. Server-only env vars must never reach the client bundle. The @ctroenv/nextjs adapter enforces this at runtime:

import { string, type ClientServerSchema } from "@ctroenv/core"
import { defineEnv } from "@ctroenv/nextjs"

const schema = {
  server: {
    DATABASE_URL: string().url(),
    JWT_SECRET: string().min(32).secret(),
  },
  client: {
    NEXT_PUBLIC_API_URL: string().url(),
  },
} satisfies ClientServerSchema

const env = defineEnv(schema)

Server components access everything. Client components can only access NEXT_PUBLIC_ variables — accessing a server var throws:

Server-only environment variable "DATABASE_URL" is not accessible on the client.
Prefix it with NEXT_PUBLIC_ to expose it.

Build-Time Validation

Wrap your Next.js config:

// next.config.ts
import { withCtroEnv } from "@ctroenv/nextjs"

export default withCtroEnv(schema, nextConfig)

Validates at config load time — before the build starts.

Accessing Secrets

Server secrets are masked ("********"). Use meta.get() for raw values:

env.JWT_SECRET           // "********"
env.meta.get("JWT_SECRET") // actual value

Choosing an Adapter

Runtime	Adapter	Source	Best for
Node.js	`@ctroenv/node`	`.env` files + `process.env`	APIs, CLIs, servers
Vite	`@ctroenv/vite`	`import.meta.env`	Frontend apps, SSG
Next.js	`@ctroenv/nextjs`	Server/client split	Full-stack apps
Cloudflare Workers	core's `workersSource()`	Worker env binding	Edge functions
Deno/Bun	core's `detectSource()`	Auto-detected	Cross-runtime apps

All adapters use the same schema. Switch between them by changing the source.

npm install @ctroenv/node @ctroenv/vite @ctroenv/nextjs

Links: GitHub · Docs · npm

Previous: Type-Safe Env Vars Without Zod
Next: Testing and Debugging Your Env Config

Type-Safe Env Vars Without Zod

Odejobi Abiola Samuel — Thu, 25 Jun 2026 12:41:03 +0000

Most TypeScript projects treat environment variables like second-class citizens. They're string | undefined everywhere, asserted with ! and parsed with parseInt(). TypeScript can't help because process.env is typed as Record<string, string | undefined>.

Schema-based validation fixes this. But most solutions bring zod, which adds 50 KB to your bundle. CtroEnv does it with zero dependencies and 6.5 KB gzipped.

How Inference Works

The type system reads each validator's configuration at compile time:

type InferredValue<V> =
  V extends Validator<infer T>
    ? V["metadata"] extends { hasDefault: true }
      ? T                    // .default() → non-nullable
      : V["metadata"] extends { optional: true }
        ? T | undefined      // .optional() → nullable
        : T                  // required → guaranteed present
    : never

This means the schema defines the type:

const env = defineEnv({
  PORT: number().port().default(3000),
  // ^? number — default makes it always present

  DB_URL: string().url(),
  // ^? string — required

  DEBUG: boolean().optional(),
  // ^? boolean | undefined — optional

  NODE_ENV: pick(["dev", "prod", "staging"] as const),
  // ^? "dev" | "prod" | "staging" — exact union
})

No interface Env { ... }. No z.infer<typeof Schema>. Add a new validator, and the type updates automatically.

Default vs Optional vs Required

The three states and their types:

Declaration	Type	Runtime behavior
`string()`	`string`	Required — throws if missing
`string().optional()`	`string \	undefined`
`string().default("x")`	`string`	Falls back to `"x"`
`string().optional().default("x")`	`string`	Default overrides optional

TypeScript reflects this exactly. Optional gives you | undefined. Default removes it.

The `as const` Requirement

pick() needs as const to preserve literal types:

pick(["dev", "prod"])           // type: string — widened
pick(["dev", "prod"] as const)  // type: "dev" | "prod" — exact union

Without as const, TypeScript widens the array to string[] and you lose the union.

Exhaustive Checking

With exact literal types, you get exhaustive checking:

switch (env.NODE_ENV) {
  case "dev": break
  case "prod": break
  case "staging": break
  // TypeScript error if you forget a case — and you can't match "production"
  // because it's not in the union
}

The Chain Order Gotcha

Type-specific methods (.url(), .email(), .min()) must come before chainable methods (.secret(), .optional(), .describe()):

string().url().secret()     // ✅ correct
string().secret().url()     // ❌ — .url() doesn't exist after .secret()

Reason: .secret() returns a generic Validator & ChainableMethods wrapper. The type-specific methods like .url() only exist on StringValidator. Once you call a chainable method, those are gone.

Quick reference:

// ✅ Correct
string().min(1).max(255).url().secret()
number().int().positive().default(42)
pick(["a", "b"] as const).optional()
boolean().default(false)

// ❌ Wrong
string().secret().url()    // .url() lost
number().optional().int()  // .int() lost

pick(), boolean(), semver(), ip(), uuid() have no type-specific refinements, so chain order doesn't matter for them.

Composing Schemas

defineSchema() + extendSchema() preserve full types through composition:

import { defineSchema, extendSchema } from "@ctroenv/core"

const base = defineSchema({
  NODE_ENV: pick(["dev", "prod"] as const).default("dev"),
})

const schema = extendSchema(base, {
  PORT: number().port().default(3000),
})

const env = defineEnv(schema)
// env.NODE_ENV: "dev" | "prod"
// env.PORT: number

The composed type merges both schemas. Extension keys override base keys — with a dev-mode warning on conflicts.

Compared to Zod

// zod — 50 KB dependency
import { z } from "zod"
const Schema = z.object({
  PORT: z.coerce.number().min(1).max(65535).default(3000),
  DB_URL: z.string().url(),
})
type Env = z.infer<typeof Schema>

// CtroEnv — 6.5 KB, zero deps
import { defineEnv, string, number } from "@ctroenv/core"
const env = defineEnv({
  PORT: number().port().default(3000),
  DB_URL: string().url(),
})
// ^? { PORT: number; DB_URL: string } — inferred automatically

Same validation power. No manual type extraction. No extra dependency.

npm install @ctroenv/core

Links: GitHub · Docs · npm

Previous: Why Your .env File Is Lying to You
Next: Framework-Specific Env Patterns

Why Your .env File Is Lying to You

Odejobi Abiola Samuel — Thu, 25 Jun 2026 08:23:47 +0000

Two weeks ago I deployed a service that crashed on the first request. Not because the code was wrong — because process.env.DATABASE_URL was undefined and nobody caught it until a user hit the endpoint.

I've made this mistake enough times to recognize the pattern: environment variables in Node.js are string | undefined. TypeScript shrugs. Validation is your problem. Most teams don't do it, or they scatter it across 15 files with parseInt() and ?? operators.

The Three Lies process.env Tells You

1. "This variable exists"

const dbUrl = process.env.DATABASE_URL
//    ^? string | undefined — TypeScript can't help

It might exist. It might not. You won't know until runtime. If it's undefined, the error surfaces at the point of first use — not at startup.

2. "This value is the right type"

const port = process.env.PORT // "3000" — it's a string!
app.listen(port + 1)          // listens on "30001", not 3001

PORT is semantically a number. At runtime it's a string. Every consumer has to parse it. Nobody does it consistently.

3. "The format is correct"

// .env
DATABASE_URL=localhost:5432/myapp  // forgot postgres://

// somewhere in your app
new URL(process.env.DATABASE_URL)  // TypeError: Invalid URL

No error at import. No error at server start. The first database query crashes.

The Manual Approach

I've written this function more times than I can count:

function getEnv() {
  const dbUrl = process.env.DATABASE_URL
  if (!dbUrl) throw new Error("DATABASE_URL is required")

  const port = parseInt(process.env.PORT ?? "3000", 10)
  if (isNaN(port) || port < 1 || port > 65535) {
    throw new Error("PORT must be between 1 and 65535")
  }

  const nodeEnv = process.env.NODE_ENV ?? "development"
  if (!["development", "production", "test"].includes(nodeEnv)) {
    throw new Error(`Invalid NODE_ENV: ${nodeEnv}`)
  }

  return { dbUrl, port, nodeEnv } as const
}

It works. But it's repetitive, undocumented, and TypeScript can't infer literal types from it. Every project reinvents this same function with slightly different bugs.

Schema-Based Validation

CtroEnv does the same thing with a schema:

import { defineEnv, string, number, pick } from "@ctroenv/core"

const env = defineEnv({
  DATABASE_URL: string().url().describe("PostgreSQL connection URL"),
  PORT: number().port().default(3000),
  NODE_ENV: pick(["development", "production", "test"] as const).default("development"),
})

env.PORT is number — already parsed
env.NODE_ENV is "development" | "production" | "test" — exact union, no typos
env.DATABASE_URL is string — guaranteed present and valid

If anything is missing or invalid, defineEnv() throws immediately with every error grouped:

● Missing required (1)

  DATABASE_URL  Add this variable to your .env file

✗ Invalid (1)

  PORT  Expected a port number (1-65535), received 0

No hunting through logs. The app crashes at import time, not on the first request.

What You Get

Problem	Raw process.env	CtroEnv
Type safety	`string \	undefined`
Startup validation	None	All vars validated
Error clarity	`cannot read property of undefined`	Grouped, descriptive
Defaults	Manual `??`	`.default()`
Secret handling	Silent	`.secret()` masks at runtime
CI integration	None	`ctroenv check`, `ctroenv validate`

The Validators

string().url()              // valid URL
string().email()            // valid email (HTML5 regex)
string().port()             // port 1-65535
string().min(8)             // minimum length
string().max(255)           // maximum length
string().hostname()         // RFC 1123 hostname
string().regex(/^[a-z]+$/)  // custom pattern

number().int()              // integer
number().positive()         // > 0
number().port()             // 1-65535
number().min(1)             // minimum value
number().max(100)           // maximum value

boolean()                   // "true"/"false", "yes"/"no", "1"/"0", "y"/"n"
pick(["dev", "prod"])       // exact string union

// Chainable on all validators:
.optional() .default(v) .describe(t) .secret() .validate(fn)

One line per variable, and TypeScript infers everything from the schema.

npm install @ctroenv/core

Links: GitHub · Docs · npm

Next: Type-Safe Env Vars Without Zod

How to Validate Environment Variables Without a Library (And Why You Should Anyway)

Odejobi Abiola Samuel — Wed, 24 Jun 2026 14:27:22 +0000

How to Validate Environment Variables Without a Library (And Why You Should Anyway)

I'm a fan of minimal dependencies. Every library you add is code you don't control, surface area for bugs, and another thing to keep up to date. So when I started a new project last month, I told myself: no env validation library. I'll write it myself. It's just a few vars.

Six hours later I had a surprisingly solid little validation function. Let me show you what I built.

Part 1: Your Own Env Validation in Plain TypeScript

Here's the complete thing, about 60 lines:

type EnvSchema = Record<string, {
  type: "string" | "number" | "boolean"
  required?: boolean
  default?: unknown
}>

function loadEnv<T extends EnvSchema>(
  schema: T,
  source: Record<string, string | undefined> = process.env
): { [K in keyof T]: T[K]["type"] extends "number" ? number
     : T[K]["type"] extends "boolean" ? boolean
     : string } {

  const result: Record<string, unknown> = {}

  for (const [key, config] of Object.entries(schema)) {
    let raw = source[key]

    if (raw === undefined) {
      if (config.default !== undefined) {
        raw = String(config.default)
      } else if (config.required !== false) {
        throw new Error(`Missing required env var: ${key}`)
      } else {
        continue
      }
    }

    switch (config.type) {
      case "number": {
        const num = Number(raw)
        if (Number.isNaN(num)) {
          throw new Error(`${key} must be a number, got "${raw}"`)
        }
        result[key] = num
        break
      }
      case "boolean": {
        const truthy = ["true", "yes", "1", "on"]
        const falsy = ["false", "no", "0", "off"]
        if (truthy.includes(raw.toLowerCase())) {
          result[key] = true
        } else if (falsy.includes(raw.toLowerCase())) {
          result[key] = false
        } else {
          throw new Error(`${key} must be a boolean, got "${raw}"`)
        }
        break
      }
      default:
        result[key] = raw
    }
  }

  return result as any
}

Usage:

const env = loadEnv({
  PORT: { type: "number", default: 3000 },
  DATABASE_URL: { type: "string", required: true },
  DEBUG: { type: "boolean", default: false },
})

env.PORT // number

That works. It's typed. It validates at startup. I was pretty proud of this for about a day.

Part 2: Why You Might Want a Library Anyway

Then the project grew. Here's what happened:

Your validation function grows. You start adding refinements: "PORT must be between 1024 and 65535", "DATABASE_URL must start with postgres://". Now your schema config has extra fields and your validation loop has special cases.

Error messages are inconsistent. I wrote decent errors, but what about when someone else touches the file? Every team member writes messages differently. Some are helpful. Some say "invalid". Good luck debugging that in CI.

No CLI tooling. Want to validate .env.production before a deploy? You're running a script that imports your config module. You can't just point a CLI at an env file and check it against your schema.

No documentation generation. I kept a ENVIRONMENT.md file updated for about three days. Then it was stale forever. Nobody wants to manually document env vars.

No framework adapters. Vite uses import.meta.env. Next.js inlines vars at build time. If your config module assumes process.env, it doesn't work everywhere. You end up maintaining adapters yourself.

No secret masking. One accidental console.log(config) later, your entire team has new API keys to rotate.

Part 3: What CtroEnv Does Differently

I'm not here to tell you CtroEnv is the only answer. But since I built it, let me show you what I mean by "a library handles this."

Same validation from Part 1:

import { defineEnv, string, number, boolean } from "@ctroenv/core"

const env = defineEnv({
  PORT: number().port().default(3000),
  DATABASE_URL: string().url(),
  DEBUG: boolean().default(false),
})

Same type safety. Fewer lines. But the real difference isn't in the code — it's everything around it.

CLI validation: npx ctroenv validate --source .env.production — checks your env against the schema and exits with a non-zero code on failure. Drop it in your CI pipeline.

Generated docs: npx ctroenv docs produces an ENVIRONMENT.md file that's always accurate because it's generated from the schema.

Secret masking: Add .secret() to any variable and it's hidden from logs, console output, and JSON.stringify.

Framework adapters: One schema, but it works with process.env, import.meta.env, and Next.js's build-time inlining without changing your code.

Consistent errors: Every validation failure follows the same format, with error codes you can check programmatically.

So Should You Use a Library?

If you have 3 env vars in a personal project, write your own function. You'll learn something and you won't need the extras.

If you have a team, a CI pipeline, staging and production deploys, and more than 5 env vars — use a library. The validation logic is the easy part. It's the tooling, the docs, the edge cases, and the framework support that'll eat your time.

Links: GitHub | npm | Docs

TypeScript Environment Variables: The Complete Guide

Odejobi Abiola Samuel — Tue, 23 Jun 2026 03:11:33 +0000

TypeScript Environment Variables: The Complete Guide

What Are Environment Variables?

Environment variables are key-value pairs your operating system or runtime passes into a process. Think of them as external configuration that stays outside your code. You don't want to hardcode a database URL or an API key — env vars let you change those values between dev, staging, and production without touching a single source file.

How Node.js Exposes Them

Node.js makes every env var available through process.env. It's a plain object where each key is a variable name and each value is a string — or undefined if the variable doesn't exist.

console.log(process.env.PORT)   // "3000" or undefined
console.log(process.env.NODE_ENV) // "development" or undefined

That's it. One global object. Simple, but also the source of most of the pain we'll talk about.

The TypeScript Problem

Here's the issue: process.env is typed as Record<string, string | undefined>. That means every single lookup returns string | undefined, even for variables you know exist. TypeScript can't help you catch typos, missing vars, or type mismatches at compile time.

const port = process.env.PORT
//    ^? string | undefined

You can't ship this without validation unless you enjoy runtime crashes.

Pattern 1: Direct Access with Fallbacks

The simplest approach. Use nullish coalescing to provide defaults.

const PORT = Number(process.env.PORT ?? "3000")
const NODE_ENV = process.env.NODE_ENV ?? "development"

You'll see this in a ton of codebases. It's fast to write and works fine for small projects. The downside? Every file that reads env vars duplicates this logic, and there's no central place to see every variable your app expects.

Pattern 2: Manual Validation Function

A step up. Centralize your env access in one file with a helper that throws on missing required vars.

function getEnv(key: string, fallback?: string): string {
  const value = process.env[key] ?? fallback
  if (value === undefined) {
    throw new Error(`Missing required env var: ${key}`)
  }
  return value
}

export const config = {
  port: Number(getEnv("PORT", "3000")),
  nodeEnv: getEnv("NODE_ENV", "development"),
  databaseUrl: getEnv("DATABASE_URL"),
}

Better. Now all vars live in one place. But you're still manually parsing types, and error messages are whatever you decide to write. Add ten more vars and this file starts to feel heavy.

Pattern 3: Schema-Based Validation

This is where libraries come in. Instead of writing parsing logic yourself, you declare a schema and let the library handle validation, typing, and error formatting.

Using CtroEnv (one option among several — Zod also works well for this):

import { defineEnv, string, number } from "@ctroenv/core"

const env = defineEnv({
  PORT: number().port().default(3000),
  DATABASE_URL: string().url(),
  NODE_ENV: string().optional(),
})

env.PORT // number — TypeScript knows this

The schema is your single source of truth. Every env var, its type, its constraints — one declaration. The library generates proper error messages, handles type coercion, and gives you full TypeScript inference.

Handling Different Types

Env vars are always strings, but your app needs real types.

Numbers: Parse with Number() or use a schema that does it for you. Watch out for NaN — Number("abc") returns NaN, not an error.
Booleans: "true" / "false", "yes" / "no", "1" / "0" — decide what you accept. A library like CtroEnv handles all these variants.
Enums / Pick from a set: You want to restrict a value to "development" | "production". With schemas, you use pick(["dev", "prod"]). With raw code, you'd write a check against an array.

Working with .env Files

.env files are not a Node.js feature — they're a convention popularized by dotenv. The file looks like this:

PORT=4000
DATABASE_URL=postgres://localhost:5432/myapp

In Node.js, you load them at the top of your entry file:

import "dotenv/config"
// or
import { loadEnv } from "@ctroenv/node"
await loadEnv()

Important: .env files belong in .gitignore. They contain secrets. Your repo should have a .env.example that documents every variable without real values.

Secrets: What Not to Do

Never log env vars. Never pass them to error reporting services. Never commit them to git. Never forward them to third-party APIs as-is if they contain secrets.

If you're using CtroEnv, marking a variable as .secret() masks its value in console output and stringification:

const env = defineEnv({
  JWT_SECRET: string().secret(),
})

console.log(env.JWT_SECRET) // "********"
env.meta.get("JWT_SECRET")  // actual value

This prevents accidental leaks during debugging or logging.

CI/CD: Validate Before Deploy

The worst time to discover a missing env var is at 3 AM after a deploy. Validate early:

# Using CtroEnv CLI
npx ctroenv validate --source .env.production

# Or just run a script that imports your config
node -e "require('./src/config').validate()"

Run this in your CI pipeline after install, before build. If validation fails, fail the build.

Framework Specifics

Node.js (Express, Fastify, etc.): Use process.env directly, or better, load your config module at startup. CtroEnv's Node adapter adds .env file loading on top.

Vite: process.env doesn't exist in the browser. Vite exposes import.meta.env for public variables. Use VITE_ prefix for client-side vars. The CtroEnv Vite plugin bridges this.

Next.js: Next.js inlines process.env at build time for any var referenced in server code. But NEXT_PUBLIC_ vars get inlined into client bundles. Use CtroEnv's Next.js adapter for proper server/client split handling.

Wrapping Up

You don't need a library to read env vars. But you do need some system to validate them, type them, and catch missing values before runtime. Whether that's a 10-line function or a schema library is up to you and the size of your project.

The important thing is: don't access process.env directly across 40 files. Centralize. Validate. Let TypeScript know what's going on.

Links: GitHub | npm | Docs

Your .env.example Is Lying to You, Here's How to Fix It

Odejobi Abiola Samuel — Tue, 23 Jun 2026 02:04:16 +0000

Last month I cloned a project, copied .env.example to .env, and ran npm run dev. The app crashed with a confusing database error. Turns out the example file was missing DATABASE_URL — someone had added it to the actual code months ago but forgot to update the example 🤔. I spent close to 45 minutes digging through source to find every env var the app needed.

This isn't a one-off. It can happens in every project that maintains .env.example by hand.

The problem

.env.example is documentation, and like all documentation, it drifts. Here's what goes wrong:

People add env vars and forget to update the example. This is the most common one. You need a new API key, so you add STRIPE_SECRET_KEY to your code and your actual .env. The example never gets touched.
People remove env vars and leave them in the example. New devs waste time setting up vars that aren't even used anymore.
Comments are minimal or nonexistent. A bare key like SMTP_HOST= tells you nothing. Is it a URL? An IP? A hostname? Good luck guessing.
No one knows what's optional vs required. New team members don't know if they can start without setting SENTRY_DSN or if the app will crash.

The manual workflow is: add a var to code → (hopefully) remember to add it to .env.example → (hopefully) write a comment. That's three places to update. It fails constantly.

The fix: generate it from your schema

If you define your env vars in a schema file, you can generate .env.example from that file. The schema is the source of truth, so the example can never drift.

Here's what I do with CtroEnv (but the principle applies to any schema-based approach):

// src/env.ts
import { defineEnv, string, number, pick } from "@ctroenv/core";

export const env = defineEnv({
  DATABASE_URL: string().url().describe("Full PostgreSQL connection string"),
  PORT: number().port().default(3000).describe("HTTP server port"),
  NODE_ENV: pick(["dev", "prod"] as const).describe("Runtime environment"),
  SENTRY_DSN: string()
    .optional()
    .describe("Sentry DSN for error tracking (optional)"),
  SMTP_HOST: string().describe("SMTP server hostname"),
  SMTP_PORT: number().port().default(587).describe("SMTP server port"),
});

Then run:

npx @ctroenv/cli generate

The output writes to .env.example automatically:

# DATABASE_URL (required)
# Full PostgreSQL connection string
DATABASE_URL=

# PORT (optional, defaults to 3000)
# HTTP server port
PORT=3000

# NODE_ENV (required)
# Runtime environment
# Allowed values: dev, prod
NODE_ENV=

# SENTRY_DSN (optional)
# Sentry DSN for error tracking (optional)
SENTRY_DSN=

# SMTP_HOST (required)
# SMTP server hostname
SMTP_HOST=

# SMTP_PORT (optional, defaults to 587)
# SMTP server port
SMTP_PORT=587

Compare this to the manual version that probably exists in your project right now:

DATABASE_URL=
PORT=3000
NODE_ENV=dev
SENTRY_DSN=
SMTP_HOST=
SMTP_PORT=587

The generated version tells you:

What each var is for (the .describe() text becomes a comment)
Whether it's required or optional
What the allowed values are (for pick validators)
What the default is

How it stays in sync

When you add a new env var, you add it to the schema. That's one place. The .env.example gets regenerated from the schema. It's impossible for them to disagree because the schema is the only thing you edit.

When you remove a var, it's also one edit. Next time someone runs npx ctroenv generate, the old var doesn't appear. No stale keys.

Bonus: this helps onboarding

A new developer cloning your repo can run:

npx @ctroenv/cli check

This compares their current .env against the schema and tells them exactly what's missing or wrong. No more "I think I set everything but it's still crashing."

Bonus: ENVIRONMENT.md generation

The same schema can generate full documentation:

npx @ctroenv/cli docs --format markdown

This produces an ENVIRONMENT.md file with a table of every env var, its type, whether it's required, its default, and its description. Stick it in your repo and link to it from your README.

What about other tools?

If you're using Zod, you can parse env vars with it, but generating .env.example from Zod schemas isn't built in. You'd need to write your own code to extract descriptions and defaults from Zod's ._def.

envalid has envalid.cleanEnv but no CLI-based generation. Same deal — you'd need a custom script.

t3-env doesn't support generation either.

That's actually what pushed me toward CtroEnv — I wanted npx ctroenv generate to just work.

Practical advice

Stop editing .env.example directly. Even if you don't switch tools, make it a rule: edit the schema, regenerate the example.
Run generation as a pre-commit hook. Catch drift before it hits the repo.
Add descriptions. Future you will thank present you when you're debugging a production issue and need to remember what STRIPE_WEBHOOK_SECRET is for.
Run check in CI. Fail the build if someone's .env doesn't match the schema.

Your .env.example file should be the first thing a new developer sees when they clone your repo. Make sure it's telling the truth.

Not every TypeScript project needs the same env setup. I compared CtroEnv, Zod, envalid, and t3-env across DX, framework support, dependencies, CLI workflow, and maintenance tradeoffs. Curious which approach people prefer.

Odejobi Abiola Samuel — Mon, 22 Jun 2026 23:53:06 +0000

Odejobi Abiola Samuel

Jun 22

Stop Shipping Broken Env Config: Comparing 4 TypeScript Validators

#typescript #node #javascript #webdev

4 min read

DEV Community: Odejobi Abiola Samuel

I Built a Sync Engine for a 0-Dep Client-Side Database, Here's What I Learned

The Hard Part Is Not the Data Transfer

Change Tracking: The Foundation

Pull: Cursor-Based Pagination

Push: Batch and Retry

Conflict Resolution: The Part I Got Wrong

Transport: HTTP with a Single URL

What I'd Do Differently

Trade-offs I'm Still Thinking About

ctrodb 1.4: Offline Sync for the Browser, Zero Dependencies

What's in v1.4

What else

Links

Environment Variables Don't Have to Suck

The core idea

What it actually does at runtime

Where this saves real time

1. No more startup crashes with bad types

2. Boolean coercion that actually makes sense

3. Secrets that don't leak in logs

The CLI is worth mentioning

How it handles real-world mess

Next.js (server/client split)

Vite plugin

Watching for changes

What I left out

The numbers

Shipping Reusable Env Schemas

Publishing a Schema from Your Library

Conflict Handling

Building Custom Validators

Error Helpers

Adding Refinement Methods

Schema Composition in Monorepos

Auto-Generated Docs

Testing Schemas

Summary

Testing and Debugging Your Env Config

Testing with objectSource

Testing Validation Errors

Testing Secret Masking

Debugging with Error Codes

formatErrors

CI/CD Integration

Fast Key Check

Strict Validation

Unknown Key Warnings

JSON Output

GitHub Actions

Build-Time Validation

Framework-Specific Env Patterns

Node.js: process.env + .env Files

Monorepo Root

Native Node 22+

System Fallback

Standalone Parser

Vite: Build-Time Validation

Schema Options

Fail on Error

viteSource()

Next.js: Server/Client Split

Build-Time Validation

Accessing Secrets

Choosing an Adapter

Type-Safe Env Vars Without Zod

How Inference Works

Default vs Optional vs Required

The as const Requirement

Exhaustive Checking

The Chain Order Gotcha

Composing Schemas

Compared to Zod

Why Your .env File Is Lying to You

The Three Lies process.env Tells You

1. "This variable exists"

2. "This value is the right type"

3. "The format is correct"

The Manual Approach

Schema-Based Validation

The `as const` Requirement