Parse, Don't Assert
Take a typical case, made up for illustration. A shipping partner changed eta from a string to an object. The store's code had typed the response with as ShippingQuote, so the compiler believed eta was still a string, and the order page threw on eta.slice() for every customer. Nothing in the logs mentioned the partner.
TypeScript types vanish at runtime. Anything that comes from outside your process, such as API responses, request bodies, environment variables and form input, has to be checked before the types mean anything. Zod lets you write that check once and infer the type from it. Below is the core pattern and how to apply it to environment variables, API responses, forms and more.
- You're casting
res.json() as SomeApiTypeand hoping the API matches your type definition - Your environment variable parsing is a series of
process.env.X as stringassertions - You write a TypeScript interface AND a Yup schema AND keep them manually in sync
- A form submits with the right types in dev but blows up in production with different data
Zod eliminates the gap between “what TypeScript thinks this is” and “what it actually is at runtime” — especially at API boundaries.
Everything here uses Zod 4. If you're still on v3, most of this transfers directly — the parsing model didn't change — but the string-format validators did: z.string().email() and friends are now soft-deprecated in favour of top-level functions (z.email(), z.uuid(), z.url()), which are faster to type-check and tree-shake better since the checker doesn't have to thread the format through the whole ZodString chain. They still work if you have v3 code lying around; there's no urgency to rewrite it, but reach for the top-level form in anything new.
The Core Pattern
import { z } from 'zod';
// 1. Define the schema — Zod 4 style: top-level format validators
const UserSchema = z.object({
id: z.uuid(),
name: z.string().min(1).max(100),
email: z.email(),
role: z.enum(['admin', 'user', 'guest']),
createdAt: z.iso.datetime(),
});
// 2. Infer the TypeScript type — no duplication
type User = z.infer<typeof UserSchema>;
// 3. Parse at the boundary — throws ZodError if invalid
const user = UserSchema.parse(await res.json());
// user is fully typed as User — TS trusts it because Zod checked it
// 4. Safe parse — returns { success: true, data } | { success: false, error }
const result = UserSchema.safeParse(rawInput);
if (result.success) {
console.log(result.data.email); // typed
} else {
console.error(result.error.flatten()); // structured errors
}
flowchart LR
input["Raw Input
(unknown)"] --> schema["Zod Schema
.parse()"]
schema -->|valid| typed["Typed Value
User"]
schema -->|invalid| error["ZodError
.flatten()"]
style typed fill:#16a34a,color:#fff,stroke:#15803d
style error fill:#dc2626,color:#fff,stroke:#b91c1c
style schema fill:#0078D4,color:#fff,stroke:#005a9e
Environment Variables
Zod's most universally useful application: validated, typed env variables that fail at startup instead of randomly in production.
// env.ts — parse once at startup
import { z } from 'zod';
const EnvSchema = z.object({
DATABASE_URL: z.url(),
NEXTAUTH_SECRET: z.string().min(32),
NEXTAUTH_URL: z.url(),
REDIS_URL: z.string().optional(),
PORT: z.coerce.number().default(3000), // coerce converts "3000" string to number
NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
});
export const env = EnvSchema.parse(process.env);
// Throws at startup with a clear error if any required var is missing or malformed
// env.PORT is typed as number, not string | undefinedAPI Response Validation
import { z } from 'zod';
const PaginatedResponseSchema = <T extends z.ZodTypeAny>(itemSchema: T) =>
z.object({
items: z.array(itemSchema),
total: z.number().int().nonnegative(),
page: z.number().int().positive(),
pageSize: z.number().int().positive(),
});
const ArticleSchema = z.object({
id: z.uuid(),
title: z.string(),
publishedAt: z.iso.datetime().nullable(),
tags: z.array(z.string()),
});
// Reusable: PaginatedResponse<Article>
const ArticleListSchema = PaginatedResponseSchema(ArticleSchema);
type ArticleList = z.infer<typeof ArticleListSchema>;
async function fetchArticles(page: number): Promise<ArticleList> {
const res = await fetch(`/api/articles?page=${page}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
// Throws if the API returns unexpected shape
return ArticleListSchema.parse(await res.json());
}Form Validation with React Hook Form
import { z } from 'zod';
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
const SignUpSchema = z.object({
email: z.email('Invalid email address'),
password: z
.string()
.min(8, 'At least 8 characters')
.regex(/[A-Z]/, 'At least one uppercase letter')
.regex(/[0-9]/, 'At least one number'),
confirmPassword: z.string(),
}).refine(
(data) => data.password === data.confirmPassword,
{ message: 'Passwords do not match', path: ['confirmPassword'] }
);
type SignUpForm = z.infer<typeof SignUpSchema>;
function SignUpForm() {
const { register, handleSubmit, formState: { errors } } = useForm<SignUpForm>({
resolver: zodResolver(SignUpSchema),
});
return (
<form onSubmit={handleSubmit((data) => signUp(data))}>
<input {...register('email')} />
{errors.email && <p>{errors.email.message}</p>}
{/* ... */}
</form>
);
}Transformations and Preprocessing
// .transform() converts the parsed value to a different type
const DateStringSchema = z.iso.datetime().transform((s) => new Date(s));
type ParsedDate = z.infer<typeof DateStringSchema>; // Date — not string!
// .preprocess() runs before validation — useful for coercion
const FlexibleNumberSchema = z.preprocess(
(val) => (typeof val === 'string' ? Number(val) : val),
z.number()
);
// .pipe() chains schemas
const TrimmedEmailSchema = z.string().transform((s) => s.trim()).pipe(z.email());
// Practical: parse a query param that might be a string number
const PageSchema = z.coerce.number().int().positive().default(1);
// get() returns null when the key is missing, and null coerces to 0, which fails positive().
// Turn null into undefined so the default applies.
const page = PageSchema.parse(searchParams.get('page') ?? undefined); // "2" → 2, missing → 1Error Handling
import { z } from 'zod';
const result = UserSchema.safeParse(unknownData);
if (!result.success) {
// .flatten() — simple field → messages map
const flat = result.error.flatten();
// { fieldErrors: { name: ['Required'], email: ['Invalid email'] }, formErrors: [] }
// .format() — nested structure matching the schema shape
const formatted = result.error.format();
// Individual issues
result.error.issues.forEach((issue) => {
console.log(issue.path.join('.'), issue.message, issue.code);
});
}
// In a Next.js Server Action:
export async function createUser(formData: FormData) {
const result = UserSchema.safeParse(Object.fromEntries(formData));
if (!result.success) {
return { errors: result.error.flatten().fieldErrors };
}
// result.data is typed as User
await db.user.create({ data: result.data });
}Unknown Keys: Strip, Reject or Keep
By default z.object strips keys it does not know about. That is the right default for API responses: the partner adds a field, your code ignores it, nothing breaks. It is the wrong default in two places, and Zod gives you a constructor for each:
z.strictObjectrejects unknown keys. Use it for request bodies and config files, where an unknown key is almost always a typo (retryLimt) that would otherwise be silently ignored while the default applies.z.looseObjectkeeps unknown keys. Use it when you validate part of a payload and must pass the rest through untouched, such as a webhook you forward to another service.
When the Partner Changes Their Schema
Validation turns the eta incident from a crash on the order page into a failed parse at the integration boundary. That is better, but on its own it still means no shipping quotes until someone ships a fix. Three habits make a partner integration survive their changes:
- Log parse failures with context. Use
safeParse, and on failure log the partner name, the endpoint andz.prettifyError(result.error), then increment a metric. An alert on that metric tells you within minutes which partner changed what, instead of a support ticket a day later. - Accept both shapes during a migration. When you learn a field is changing, accept the old and new forms with a union and normalise to one internal type with
.transform, so the rest of the code never sees the difference. - Degrade instead of failing the page. If the quote cannot be parsed, show the order without an ETA and keep the failure in the logs. Validation decides what you trust; the product decides what to do without it.
const Eta = z.union([
z.iso.datetime(), // old: "2026-10-04T10:00:00Z"
z.object({ earliest: z.iso.datetime(), latest: z.iso.datetime() }), // new
]).transform((eta) => (typeof eta === 'string' ? { earliest: eta, latest: eta } : eta));One Schema for Client, Server and Docs
The schema is the most valuable artefact here, so put it where every consumer can import it: a shared package in a monorepo, imported by the API handler, the frontend form and the tests. For anything outside TypeScript, such as an OpenAPI document or another team’s service, z.toJSONSchema(schema) produces JSON Schema from the same definition. Generate it in the build rather than writing it by hand, and the documentation stays much closer to what the server enforces. Check the output, though: transforms and custom refinements have no direct JSON Schema equivalent, so some schemas need an override or a change, and a test on the generated contract catches the rest.
Pitfalls
Using .parse() in request handlers
parse() throws a ZodError — which becomes a 500 in most frameworks. Use safeParse() in request handlers and return 400 on validation failure. Reserve parse() for startup-time validation (env vars) where throwing is the correct behaviour.
Inferring after transform
z.infer<typeof Schema> gives you the output type after transforms. If you need the input type (what goes into parse()), use z.input<typeof Schema>.
Schema reuse vs recreation
Define schemas as module-level constants, not inside components or route handlers. Recreating schemas on every render is wasteful and breaks referential equality for memoisation.
Migrating from Zod 3: .string().email() still runs, it just isn't the model anymore
The chained form isn't removed — it's a thin wrapper around the same top-level check now, kept around so v3 codebases don't break on upgrade. The reason to actually go rewrite it isn't correctness, it's that Zod 4's parsing engine and TypeScript performance work were built around the top-level primitives; the chained form is the compatibility shim, not the fast path. New code should default to z.email()/z.uuid()/z.url()/z.iso.datetime() — treat the old chain as something you migrate opportunistically, not a fire drill.
Zod and LLM Output
Zod is now a common way to define structured output for models. Zod 4 can produce JSON Schema directly with z.toJSONSchema(), and tools such as the Vercel AI SDK accept schemas as they are. Remember that models may fill required fields with invented values, so allow null where data may be missing.