Chapter 53: Zod Mini — Overview & When to Use It
Core Idea
Zod Mini is a functional, tree-shakable variant of Zod with identical functionality but a functions-over-methods API — bundlers can eliminate unused top-level functions but not unused method implementations, so Mini trades ergonomics for meaningfully smaller bundles, mainly relevant to bundle-size-sensitive frontend code.
Key Concepts
- Same package, different import:
import * as z from "zod/mini" (no separate install needed beyond zod@^4.0.0).
- Functional API shape: wrapping modifiers become functions (
z.nullable(z.optional(z.string())) instead of z.string().optional().nullable()), and checks attach via .check(...) with function-form checks (z.string().check(z.minLength(5), z.maxLength(10), z.trim())) instead of chained methods (.min(5).max(10).trim()).
- Why it's smaller: bundlers can tree-shake unused functions but generally can't remove unused methods on a class — Mini's API is built from functions specifically to make dead-code elimination effective.
- When it matters least: backend code (bundle size doesn't affect cold starts meaningfully at Zod's scale — measured around a ~0.6ms difference even in Lambda) and typical web users (round-trip latency dwarfs a few extra KB except on very slow connections).
- DX trade-off: Mini's API is more verbose and less discoverable via autocomplete than chained methods — even Zod's own author prefers the standard API when bundle size isn't a hard constraint.
Code Examples
// regular Zod
const mySchema = z.string().optional().nullable();
z.string().min(5).max(10).trim();
// Zod Mini — same behavior, functional shape
import * as z from "zod/mini";
const mySchemaMini = z.nullable(z.optional(z.string()));
z.string().check(z.minLength(5), z.maxLength(10), z.trim());
- What it demonstrates: the same schema expressed in both APIs, showing the functions-vs-methods difference directly.
Reference Tables
| Schema | Zod (gzip) | Zod Mini (gzip) | Reduction |
|---|
z.boolean() | 5.91kb | 2.12kb | ~64% |
3-field z.object({...}) | 13.1kb | 4.0kb | ~69% |
Key Takeaways
- Default to regular Zod; reach for Zod Mini only under genuinely strict frontend bundle-size constraints (e.g. targeting users on slow mobile networks).
- Bundle-size savings from Mini are essentially irrelevant on the backend — cold-start and runtime cost differences at Zod's scale are negligible.
- The DX cost (verbosity, weaker autocomplete) is real and should be weighed against the actual, measured bundle-size benefit for your specific use case — don't assume it matters without checking.
Connects To
- Zod Mini — API Reference: the concrete
.check() function list and remaining instance methods.
- For Library Authors — Peer Dependencies & Subpaths: writing library code that supports both Zod and Zod Mini simultaneously.