Skip to main content

Zod

What is Zod​

Zod is a TypeScript-first schema declaration and validation library. It is MIT licensed, currently at version 4.x, and has ~30M+ weekly npm downloads with 36k+ GitHub stars. It has zero dependencies and works across Node.js, browsers, Deno, Bun, and Cloudflare Workers. Bundle size is ~11 kB gzipped, with Zod Mini offering a ~2 kB core for bundle-sensitive contexts.

Why we recommend it​

  • TypeScript type inference — schemas automatically infer static types via z.infer<typeof schema>, eliminating the need to maintain types and validation logic separately.
  • Zero dependencies — nothing extra enters your dependency tree.
  • Composable API — schemas are chainable and composable with .extend(), .merge(), .pick(), .omit(), .partial(), and more.
  • Rich type support — strings, numbers, objects, arrays, unions, discriminated unions, recursive types, tuples, records, and custom refinements/transforms.
  • Structured errors — ZodError objects include path information, making it straightforward to map errors to form fields or API response shapes.
  • Broad ecosystem integration — first-class support in React Hook Form, tRPC, TanStack Router, Conform, and Next.js Server Actions.

Why over alternatives​

  • vs Yup — Yup's TypeScript inference was added retroactively and is less reliable. It coerces values by default — a frequent source of subtle bugs.
  • vs Joi — Joi offers no TypeScript type inference, has a large bundle (~150 kB), and is primarily designed for Node.js server environments.
  • vs io-ts — io-ts has a steep learning curve, requires the fp-ts library, and is less ergonomic for common validation tasks.
  • vs class-validator — Decorator-based validation requires classes and reflect-metadata, which conflicts with functional React patterns and tree-shaking.

When to use​

  • Form validation (paired with React Hook Form or Conform).
  • API response validation — verify that external data matches expected shapes at runtime.
  • Environment variable parsing — fail fast on startup if required config is missing.
  • tRPC input/output schemas.
  • Shared client/server contracts — define a schema once, use it for both runtime validation and TypeScript types.
  • Config file parsing.
  • LLM structured output — constrain model responses to typed schemas using Zod 4's built-in z.toJSONSchema() with OpenAI, Anthropic, and Google Gemini. See Structured Output with Zod for provider-specific patterns and the Vercel AI SDK Output.object() abstraction.

When NOT to use​

  • Performance-critical bulk data processing — if you're validating thousands of JSON objects per second (e.g., streaming pipelines), consider Ajv which compiles schemas to optimized code.
  • Projects not using TypeScript — Zod's primary value proposition is type inference. In plain JavaScript projects, the ergonomic advantage shrinks considerably.
  • JSON Schema as source of truth — if your validation schemas must be serializable JSON Schema (e.g., for OpenAPI specs), consider TypeBox or Ajv directly.
  • Extremely bundle-sensitive apps — if every kilobyte counts and you need minimal validation, consider Valibot which offers a tree-shakeable, function-based API.
tip

Zod pairs naturally with TanStack Query — validate API responses at the boundary before they enter your cache, catching contract drift early.

Resources​