Why Runtime Validation Is the Missing Piece in TypeScript Projects
TypeScript gives you type safety at compile time — but the moment data crosses a network boundary, all bets are off. An API response, a form submission, a query parameter: none of these are typed at runtime. TypeScript simply trusts whatever shape you declared. When reality doesn’t match that declaration, you get silent bugs that only surface in production.
I’ve been burned by this more times than I care to admit. In my real-world experience, this is one of the essential skills to master — validating data at the edge of your application, where the untrusted world meets your typed TypeScript code. That’s exactly the gap Zod fills.
Zod is a TypeScript-first schema declaration and validation library. You define a schema once, and Zod gives you two things: runtime validation (reject bad data immediately) and TypeScript type inference (no duplicate type declarations). The two stay in sync automatically, which eliminates an entire category of bugs.
Installation
Zod works in any TypeScript project — Node.js backends, React frontends, or shared monorepo packages.
npm install zod
# or
pnpm add zod
# or
yarn add zodFor React Hook Form integration, you also need the Zod resolver:
npm install react-hook-form @hookform/resolvers zodThat’s the entire dependency surface. Zod has zero external dependencies and works in all modern environments including Deno and Bun.
Verify your TypeScript version is 4.5 or higher — Zod relies on template literal types and newer inference features:
npx tsc --versionConfiguration: Building Your First Schemas
Basic Schema Definition and Type Inference
The core concept is simple: define a schema using Zod’s primitives, then extract the TypeScript type from it using z.infer.
import { z } from 'zod';
// Define schema once
const UserSchema = z.object({
id: z.number().int().positive(),
email: z.string().email(),
username: z.string().min(3).max(20),
role: z.enum(['admin', 'editor', 'viewer']),
createdAt: z.string().datetime().optional(),
});
// Extract TypeScript type — no duplication
type User = z.infer<typeof UserSchema>;
// Now User is equivalent to:
// {
// id: number;
// email: string;
// username: string;
// role: 'admin' | 'editor' | 'viewer';
// createdAt?: string | undefined;
// }This is the key insight: you write the schema, TypeScript writes the type for you. When you update the schema, the type updates automatically. No more forgetting to update the interface when you add a field to the validation logic.
Runtime Parsing and Error Handling
Zod gives you two methods for validating data: parse() throws on failure, safeParse() returns a result object.
const rawData = {
id: 1,
email: '[email protected]',
username: 'john_doe',
role: 'admin',
};
// Option 1: parse — throws ZodError if invalid
try {
const user = UserSchema.parse(rawData);
console.log(user.email); // fully typed
} catch (err) {
console.error(err); // ZodError with detailed messages
}
// Option 2: safeParse — returns { success, data } or { success, error }
const result = UserSchema.safeParse(rawData);
if (result.success) {
console.log(result.data.role); // typed as 'admin' | 'editor' | 'viewer'
} else {
console.error(result.error.flatten());
// { fieldErrors: { email: ['Invalid email'] }, formErrors: [] }
}safeParse() is generally preferred in application code because it doesn’t interrupt execution flow — you handle the error case explicitly without try/catch noise.
Practical Patterns: Transformations, Defaults, and Nested Schemas
Schemas compose naturally, and Zod supports transforms to coerce or reshape data during parsing:
// Nested schemas
const AddressSchema = z.object({
street: z.string(),
city: z.string(),
country: z.string().length(2), // ISO country code
});
const ProfileSchema = z.object({
user: UserSchema,
address: AddressSchema.optional(),
tags: z.array(z.string()).default([]),
});
// Transforms: parse a date string into a Date object
const EventSchema = z.object({
name: z.string(),
startDate: z.string().transform((val) => new Date(val)),
attendeeCount: z.coerce.number(), // coerce string '42' to number 42
});
type Event = z.infer<typeof EventSchema>;
// startDate is Date (after transform), not string
// Refinements: custom validation logic
const PasswordSchema = z
.object({
password: z.string().min(8),
confirm: z.string(),
})
.refine((data) => data.password === data.confirm, {
message: 'Passwords do not match',
path: ['confirm'],
});Integrating Zod with React Hook Form
React Hook Form manages form state efficiently, but its built-in validation is separate from your TypeScript types. The @hookform/resolvers package bridges the gap — you pass a Zod schema as the resolver, and React Hook Form uses it for both validation and TypeScript type inference.
// components/RegistrationForm.tsx
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
const RegistrationSchema = z
.object({
email: z.string().email('Please enter a valid email'),
username: z
.string()
.min(3, 'Username must be at least 3 characters')
.max(20, 'Username cannot exceed 20 characters')
.regex(/^[a-z0-9_]+$/, 'Only lowercase letters, numbers, and underscores'),
password: z.string().min(8, 'Password must be at least 8 characters'),
confirmPassword: z.string(),
})
.refine((data) => data.password === data.confirmPassword, {
message: 'Passwords do not match',
path: ['confirmPassword'],
});
type RegistrationFormData = z.infer<typeof RegistrationSchema>;
export function RegistrationForm() {
const {
register,
handleSubmit,
formState: { errors, isSubmitting },
} = useForm<RegistrationFormData>({
resolver: zodResolver(RegistrationSchema),
});
const onSubmit = async (data: RegistrationFormData) => {
// data is fully typed and already validated
await fetch('/api/register', {
method: 'POST',
body: JSON.stringify(data),
});
};
return (
<form onSubmit={handleSubmit(onSubmit)}>
<div>
<input {...register('email')} placeholder="Email" />
{errors.email && <p>{errors.email.message}</p>}
</div>
<div>
<input {...register('username')} placeholder="Username" />
{errors.username && <p>{errors.username.message}</p>}
</div>
<div>
<input type="password" {...register('password')} placeholder="Password" />
{errors.password && <p>{errors.password.message}</p>}
</div>
<div>
<input
type="password"
{...register('confirmPassword')}
placeholder="Confirm Password"
/>
{errors.confirmPassword && <p>{errors.confirmPassword.message}</p>}
</div>
<button type="submit" disabled={isSubmitting}>
{isSubmitting ? 'Creating account...' : 'Register'}
</button>
</form>
);
}The beauty of this setup: the same RegistrationSchema can be imported on the API route to validate the incoming request body. One schema, validated on both client and server.
Sharing Schemas Between Frontend and Backend
This is where the full-stack benefit becomes obvious. Create a shared schemas file:
// shared/schemas.ts
import { z } from 'zod';
export const RegistrationSchema = z
.object({
email: z.string().email(),
username: z.string().min(3).max(20),
password: z.string().min(8),
confirmPassword: z.string(),
})
.refine((data) => data.password === data.confirmPassword, {
message: 'Passwords do not match',
path: ['confirmPassword'],
});
export type RegistrationFormData = z.infer<typeof RegistrationSchema>;// pages/api/register.ts (Next.js API route)
import { RegistrationSchema } from '@/shared/schemas';
export async function POST(request: Request) {
const body = await request.json();
const result = RegistrationSchema.safeParse(body);
if (!result.success) {
return Response.json(
{ errors: result.error.flatten().fieldErrors },
{ status: 400 }
);
}
// result.data is fully typed here
const { email, username, password } = result.data;
// ... create user
}Verification and Monitoring: Testing Your Schemas Hold Up
Unit Testing Schemas Directly
Schemas are pure functions — they’re straightforward to unit test without mocking anything:
// schemas.test.ts
import { RegistrationSchema } from './shared/schemas';
describe('RegistrationSchema', () => {
it('accepts valid registration data', () => {
const result = RegistrationSchema.safeParse({
email: '[email protected]',
username: 'john_doe',
password: 'secure123',
confirmPassword: 'secure123',
});
expect(result.success).toBe(true);
});
it('rejects mismatched passwords', () => {
const result = RegistrationSchema.safeParse({
email: '[email protected]',
username: 'john_doe',
password: 'secure123',
confirmPassword: 'different456',
});
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.flatten().fieldErrors.confirmPassword).toBeDefined();
}
});
it('rejects invalid email format', () => {
const result = RegistrationSchema.safeParse({
email: 'not-an-email',
username: 'john_doe',
password: 'secure123',
confirmPassword: 'secure123',
});
expect(result.success).toBe(false);
});
});Monitoring Validation Errors in Production
When validation fails in production, you want visibility. Wrap your API validation with logging:
const result = RegistrationSchema.safeParse(body);
if (!result.success) {
const errors = result.error.flatten();
// Log to your monitoring service (Sentry, Datadog, etc.)
console.warn('[Validation failed]', {
endpoint: '/api/register',
fieldErrors: errors.fieldErrors,
formErrors: errors.formErrors,
});
return Response.json({ errors: errors.fieldErrors }, { status: 400 });
}Frequent validation failures on a specific field often signal a frontend bug, a mobile client sending wrong data formats, or an API consumer that didn’t read your docs. Surface these early rather than hunting through logs after users complain.
Common Gotchas
- Optional vs nullable:
z.string().optional()allowsundefined;z.string().nullable()allowsnull. They’re different. Usez.string().nullish()for both. - Unknown keys: By default, Zod strips unknown keys during parsing. Call
.passthrough()to keep them or.strict()to throw on them. - Async refinements: Use
.refineAsync()andparseAsync()when your validation needs to hit a database (e.g., checking if an email is already taken). - Error messages: Custom messages go in the validator call:
z.string().min(3, 'Too short')— not in a separate config object.
