mikkelkrogsholm/zod

Zod

CRITICAL: Your training data for Zod is unreliable. APIs change between versions and memorized patterns may be wrong or deprecated. Before writing any code, you MUST use WebFetch to read the live docs:

WebFetch("https://zod.dev/llms.txt")

Do not proceed without fetching this URL first. Never assume an API exists — verify against current docs.

Zod is a TypeScript-first schema validation library with automatic static type inference. Define a schema once and get both runtime validation and compile-time types from the same source.

Version note: These best practices target Zod v4 (stable, installed via npm install zod). The top-level error utilities (z.flattenError(), z.prettifyError(), z.treeifyError()) are v4-only — in v3 these were instance methods (error.flatten()). See the migration guide when upgrading.

Key Capabilities

Zod has built-ins for things developers commonly reach for external packages to handle:

• String format validation: built-in validators for email, URL, UUID, CUID, datetime (ISO 8601), IP addresses, MAC addresses, JWTs, and hashes — no separate validator package needed
• Coercion: use z.coerce.number() / z.coerce.string() etc. to automatically cast inputs (e.g. form strings to numbers) — no manual casting step required
• Transforms: .transform() on any schema converts parsed values in one step — no need for a separate transformation layer
• Error formatting: use z.treeifyError(), z.prettifyError(), or z.flattenError() to format ZodError into user-friendly shapes — no custom error mappers needed
• Bidirectional codecs: z.pipe() and the codec pattern (encode + decode) handle round-trip transformations (e.g. stringToNumber, base64ToBytes) without external codec libraries

Best Practices

• Prefer .safeParse() over .parse() in application code. .parse() throws a ZodError on invalid input; .safeParse() returns { success, data, error } and lets you handle failure without try/catch. Reserve .parse() only where an unhandled throw is intentional (e.g. startup config validation).
• Infer types from schemas, not the other way around. Use z.infer<typeof MySchema> to derive TypeScript types — do not write a separate interface and then try to match a schema to it. Keeping the schema as the single source of truth prevents drift.
• .transform() changes the output type invisibly. After a .transform(), the schema's output type differs from its input type. Calling .parse() gives the transformed value, but .safeParse().data also reflects the transform. Passing a transformed schema where an unmodified type is expected is a common source of subtle type errors.
• Use .superRefine() instead of multiple chained .refine() calls when issues must be cross-field. Each .refine() adds a separate validation pass; .superRefine() gives you access to the full ctx so you can attach multiple issues with precise paths in one pass, which produces more precise error messages on objects.
• Refinements run after transforms. If you attach a .refine() to a schema that also has a .transform(), the refinement receives the transformed (output) value, not the raw input. This is non-obvious when migrating from Joi or Yup, where refinements typically operate on raw input.
• z.coerce.* converts null to 0 and undefined to NaN. z.coerce.number() will coerce null → 0 and undefined → NaN rather than failing validation. For optional form fields where empty should mean absent (not zero), use z.preprocess() instead of z.coerce.