Migration from envalid
If you're using envalid, migrating to CtroEnv gives you TypeScript-native inference and a modern chainable API.
Key Differences
| Feature | envalid | CtroEnv |
|---|---|---|
| API | Object-based (str(), num()) | Chainable methods (string().url()) |
| TypeScript inference | Manual type creation | Automatic inference |
| Error messages | Basic | Rich, grouped, with suggestions |
| CLI | None | Full CLI tooling |
| Framework adapters | None | Node, Vite, Next.js |
| Secret masking | Not supported | .secret() method |
Step-by-Step Migration
1. Install CtroEnv
npm uninstall envalid
npm install @ctroenv/core2. Replace imports and schema
// Before (envalid)
import { cleanEnv, str, num, url, makeValidator } from "envalid"
const env = cleanEnv(process.env, {
DATABASE_URL: url(),
PORT: num({ default: 3000 }),
NODE_ENV: str({ choices: ["dev", "prod"] }),
})
// After (CtroEnv)
import { defineEnv, string, number, pick } from "@ctroenv/core"
const env = defineEnv({
DATABASE_URL: string().url(),
PORT: number().port().default(3000),
NODE_ENV: pick(["dev", "prod"]),
})3. Update custom validators
// Before (envalid — makeValidator)
const hostname = makeValidator((input) => {
if (!/^[a-z0-9.-]+$/.test(input)) {
throw new Error("Invalid hostname")
}
return input
})
// After (CtroEnv — .validate())
const hostnameValidator = string().validate((value) => {
if (!/^[a-z0-9.-]+$/.test(value)) {
return "Invalid hostname"
}
})Key Mapping
| envalid | CtroEnv |
|---|---|
str() | string() |
num() | number() |
bool() | boolean() |
url() | string().url() |
email() | string().email() |
json() | Custom .validate() |
makeValidator() | .validate() |
{ default: v } | .default(v) |
{ choices: [...] } | pick([...]) |
cleanEnv() | defineEnv() |
What's Different
Type Inference
envalid requires separate type definitions. CtroEnv infers types automatically:
// envalid: must manually define types
type Env = {
PORT: number
DATABASE_URL: string
}
// CtroEnv: types are inferred automatically
const env = defineEnv({ ... })
// typeof env.PORT → number