Zod

Overview

Zod is a TypeScript-first schema validation library with static type inference. Define a schema once; you get both runtime validation and a TypeScript type (via z.infer). Zero external dependencies; works in Node and browsers. Ideal for forms (e.g. with react-hook-form), API parsing, env vars, and any untrusted input.

Requirements: TypeScript 5.5+ recommended; enable strict in tsconfig.json.

Install: npm install zod

Quick start

import { z } from "zod";

const User = z.object({
  name: z.string(),
  age: z.number().optional(),
});

type User = z.infer<typeof User>;
// { name: string; age?: number }

const data = User.parse(input); // throws ZodError if invalid
const result = User.safeParse(input); // { success: true, data } | { success: false, error }

Primitives and common types

Optional: .optional() → T | undefined. Nullable: .nullable() → T | null. Nullish: .nullish() → T | null | undefined. Default: .default(value).

Objects

const Schema = z.object({
  name: z.string(),
  age: z.number().optional(),
  tags: z.array(z.string()).default([]),
});

type Schema = z.infer<typeof Schema>;

• .shape: Schema.shape.name (access field schema).
• .keyof(): Schema.keyof() → enum of keys.
• .extend({ ... }): Add or override keys.
• .pick({ name }) / .omit({ age }): Subset of keys.
• .partial() / .required({ name }): Optionalize or require.
• .strict(): No extra keys (default in z.object). z.strictObject / z.looseObject for behavior variants.
• .catchall(z.string()): Allow extra keys with a schema.
• Nested: z.object({ user: z.object({ name: z.string() }) }).
• Recursive: z.lazy(() => Category) for self-referential structures.

Arrays and tuples

• Arrays: z.array(z.string()), z.string().array().
• Tuples: z.tuple([z.string(), z.number()]) — fixed length and types.
• Non-empty: .min(1) or dedicated helpers if available.

Unions and intersections

• Union: z.union([z.string(), z.number()]) or z.string().or(z.number()).
• Discriminated union: Use a common key (e.g. type: "a") and z.discriminatedUnion("type", [z.object({ type: z.literal("a"), ... }), ...]).
• Intersection: z.intersection(A, B) or A.and(B).

Refinements and transform

• .refine(fn, message?): Custom validation; keep type unchanged.
• .superRefine: Multiple issues or async; push to ctx.
• .transform(fn): Change output type. Input and output can differ; use z.input<typeof schema> and z.output<typeof schema> (or z.infer for output).
• .pipe(otherSchema): Chain validation/transform (e.g. string → number via z.string().pipe(z.coerce.number())).

Parsing and errors

• .parse(input): Returns data or throws ZodError.
• .safeParse(input): Returns { success: true, data } or { success: false, error: ZodError }.
• ZodError: error.issues (array of { path, message, code }), error.format() for nested shape.
• Async: .parseAsync / .safeParseAsync for schemas with async refinements or transforms.

Type inference

• z.infer<typeof schema>: Output type (after transforms/defaults).
• z.input<typeof schema>: Input type (before transforms; useful when input ≠ output).
• z.output<typeof schema>: Same as z.infer for output type.

const S = z.string().transform((s) => s.length);
type In = z.input<typeof S>;  // string
type Out = z.output<typeof S>; // number

Integration: React Hook Form

Use @hookform/resolvers with zodResolver:

import { zodResolver } from "@hookform/resolvers/zod";
import { useForm } from "react-hook-form";
import { z } from "zod";

const formSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

type FormValues = z.infer<typeof formSchema>;

const form = useForm<FormValues>({
  resolver: zodResolver(formSchema),
  defaultValues: { email: "", password: "" },
});

Best practices

• Prefer strict schemas (no extra keys) for API boundaries; use .passthrough() only when you need to forward unknown keys.
• Use .default() for optional fields with a default value.
• For API/env parsing, use safeParse and handle errors; show user-friendly messages from error.issues.
• Use discriminated unions for variant payloads (e.g. events by type).
• Coerce only when safe: z.coerce.number(), z.coerce.boolean(), or custom .transform().

Common mistakes

• Forgetting strict: Keep TypeScript strict: true; Zod works best with it.
• Input vs output: After .transform(), use z.input<> / z.output<> if the type seen by callers differs.
• parse in hot path: Prefer validating once at boundaries (e.g. API handler, form submit) rather than on every render.
• Overly broad schema: Prefer specific types (e.g. .email(), .min()) instead of plain z.string() when the domain has rules.

Additional resources

• reference.md — Official Zod docs links, API sections (primitives, objects, strings, numbers, refinements, etc.), Zod Mini, ecosystem.
• Official: https://zod.dev — Introduction, API, basics, ecosystem.
• API (Zod 4): https://zod.dev/api — Full schema types and methods.
• LLMs / index: https://zod.dev/llms.txt — Structured doc for tools/agents.