DEV Community: Odejobi Abiola Samuel

Secrets at Rest, Schemas at Scale — What's New in CtroEnv v1.1.0

Odejobi Abiola Samuel — Wed, 17 Jun 2026 17:54:10 +0000

I accidentally logged a JWT secret to the console while debugging a test. Twice. The first time I thought "eh, it's just dev." The second time I realized the problem wasn't me — it was that my env tool treated secrets and config the same way. No distinction. No protection. Just a flat bag of strings where a console.log(env) dumped everything.

That's the gap v1.1.0 tries to close.

Runtime Secret Masking

The API is simple — add .secret() to any validator:

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

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

Now env.JWT_SECRET returns "********" instead of the real value:

console.log(env.JWT_SECRET)      // "********"
console.log(env.DATABASE_URL)    // "postgresql://..." — visible as usual

// Real value when you need it:
env.meta.get("JWT_SECRET")       // "supersecretkey..."
env.meta.keys()                  // ["JWT_SECRET"]
env.meta.has("JWT_SECRET")       // true

This means console.log(env), error reports, and JSON.stringify are safe by default:

JSON.stringify(env)
// {"DATABASE_URL":"postgresql://...","JWT_SECRET":"********"}

.meta is non-enumerable — it won't show up in Object.keys(), for...in, or spreads. You have to reach for it explicitly.

Why a Proxy?

Object.freeze can't intercept reads. The ES Proxy spec prevents a get trap from returning different values for non-configurable target properties. So instead of freezing, we use a Proxy with set/deleteProperty traps. The result feels identical — you can't mutate it, but reads on secret keys get masked.

Error Messages Are Safe Too

Secret values are redacted in error output automatically:

try {
  defineEnv({ KEY: string().secret() }, { source: { KEY: "exposed" } })
} catch (e) {
  if (e instanceof CtroEnvError) {
    console.log(e.errors[0].value) // "********" — not "exposed"
  }
}

Schema Composition for Monorepos

The second feature comes from working on a monorepo ourselves. We had three packages (shared, api, worker) all needing DATABASE_URL and JWT_SECRET, but each needing their own specific vars too. Before, we copy-pasted. After, we composed:

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

// Define shared vars once
const base = defineSchema({
  DATABASE_URL: string().url(),
  REDIS_URL: string().url().optional(),
  LOG_LEVEL: string().default("info"),
})

// API service extends
const apiSchema = extendSchema(base, {
  PORT: number().port().default(4000),
  API_KEY: string().secret(),
})

// Worker extends
const workerSchema = extendSchema(base, {
  QUEUE_CONCURRENCY: number().positive().default(5),
  JOB_TIMEOUT: number().positive().default(30000),
})

const env = defineEnv(apiSchema)
env.DATABASE_URL // string — inherited
env.API_KEY      // "********" — secret + inherited

Merge Semantics

Extension keys override base keys. Dev mode (NODE_ENV=development) logs a warning on conflict so you don't accidentally shadow a shared var.

Chaining works naturally:

const stagingSchema = extendSchema(base, { /* overrides */ })
const prodSchema = extendSchema(stagingSchema, { /* overrides */ })

Real Example

We shipped a monorepo example with the repo:

monorepo/
  .env                          # Root env file
  packages/
    shared/src/index.ts         # defineSchema({ DATABASE_URL, REDIS_URL, LOG_LEVEL })
    api/src/env.ts              # extendSchema(base, { PORT, API_KEY })
    api/src/index.ts            # defineEnv(apiSchema)
    worker/src/env.ts           # extendSchema(base, { QUEUE_CONCURRENCY, JOB_TIMEOUT })
    worker/src/index.ts         # defineEnv(workerSchema)

Each package loads env from root via loadEnv({ path: "../.." }). One .env file, three schemas.

AGENTS.md

CtroEnv now ships an AGENTS.md at the repo root. It covers the API, chain order rules, error handling, CLI commands, and anti-patterns. Any AI agent that lands on the repo reads it automatically — opencode, Cursor, Copilot, Claude Code, Cline.

There's also a skill file at .opencode/skills/ctroenv/SKILL.md with worked examples.

What Else Changed

Package	Version	What
`@ctroenv/core`	1.1.0	Secret masking, schema composition, EnvMeta API
`@ctroenv/cli`	1.1.0	Config-level secrets masking
`@ctroenv/{node,vite,nextjs,shared}`	1.0.2	README + LICENSE polish

No breaking changes. Existing schemas keep working.

npm install @ctroenv/core@^1.1.0 @ctroenv/cli@^1.1.0

The v1.2.0 roadmap: a zodToCtroEnv bridge, branded types (Email, URL), and deeper Next.js RSC integration.

Try string().secret() and see if it catches anything you'd rather keep quiet.

Building Your Own CtroEnv Validators

Odejobi Abiola Samuel — Wed, 17 Jun 2026 17:44:45 +0000

I needed a validator that checks if a string is a valid IPv6 address. The four built-in validators — string(), number(), boolean(), pick() — cover the common cases, but this specific case wasn't there.

So I wrote one. Here's how.

How a Validator Works

A CtroEnv validator is an object with a parse function and metadata:

interface Validator<T> {
  readonly _type: T
  parse(input: unknown, context: ParseContext): ParseResult<T>
  readonly metadata: ValidatorMetadata
}

parse() receives the raw input and returns success or failure:

interface ParseContext { key: string; path: readonly string[] }

type ParseResult<T> = ParseResultOk<T> | ParseResultFail

interface ParseResultOk<T> { success: true; value: T; errors: readonly ValidationError[] }
interface ParseResultFail { success: false; value?: unknown; errors: readonly ValidationError[] }

Two helpers create these results:

import { parseOk, singleError } from "@ctroenv/core"

parseOk("hello")   // { success: true, value: "hello", errors: [] }
singleError(err)   // { success: false, errors: [err] }

Building a Custom Validator

createValidator() is the simplest path:

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

function semver() {
  const pattern = /^\d+\.\d+\.\d+$/

  return createValidator<string>(
    (input, context) => {
      if (typeof input !== "string") {
        return singleError(
          errType(context.key, typeof input, "a semver string", {
            suggestion: "Use format MAJOR.MINOR.PATCH (e.g., '1.2.3').",
          }),
        )
      }

      if (!pattern.test(input)) {
        return singleError(
          errInvalid(context.key, input, `"${input}" is not a valid semver version`, {
            suggestion: "Use format MAJOR.MINOR.PATCH (e.g., '1.2.3').",
          }),
        )
      }

      return parseOk(input)
    },
    { typeLabel: "semver" },
  )
}

But this returns a bare Validator<string> — no .default(), .describe(), or .optional().

Adding Chainable Methods with `applyChain`

applyChain() wraps any validator and adds the method set (.optional(), .default(), .describe(), .secret(), .validate()):

import { applyChain } from "@ctroenv/core"

function semver() {
  const base = createValidator<string>(
    (input, context) => {
      // ... validation logic ...
    },
    { typeLabel: "semver" },
  )

  return applyChain(base)
}

Now .default(), .describe(), .optional(), .secret(), and .validate() all work. The return type is Validator<string> & ChainableMethods<string>.

Adding Refinement Methods

To add methods like .min() on StringValidator, extend the wrapped validator:

interface SemverValidator extends Validator<string>, ChainableMethods<string> {
  major(min: number): SemverValidator
  minor(min: number): SemverValidator
  patch(min: number): SemverValidator
  allowVPrefix(): SemverValidator
}

function semver(): SemverValidator {
  const base = createValidator<string>(
    (input, context) => {
      if (typeof input !== "string") {
        return singleError(errType(context.key, typeof input, "a semver string"))
      }
      const cleaned = input.startsWith("v") ? input.slice(1) : input
      const parts = cleaned.split(".").map(Number)
      if (parts.length !== 3 || parts.some(isNaN)) {
        return singleError(errInvalid(context.key, input, `"${input}" is not a valid semver`))
      }
      return parseOk(cleaned)
    },
    { typeLabel: "semver" },
  )

  const chainable = applyChain(base)
  const extended = chainable as SemverValidator

  extended.major = (min: number) => {
    const original = extended
    const wrapped = createValidator<string>(
      (input, context) => {
        const result = original.parse(input, context)
        if (!result.success) return result
        const major = Number(result.value.split(".")[0])
        if (major < min) {
          return singleError(errInvalid(context.key, result.value, `Major version must be at least ${min}`))
        }
        return result
      },
      original.metadata,
    )
    return applyChain(wrapped) as SemverValidator
  }

  return extended
}

This is the same pattern StringValidator and NumberValidator use internally.

Writing a Refinement Function

If you don't need a full validator, write a refinement that wraps an existing one. This is what url(), email(), min(), max(), and port() do:

function hexColor(): <T extends string>(v: Validator<T>) => Validator<T> {
  return (validator: Validator<string>) => {
    const original = validator
    const wrapped = createValidator<string>(
      (input, context) => {
        const result = original.parse(input, context)
        if (!result.success) return result
        if (!/^#[0-9a-fA-F]{3,6}$/.test(result.value)) {
          return singleError(
            errInvalid(context.key, result.value, `"${result.value}" is not a valid hex color`, {
              suggestion: "Use #rgb, #rrggbb, or #rrggbbaa format.",
            }),
          )
        }
        return result
      },
      original.metadata,
    )
    return applyChain(wrapped)
  }
}

Usage:

const env = defineEnv({
  THEME_COLOR: hexColor()(string()).default("#3b82f6"),
})

A Complete Example: IP Address Validator

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

interface IpValidator extends Validator<string>, ChainableMethods<string> {
  v4(): IpValidator
  v6(): IpValidator
}

function ip(): IpValidator {
  const base = createValidator<string>(
    (input, context) => {
      if (typeof input !== "string") {
        return singleError(errType(context.key, typeof input, "an IP address"))
      }

      const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/
      const match = input.match(ipv4)
      if (match) {
        const valid = match.slice(1).every((octet) => {
          const n = Number(octet); return n >= 0 && n <= 255
        })
        if (!valid) {
          return singleError(errInvalid(context.key, input, "IPv4 octets must be between 0 and 255"))
        }
        return parseOk(input)
      }

      if (input.includes(":")) {
        const parts = input.split(":")
        if (parts.length >= 2 && parts.length <= 8) return parseOk(input)
      }

      return singleError(errInvalid(context.key, input, `"${input}" is not a valid IP address`))
    },
    { typeLabel: "ip" },
  )

  const chainable = applyChain(base)
  const extended = chainable as IpValidator

  extended.v4 = () => {
    const original = extended
    const wrapped = createValidator<string>(
      (input, context) => {
        const result = original.parse(input, context)
        if (!result.success) return result
        if (result.value.includes(":")) {
          return singleError(errInvalid(context.key, result.value, "Expected IPv4 address, received IPv6"))
        }
        return result
      },
      original.metadata,
    )
    return applyChain(wrapped) as IpValidator
  }

  return extended
}

const env = defineEnv({
  TRUSTED_PROXY: ip().v4().describe("Trusted proxy IP (IPv4 only)"),
  DNS_SERVER: ip().optional().describe("Custom DNS server"),
})

Error Factories

Available for building custom validators:

import {
  errMissing,   // "Missing required environment variable: KEY"
  errType,      // "Expected a string, received number"
  errInvalid,   // "Invalid URL"
  errCoerce,    // 'Failed to coerce "foo" to number'
  errWrap,      // Generic wrapper for any ErrorCode
} from "@ctroenv/core"

errInvalid(context.key, value, "Custom error message", {
  suggestion: "Here's how to fix it.",
})

Publishing Custom Validators

Publish as @ctroenv/community-<name>:

{
  "name": "@ctroenv/community-ip",
  "version": "1.0.0",
  "type": "module",
  "dependencies": { "@ctroenv/core": "^1.0.0" }
}

// src/index.ts
export { ip } from "./ip"
export type { IpValidator } from "./ip"

Only @ctroenv/core as a dependency. The same primitives that built the built-in validators.

API	Purpose
`createValidator(parseFn, metadata)`	Create a base validator with custom parse logic
`applyChain(validator)`	Add `.optional()`, `.default()`, `.describe()`, `.secret()`, `.validate()`
`parseOk(value)`	Return a successful parse result
`singleError(error)`	Return a failed parse result
`errType`, `errInvalid`, etc.	Create typed `ValidationError` instances
Refinement functions	Wrap an existing validator with additional constraints

The same primitives that built string(), number(), boolean(), and pick() are available to you. The only difference between a built-in validator and a community one is which npm package it lives in.

If you build something useful, open a PR or publish it under @ctroenv/community-*.

Resources: Docs · GitHub · Contributing guide

This was the final article in the series. Thanks for reading!

Monorepo Environment Management at Scale

Odejobi Abiola Samuel — Wed, 17 Jun 2026 17:41:56 +0000

We run a monorepo with three packages — shared, api, and worker. The API needs PORT and CORS_ORIGIN. The worker needs QUEUE_CONCURRENCY and JOB_TIMEOUT. Both need DATABASE_URL, REDIS_URL, and JWT_SECRET.

Before CtroEnv v1.1.0, we duplicated schemas. Every package had its own if (!process.env.DATABASE_URL) block, and every time we changed validation rules we had to hunt down every copy.

The Pattern: Define Once, Extend Per-Service

1. Shared Schema Package

// packages/shared/src/index.ts
import { string, pick } from "@ctroenv/core"

export const base = {
  NODE_ENV: pick(["development", "staging", "production"] as const).default("development"),
  DATABASE_URL: string().url().secret().describe("PostgreSQL connection URL"),
  JWT_SECRET: string().secret().min(32).describe("JWT signing secret"),
  REDIS_URL: string().url().secret().optional().describe("Redis connection URL"),
}

No defineEnv() call, no source binding, no side effects. Pure schema.

2. Extend in Each Service

// packages/api/src/env.ts
import { defineEnv, string, number } from "@ctroenv/core"
import { loadEnv } from "@ctroenv/node"
import { base } from "@example/shared-config"

export const schema = {
  ...base,
  PORT: number().port().default(3000),
  HOST: string().default("0.0.0.0"),
  CORS_ORIGIN: string().url().describe("Allowed CORS origin"),
  API_VERSION: string().regex(/^\d+\.\d+$/).describe("API version"),
}

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

// packages/worker/src/env.ts
import { defineEnv, string, number } from "@ctroenv/core"
import { loadEnv } from "@ctroenv/node"
import { base } from "@example/shared-config"

export const schema = {
  ...base,
  QUEUE_CONCURRENCY: number().int().min(1).default(5),
  WORKER_TIMEOUT: number().int().min(1000).default(30000),
  WORKER_LOG_LEVEL: string().default("info"),
}

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

Each service validates its own schema against its own source. The shared vars inherit their validators from base. Tighten DATABASE_URL in one place — both services pick it up.

This is also available via defineSchema() and extendSchema() if you prefer a more explicit API:

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

const base = defineSchema({
  DATABASE_URL: string().url(),
})

const apiSchema = extendSchema(base, {
  PORT: number().port().default(4000),
})

extendSchema merges with spread semantics — extension keys override base. Dev mode warns on conflicts.

Running Validation in CI

The CLI has four commands for CI pipelines.

`ctroenv validate` — Fail on Invalid Values

# .github/workflows/ci.yml
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run build -w packages/shared
      - run: npx ctroenv validate --source .env
        working-directory: packages/api

`ctroenv check` — Detect Drift

      - run: npx ctroenv check
        working-directory: packages/api

Reports vars in the schema but not in .env, and vars in .env but not in the schema (typos, leftovers).

`ctroenv generate` — Keep `.env.example` in Sync

npx ctroenv generate

Produces:

# DATABASE_URL (required)
# PostgreSQL connection URL
# DATABASE_URL=

# PORT (optional, default: 3000)
PORT=3000

Secret variables are commented out. Variables with defaults are filled in. Commit the generated file — it stays in sync because it's derived from the same schema.

`ctroenv docs` — Auto-Generate Documentation

npx ctroenv docs

Produces ENVIRONMENT.md with type, required status, default, and description for every variable. JSON output (--format json) also available for custom tooling.

Putting It Together

name: Validate Environment
on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        package: [api, worker]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run build -w packages/shared

      - name: Validate env vars
        run: npx ctroenv validate --source .env
        working-directory: packages/${{ matrix.package }}

      - name: Check env file consistency
        run: npx ctroenv check
        working-directory: packages/${{ matrix.package }}

      - name: Verify .env.example is up to date
        run: |
          npx ctroenv generate && git diff --exit-code .env.example
        working-directory: packages/${{ matrix.package }}

The last step is the most useful: regenerate .env.example and fail if it differs from what's committed. If the PR author forgot to commit the updated example, the pipeline catches it.

The Config File

// ctroenv.config.ts
import { defineConfig } from "@ctroenv/cli"

export default defineConfig({
  schema: "./src/env.ts",
  sources: { default: ".env" },
  output: { example: ".env.example", docs: "ENVIRONMENT.md" },
  secrets: { mask: ["JWT_SECRET", "DATABASE_URL"], maskWith: "****" },
})

With this in place, npx ctroenv validate (no flags) reads the config, discovers the schema, and applies settings automatically.

What You Get

Single source of truth for shared vars. Change DATABASE_URL validation in one place, every service gets the update.
Per-service autonomy. The API can add CORS_ORIGIN without the worker knowing.
Docs that stay fresh. The schema that validates at startup also generates .env.example and ENVIRONMENT.md.

Final article: Building Your Own CtroEnv Validators — how createValidator() and applyChain() work, and how to build custom validators for semver strings, IP addresses, and AWS ARNs.

Resources: Docs · GitHub · CLI reference

Define Once, Trust Everywhere — CtroEnv Deep Dive

Odejobi Abiola Samuel — Wed, 17 Jun 2026 17:38:30 +0000

The core API is just four validator factories. Here's how they work and when to use each one.

The Four Validators

`string()` — Text Values

The most common one. Accepts any string input with refinements for format validation:

import { string } from "@ctroenv/core"

const v = string()
  .url()                    // Must be a valid URL
  .email()                  // Must match email format
  .port()                   // Must be a port number (1-65535)
  .min(8)                   // Minimum length
  .max(256)                 // Maximum length
  .regex(/^[a-z]+$/, "Must be lowercase letters only")

Each refinement returns a new StringValidator, so they chain in any order. Fail any refinement and you get an invalid_value error with a message like "Invalid URL" or "Must be at least 8 characters".

`number()` — Numeric Values

Accepts numbers or numeric strings. Coerces "3000" to 3000:

import { number } from "@ctroenv/core"

const v = number()
  .int()                    // Must be an integer
  .positive()               // Must be > 0
  .port()                   // Must be between 1-65535
  .min(1)                   // Minimum value
  .max(100)                 // Maximum value

number() calls Number(input) on strings. It rejects empty strings and anything producing NaN. "3.14" parses fine but fails .int().

`boolean()` — True/False Values

Accepts booleans directly, coerces strings and numbers:

import { boolean } from "@ctroenv/core"

const v = boolean()
// Accepts: true, false
// Coerces: "true" -> true, "false" -> false, "1" -> true, "0" -> false
// Coerces: 1 -> true, 0 -> false
// Rejects: everything else

Useful for feature flags:

# .env
ENABLE_METRICS=true
SHOW_BETA_FEATURES=0

const env = defineEnv({
  ENABLE_METRICS: boolean().default(false),
  SHOW_BETA_FEATURES: boolean().default(false),
})
// env.ENABLE_METRICS === true
// env.SHOW_BETA_FEATURES === false

`pick()` — Enum Values

Restricts to a set of allowed strings. The type is inferred as a union of literals:

import { pick } from "@ctroenv/core"

const env = defineEnv({
  NODE_ENV: pick(["development", "staging", "production"] as const).default("development"),
  LOG_LEVEL: pick(["debug", "info", "warn", "error"] as const).default("info"),
})

env.NODE_ENV // "development" | "staging" | "production"
env.LOG_LEVEL // "debug" | "info" | "warn" | "error"

Typo "production" (missing the 'c')? The error includes a suggestion:

NODE_ENV  Did you mean 'production'?

The as const assertion is critical — it keeps the literal types instead of widening to string.

Chainable Methods

Available on every validator, including custom ones built with createValidator().

`.default(value)` — Fallback When Not Set

const v = number().default(3000)
// If PORT is not set, env.PORT === 3000

The inferred type is always the value type, never T | undefined:

const env = defineEnv({ PORT: number().port().default(3000) })
env.PORT // number — always present

`.optional()` — Allow Undefined

const v = string().url().optional()

const env = defineEnv({
  SENTRY_DSN: string().url().optional().describe("Sentry error tracking DSN"),
})

env.SENTRY_DSN // string | undefined

`.describe(text)` — Documentation Metadata

Attaches a description for error messages and auto-generated docs:

string().url().describe("PostgreSQL connection URL")

// Missing required environment variable: DATABASE_URL — PostgreSQL connection URL

Descriptions also appear in ctroenv docs output and .env.example comments.

`.secret()` — Protect Sensitive Values

Flags a variable as sensitive. Values are masked (********) in CLI output and commented out in .env.example. The runtime value is still accessible normally.

string().min(32).secret().describe("JWT signing secret")

Order matters: .min() must come before .secret(). The type-specific methods (min, max, url, email, port, regex) live on StringValidator and NumberValidator. Chainable methods (secret, optional, default, describe, validate) return Validator<T> & ChainableMethods<T>, which doesn't include the type-specific refinements.

`.validate(fn)` — Custom Inline Validation

For one-off rules that don't need a full custom validator:

const env = defineEnv({
  API_KEY: string().validate((value) => {
    if (!value.startsWith("sk_")) return "Must start with 'sk_'"
    if (value.length < 40) return "Must be at least 40 characters"
    return undefined // pass
  }),
})

The function receives the parsed value and a context object. Return undefined for pass, or a string error message for failure.

Standalone Refinements

Each refinement on StringValidator and NumberValidator is also available as a standalone function:

import { string, number, url, port, min, max, email, regex, integer } from "@ctroenv/core"

// These are equivalent:
string().url()
url()(string())

string().min(8)
min(8)(string())

number().int()
integer()(number())

number().port()
port()(number())

Useful for composing refinements from different validator types or building reusable validator factories.

The Error System

When defineEnv() encounters failures, it collects every error and throws a single CtroEnvError. Fail fast, but tell the developer everything wrong at once.

How Errors Are Structured

class ValidationError {
  key: string           // "DATABASE_URL"
  message: string       // "Invalid URL"
  code: ErrorCode       // "missing_required" | "type_mismatch" | "invalid_value" | ...
  value: unknown        // The original (invalid) value
  suggestion?: string   // "Did you mean 'production'?"
}

Error Codes

Code	When
`missing_required`	Var not set and no default
`type_mismatch`	Wrong type (string vs number, etc.)
`invalid_value`	Failed a refinement (.url(), .min(), etc.)
`validation_failed`	Custom .validate() returned an error
`coercion_failed`	Could not coerce (string "foo" to number)

Formatted Output

formatErrors() produces grouped, colored terminal output:

 ● Missing required (2)

   DATABASE_URL  Add this variable to your .env file or set it in the environment.
   JWT_SECRET    Required — no default

 ✗ Invalid (1)

   CORS_ORIGIN
   Invalid URL

It detects NO_COLOR, CI, and TERM=dumb — in CI, colors are stripped automatically.

Programmatic Error Handling

import { CtroEnvError } from "@ctroenv/core"

try {
  const env = defineEnv(schema)
} catch (e) {
  if (e instanceof CtroEnvError) {
    for (const err of e.errors) {
      console.error(`${err.key}: ${err.message}`)
      if (err.suggestion) console.error(`  -> ${err.suggestion}`)
    }
  }
}

Framework Adapters

Node.js — `@ctroenv/node`

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

// Just process.env
const env = defineEnv(schema, { source: nodeSource() })

// Load .env files with priority
const env = defineEnv(schema, { source: loadEnv() })

loadEnv() reads .env -> .env.{NODE_ENV} -> .env.local, each overriding the previous.

Vite — `@ctroenv/vite`

Two integration points — a runtime source and a build plugin:

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

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

// src/main.ts
import { defineEnv } from "@ctroenv/core"
import { viteSource } from "@ctroenv/vite"
import { schema } from "./schema"

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

With failOnError: true, vite build fails immediately if any variable is missing or invalid.

Next.js — `@ctroenv/nextjs`

Next.js has a server/client split problem. Server code can access all env vars, but client code can only access NEXT_PUBLIC_* variables. CtroEnv handles this with a two-part schema:

import { defineEnv } from "@ctroenv/nextjs"

export const env = defineEnv({
  server: {
    DATABASE_URL: string().url(),
    JWT_SECRET: string().secret().min(32),
  },
  client: {
    NEXT_PUBLIC_API_URL: string().url(),
    NEXT_PUBLIC_APP_NAME: string().default("My App"),
  },
})

On the server, both schemas validate. On the client, only client validates. Accessing a server-only key from client code throws:

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

Catches the most common Next.js security mistake without requiring separate env files.

The EnvSource Abstraction

Every adapter implements this interface:

interface EnvSource {
  get(key: string): string | undefined
}

Source	What it reads
`detectSource()` (default)	`process.env` -> `import.meta.env`
`nodeSource()`	`process.env`
`loadEnv()`	`.env` files on disk
`viteSource()`	`import.meta.env`
Next.js `defineEnv()`	`process.env`

Pass any object matching this interface to defineEnv():

const env = defineEnv(schema, {
  source: {
    get(key) {
      if (key === "DATABASE_URL") return "postgres://localhost:5432/db"
      if (key === "PORT") return "4000"
      return undefined
    },
  },
})

Or use objectSource() for flat objects:

import { objectSource } from "@ctroenv/core"

const source = objectSource({
  DATABASE_URL: "postgres://localhost:5432/db",
  PORT: "4000",
})

What `defineEnv()` Returns

A deeply frozen object. Every property is read-only at runtime:

const env = defineEnv({ PORT: number().port().default(3000) })
env.PORT = 4000 // TypeError in strict mode

Recursive freeze applies to nested objects inside validated values. Prevents accidental mutation of what should be immutable config.

Full API Surface

Export	Kind	Package
`defineEnv`	Function	`@ctroenv/core`
`string`, `number`, `boolean`, `pick`	Factories	`@ctroenv/core`
`createValidator`, `applyChain`	Factories	`@ctroenv/core`
`detectSource`, `objectSource`	Functions	`@ctroenv/core`
`url`, `email`, `port`, `min`, `max`, `regex`, `integer`	Refinements	`@ctroenv/core`
`CtroEnvError`, `ValidationError`, `formatErrors`	Errors	`@ctroenv/core`
`nodeSource`, `loadEnv`	Functions	`@ctroenv/node`
`viteSource`, `ctroenvPlugin`	Function + Plugin	`@ctroenv/vite`
`defineEnv`, `withCtroEnv`	Functions	`@ctroenv/nextjs`

Up next: Monorepo Environment Management at Scale — sharing schemas across packages, extending base configs, running validation in CI.

Resources: Docs · @ctroenv/core on npm · GitHub

Stop Using process.env Directly — Here's Why

Odejobi Abiola Samuel — Wed, 17 Jun 2026 17:35:47 +0000

Last month I pushed a new service to staging. Forgot to add REDIS_URL to the env file. The server started fine — no crash, no error — but the first request that tried to hit the cache hung forever. Took me 20 minutes and a strace to figure out the connection was silently failing.

I've done this enough times now to recognize the pattern: environment variables in Node.js are just string | undefined. TypeScript can't help you. Validation is your job. Most teams do it wrong, or don't do it at all.

The Problem with `process.env`

const dbUrl = process.env.DATABASE_URL
//    ^? string | undefined — TypeScript can't help you here
const port = process.env.PORT
//    ^? string | undefined — also a string, not a number

Three things go wrong here:

No guarantee the variable exists. It could be undefined at any time, and you won't know until runtime.
No type information. PORT is a number semantically, but it's a string at runtime. Every consumer has to parse it themselves.
No documentation. What format should DATABASE_URL be? What's the default for PORT? Who knows — go find the README, which is probably outdated.

Three Common Failure Patterns

1. Missing Required Vars

// src/db.ts
const pool = new Pool({
  connectionString: process.env.DATABASE_URL, // undefined — oops
})
// Error: connect ECONNREFUSED — good luck debugging that

No error at import time. No error at server start. The error surfaces the first time someone hits a database endpoint.

2. Wrong Format, Cryptic Errors

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

// src/db.ts
const url = new URL(process.env.DATABASE_URL) // TypeError: Invalid URL

Or worse — silent data corruption:

// .env
MAX_CONNECTIONS=not-a-number

// src/config.ts
const max = parseInt(process.env.MAX_CONNECTIONS ?? "10", 10)
//    ^? NaN — your connection pool silently uses NaN as max

3. Type Confusion

// .env
PORT=3000

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

Every parseInt, Number(), === "true", or as string is validation logic you're scattering across your codebase. Most teams don't even do that.

The Manual Approach

I've written this function before:

// src/env.ts
function getEnv(): Env {
  const databaseUrl = process.env.DATABASE_URL
  if (!databaseUrl) 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}`)
  }

  const jwtSecret = process.env.JWT_SECRET
  if (!jwtSecret) throw new Error("JWT_SECRET is required")
  if (jwtSecret.length < 32) throw new Error("JWT_SECRET must be at least 32 chars")

  return { databaseUrl, port, nodeEnv, jwtSecret } as const
}

export const env = getEnv()

It works. But it's repetitive, scattered, undocumented, not CI-friendly, and TypeScript can't infer literal types from it.

Schema-Based Validation

What if you could write this instead:

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"),
  JWT_SECRET: string().secret().min(32).describe("JWT signing secret"),
})

And get all of this automatically:

TypeScript infers everything — env.PORT is number, env.NODE_ENV is "development" | "production" | "test"
Validation at definition time — if DATABASE_URL is missing or invalid, it throws immediately
Defaults — PORT defaults to 3000 if not set
Secrets marked — JWT_SECRET is flagged, won't leak into docs or logs
Descriptions — each variable carries its docs alongside the schema

How It Works

defineEnv() reads from your source (defaults to process.env), runs each value through its validator chain, and collects errors. If any exist, it throws CtroEnvError with every error grouped and formatted:

 ● Missing required (1)

   DATABASE_URL  Add this variable to your .env file or set it in the environment.

 ✗ Invalid (1)

   CORS_ORIGIN
   Invalid URL

No hunting through logs. You know exactly what's wrong and what to fix.

Validators at a Glance

Factory	Creates	Coercion
`string()`	A string validator	None
`number()`	A number validator	Coerces `"3000"` -> `3000`, rejects `NaN`
`boolean()`	A boolean validator	Coerces `"true"`/`"1"` -> `true`, `"false"`/`"0"` -> `false`
`pick([...])`	A union of allowed string values	Fuzzy suggestion on typo

String refinements: .url(), .email(), .port(), .min(n), .max(n), .regex(p)
Number refinements: .int(), .positive(), .port(), .min(n), .max(n)
Chainable (all validators): .default(v), .optional(), .describe(t), .secret(), .validate(fn)

Putting It Together

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

const env = defineEnv({
  PORT: number().port().default(3000),
  HOST: string().default("0.0.0.0"),
  DATABASE_URL: string().url().describe("PostgreSQL connection URL"),
  JWT_SECRET: string().secret().min(32).describe("JWT signing secret"),
  CORS_ORIGIN: string().url().describe("Allowed CORS origin"),
  NODE_ENV: pick(["development", "production", "test"] as const).default("development"),
  LOG_LEVEL: pick(["debug", "info", "warn", "error"] as const).default("info"),
  REDIS_URL: string().url().optional().describe("Redis connection URL"),
}, { source: loadEnv() })

export { env }

// src/index.ts
import express from "express"
import { env } from "./env"

const app = express()

app.get("/health", (_req, res) => {
  res.json({ status: "ok", uptime: process.uptime(), nodeEnv: env.NODE_ENV, port: env.PORT })
})

app.listen(env.PORT, env.HOST, () => {
  console.log(`Server running on http://${env.HOST}:${env.PORT}`)
})

If any env var is missing or invalid, the app fails at import time — not the first time someone hits a route.

Beyond Validation

Once your schema exists, the CLI tools layer on:

npx ctroenv generate — creates .env.example from your schema
npx ctroenv validate — fails CI if env drifts from schema
npx ctroenv docs — generates ENVIRONMENT.md
Secrets marked with .secret() are masked in output and commented out in .env.example

Approach	Type safety	Error clarity	Auto-docs	CI support	Lines per var
Raw `process.env`	None	None	No	No	1
Manual validation	Partial	Depends	No	No	5-10
CtroEnv	Full	Grouped	Yes	Yes	1

Try It

npm install @ctroenv/core

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

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

Resources: Docs · GitHub · npm

Next: Define Once, Trust Everywhere — CtroEnv Deep Dive

Why I Built Ctrovalidate: Rethinking Form Validation in JavaScript

Odejobi Abiola Samuel — Wed, 04 Feb 2026 07:52:20 +0000

🤔 Form Validation Is Everywhere… Yet Still Painful

Every web app has forms.
Every form needs validation.

Yet somehow, validation logic still ends up:

Scattered across files
Hard to read later
Tightly coupled to frameworks
Or bloated with unnecessary abstractions

After dealing with this repeatedly, I decided to build a small solution for myself — and that became Ctrovalidate.

🛠️ The Idea Behind Ctrovalidate

Ctrovalidate was built around a few simple principles:

Rules should read like rules
Validation should be predictable
Errors should be accessible by default
The library should stay out of your way

No magic. No heavy configuration. Just clear validation logic.

✨ What Ctrovalidate Tries to Do Well

📦 Lightweight and framework-agnostic
📖 Human-readable validation rules
♿ Accessibility-conscious error handling
🔌 Easy to plug into existing projects
🧠 Simple mental model (great for learning & teaching)

It works with vanilla JavaScript and fits nicely into modern frontend setups.

📚 Docs, Examples & Demo

If you want to see how it works in practice:

👉 Documentation & Demo

https://ctrotech-tutor.github.io/ctrovalidate/

⭐ Open Source on GitHub

The project is fully open-source and still evolving:

👉 GitHub Repository

https://github.com/ctrotech-tutor/ctrovalidate

If you like the idea:

⭐ Star the repo
👀 Follow for updates
🧪 Try it in a real project

🙏 Looking for Feedback

This project is still growing, and feedback matters a lot at this stage.

I’d especially love thoughts on:

API design
Missing validation rules
DX improvements
Accessibility edge cases

If you’ve ever built forms (which… we all have 😄), your input would be valuable.

Thanks for reading, and happy coding 🚀

Introducing Ctrovalidate – Lightweight JavaScript Form Validation Library By Ctrotech

Odejobi Abiola Samuel — Tue, 03 Feb 2026 14:06:02 +0000

🚀 Introducing Ctrovalidate

Form validation is something every web developer deals with — yet it often becomes repetitive, messy, or overly complex.

So I built Ctrovalidate, a lightweight, open-source JavaScript library designed to make form validation clean, readable, and accessible.

✨ Why Ctrovalidate?

Ctrovalidate focuses on clarity over complexity.

What it offers:

✅ Simple and readable validation rules
♿ Accessibility-friendly error handling
🧩 Framework-agnostic (works with vanilla JS, React, etc.)
🪶 Lightweight and easy to integrate
🛠️ Predictable validation flow (no hidden magic)

If you’ve ever felt that form validation libraries were too heavy or too opinionated, this might be useful for you.

📖 Documentation & Live Demo

You can explore the docs, API, and see live validation examples here:

👉 Docs & Demo

https://ctrotech-tutor.github.io/ctrovalidate/

⭐ GitHub Repository

The project is fully open-source:

👉 GitHub Repo

https://github.com/ctrotech-tutor/ctrovalidate

If you find it helpful:

⭐ Star the repository
👀 Follow the project for updates
🧪 Try it in a real project

🤝 Feedback Welcome

Ctrovalidate is still growing, and I’d really appreciate feedback from the DEV community:

API design suggestions
Feature requests
Validation edge cases you’ve encountered
Improvements around accessibility or DX

If you’ve built or struggled with form validation before, I’d love to hear your thoughts.

Thanks for checking it out — happy building 🚀

DEV Community: Odejobi Abiola Samuel

Secrets at Rest, Schemas at Scale — What's New in CtroEnv v1.1.0

Runtime Secret Masking

Why a Proxy?

Error Messages Are Safe Too

Schema Composition for Monorepos

Merge Semantics

Real Example

AGENTS.md

What Else Changed

Building Your Own CtroEnv Validators

How a Validator Works

Building a Custom Validator

Adding Chainable Methods with applyChain

Adding Refinement Methods

Writing a Refinement Function

A Complete Example: IP Address Validator

Error Factories

Publishing Custom Validators

Monorepo Environment Management at Scale

The Pattern: Define Once, Extend Per-Service

1. Shared Schema Package

2. Extend in Each Service

Running Validation in CI

ctroenv validate — Fail on Invalid Values

ctroenv check — Detect Drift

ctroenv generate — Keep .env.example in Sync

ctroenv docs — Auto-Generate Documentation

Putting It Together

The Config File

What You Get

Define Once, Trust Everywhere — CtroEnv Deep Dive

The Four Validators

string() — Text Values

number() — Numeric Values

boolean() — True/False Values

pick() — Enum Values

Chainable Methods

.default(value) — Fallback When Not Set

.optional() — Allow Undefined

.describe(text) — Documentation Metadata

.secret() — Protect Sensitive Values

.validate(fn) — Custom Inline Validation

Standalone Refinements

The Error System

How Errors Are Structured

Error Codes

Formatted Output

Programmatic Error Handling

Framework Adapters

Node.js — @ctroenv/node

Vite — @ctroenv/vite

Next.js — @ctroenv/nextjs

The EnvSource Abstraction

What defineEnv() Returns

Full API Surface

Stop Using process.env Directly — Here's Why

The Problem with process.env

Three Common Failure Patterns

1. Missing Required Vars

2. Wrong Format, Cryptic Errors

3. Type Confusion

The Manual Approach

Schema-Based Validation

How It Works

Validators at a Glance

Putting It Together

Beyond Validation

Try It

Why I Built Ctrovalidate: Rethinking Form Validation in JavaScript

🤔 Form Validation Is Everywhere… Yet Still Painful

🛠️ The Idea Behind Ctrovalidate

✨ What Ctrovalidate Tries to Do Well

📚 Docs, Examples & Demo

⭐ Open Source on GitHub

🙏 Looking for Feedback

Introducing Ctrovalidate – Lightweight JavaScript Form Validation Library By Ctrotech

🚀 Introducing Ctrovalidate

✨ Why Ctrovalidate?

What it offers:

Adding Chainable Methods with `applyChain`

`ctroenv validate` — Fail on Invalid Values

`ctroenv check` — Detect Drift

`ctroenv generate` — Keep `.env.example` in Sync

`ctroenv docs` — Auto-Generate Documentation

`string()` — Text Values

`number()` — Numeric Values

`boolean()` — True/False Values

`pick()` — Enum Values

`.default(value)` — Fallback When Not Set

`.optional()` — Allow Undefined

`.describe(text)` — Documentation Metadata

`.secret()` — Protect Sensitive Values

`.validate(fn)` — Custom Inline Validation

Node.js — `@ctroenv/node`

Vite — `@ctroenv/vite`

Next.js — `@ctroenv/nextjs`

What `defineEnv()` Returns

The Problem with `process.env`