Zod Framework Integrations

Fastify: Type-Provider Integration

The fastify-type-provider-zod package connects Zod schemas directly to Fastify's type inference system:

import Fastify from "fastify";
import { ZodTypeProvider, serializerCompiler, validatorCompiler } from "fastify-type-provider-zod";
import { z } from "zod";

const app = Fastify().withTypeProvider<ZodTypeProvider>();

// Required: attach Zod compilers
app.setValidatorCompiler(validatorCompiler);
app.setSerializerCompiler(serializerCompiler);

const CreateUserBody = z.strictObject({
  name: z.string().min(1),
  email: z.email(),
});

const UserResponse = z.object({
  id: z.string().uuid(),
  name: z.string(),
  email: z.email(),
});

app.post("/users", {
  schema: {
    body: CreateUserBody,
    response: { 201: UserResponse },
  },
}, async (req, reply) => {
  // req.body is fully typed as z.infer<typeof CreateUserBody>
  // Response schema prevents leaking fields not in UserResponse
  const user = await db.createUser(req.body);
  return reply.status(201).send(user);
});

Key benefits:

• Request body, query params, path params automatically validated and typed
• Response schema enforced — extra fields not in the schema are stripped from responses
• 400 errors returned automatically on validation failure — no manual error handling needed

Security note: Use z.strictObject() for request body schemas to prevent over-posting. The response schema can use z.object() (strip mode) since you're controlling what goes out.

Next.js: Server Actions

Use .safeParse() inside Server Actions — never .parse(). A thrown exception in a Server Action crashes the action instead of returning a validation error to the client:

// shared/schemas.ts — shared between client and server
export const CreatePostSchema = z.object({
  title: z.string().min(1).max(100),
  content: z.string().min(10),
});
export type CreatePostInput = z.infer<typeof CreatePostSchema>;

// app/actions/posts.ts
"use server";
import { CreatePostSchema } from "@/shared/schemas";

export async function createPost(formData: FormData) {
  const raw = {
    title: formData.get("title"),
    content: formData.get("content"),
  };

  const result = CreatePostSchema.safeParse(raw);
  if (!result.success) {
    return {
      success: false,
      errors: z.flattenError(result.error).fieldErrors,
    };
  }

  // result.data is fully typed
  await db.posts.create(result.data);
  return { success: true };
}

React Hook Form: zodResolver

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

// Form schemas often need coercion for HTML input types
const RegisterSchema = z.object({
  email: z.email(),
  age: z.coerce.number().int().min(13).max(120), // HTML inputs return strings
  birthdate: z.coerce.date(), // <input type="date"> returns string
  avatar: z.file().max(5 * 1024 * 1024).type("image/*"),
});
type RegisterForm = z.infer<typeof RegisterSchema>;

function RegisterForm() {
  const { register, handleSubmit, formState: { errors } } =
    useForm<RegisterForm>({ resolver: zodResolver(RegisterSchema) });

  return (
    <form onSubmit={handleSubmit(async (data) => { /* data is typed RegisterForm */ })}>
      <input {...register("email")} />
      {errors.email && <span>{errors.email.message}</span>}
    </form>
  );
}

Form schema vs API schema: Form schemas often differ from API schemas due to coercion needs (z.coerce.number(), z.coerce.date()). Share a base schema and layer coercions on top for the form layer rather than duplicating the entire schema.

Multi-step forms: Wrap with FormProvider and use useFormContext() in step components — avoid prop drilling the register/errors objects.

Monorepo: Shared Schema Package

The canonical architecture for full-stack type safety:

packages/
  schemas/          ← Shared Zod schemas
    package.json    ← "zod" as peerDependency (NOT dependency)
    src/
      user.ts
      post.ts
      index.ts      ← Re-export all schemas

apps/
  web/              ← Frontend (imports from @workspace/schemas)
  api/              ← Backend (imports from @workspace/schemas)

// packages/schemas/src/user.ts
import { z } from "zod"; // Resolved to the single workspace Zod instance

export const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.email(),
  role: z.enum(["admin", "user"]),
});
export type User = z.infer<typeof UserSchema>;

// apps/web/src/auth.tsx
import { UserSchema } from "@workspace/schemas"; // ✅ Same Zod instance
// NOT: import { z } from "zod" // ❌ May create a second instance

Force single Zod version at workspace root:

// package.json (workspace root)
{
  "pnpm": {
    "overrides": { "zod": "^4.0.0" }
  },
  // npm: "overrides": { "zod": "^4.0.0" }
  // yarn: "resolutions": { "zod": "^4.0.0" }
}

The "ID already exists in registry" Error

This error occurs in Zod 4.1.13+ when the same schema with .meta({ id }) is evaluated twice — either from duplicate Zod instances or from schema definitions inside dynamic/called functions:

// WRONG: Dynamic schema creation generates duplicate IDs
function buildSchema(fields: string[]) {
  return z.object({ name: z.string() }).meta({ id: "user-schema" }); // Re-registered on each call!
}

// CORRECT: Static, module-level schema with .meta() id
export const UserSchema = z.object({ name: z.string() }).meta({ id: "user-schema" });

Resolution steps:

1. Ensure "zod" is a peerDependency in shared packages (not dependency)
2. Add workspace-root version override to force single Zod instance
3. Move all .meta({ id }) assignments to module-level constants
4. Centralize all Zod imports through the shared package

Vercel AI SDK: zodSchema() Helper

When using Zod schemas with the Vercel AI SDK for structured output or tool definitions:

import { generateObject } from "ai";
import { zodSchema } from "ai/zod";
import { z } from "zod";

const RecipeSchema = z.object({
  name: z.string(),
  ingredients: z.array(z.object({ item: z.string(), amount: z.string() })),
  steps: z.array(z.string()),
});

const { object } = await generateObject({
  model: openai("gpt-4o"),
  schema: zodSchema(RecipeSchema),
  prompt: "Generate a recipe for chocolate cake",
});
// object is typed as z.infer<typeof RecipeSchema>

Additional Resources

• `references/fastify-integration.md` — Complete Fastify setup with query params, path params, response schemas, error handling
• `references/nextjs-integration.md` — Next.js App Router patterns, Server Actions, route handlers, middleware validation
• `references/rhf-integration.md` — React Hook Form: coercion patterns, file inputs, date fields, multi-step forms, create/edit form hooks
• `references/monorepo-guide.md` — Full monorepo architecture: peerDependencies, workspace overrides, centralized imports, tRPC integration