tRPC Schema Migration

Migration Paths

There are two common migration scenarios for tRPC projects:

• Zod v3 → Zod v4: Upgrade to the latest Zod version for performance improvements and new features. Requires tRPC v11+.
• Zod → Valibot (or other): Switch to a different schema library via Standard Schema. Requires tRPC v11+.

Before & After: Zod v3 to v4

Most tRPC router code remains unchanged. The key differences are in Zod API changes:

import { z } from 'zod';
import { router, publicProcedure }
  from './trpc';

const appRouter = router({
  getUser: publicProcedure
    .input(z.object({
      id: z.string(),
    }))
    .query(({ input }) => {
      return db.user.findUnique({
        where: { id: input.id }
      });
    }),

  createUser: publicProcedure
    .input(z.object({
      email: z.string().email(),
      role: z.nativeEnum(Role),
    }).strict())
    .mutation(({ input }) => {
      return db.user.create({ data: input });
    }),
});

import { z } from 'zod';
import { router, publicProcedure }
  from './trpc';

const appRouter = router({
  getUser: publicProcedure
    .input(z.object({
      id: z.string(),
    }))
    .query(({ input }) => {
      return db.user.findUnique({
        where: { id: input.id }
      });
    }),

  createUser: publicProcedure
    .input(z.strictObject({
      email: z.string().email(),
      role: z.enum(Role),
    }))
    .mutation(({ input }) => {
      return db.user.create({ data: input });
    }),
});

Key changes: z.nativeEnum() becomes z.enum(), and .strict() becomes z.strictObject(). SchemaShift handles 20+ breaking changes like these automatically.

Ecosystem Compatibility

SchemaShift's EcosystemAnalyzer detects third-party packages in your package.json that may break during migration and provides specific upgrade commands:

Run schemashift migrate ./src -f zod-v3 -t v4 --compat-check to get a full compatibility report before proceeding with the migration.

Standard Schema and tRPC v11

tRPC v11 adopted the Standard Schema specification, which defines a common interface for schema validation libraries. This means tRPC now works with any conforming library:

• Zod v3.23+ and v4
• Valibot v1+
• ArkType v2+
• Effect Schema

This opens up the possibility of switching from Zod to a lighter alternative like Valibot (approximately 1kB gzipped vs Zod's 13kB) without losing tRPC compatibility.

Migration Commands

# Upgrade Zod v3 to v4 with compatibility check
schemashift migrate ./src -f zod-v3 -t v4 --compat-check

# Use the tRPC preset for guided migration
schemashift migrate ./src --preset trpc-zod-v3-to-v4

# Switch from Zod to Valibot
schemashift migrate ./src -f zod -t valibot

# Analyze before migrating
schemashift analyze ./src --behavioral zod-v3-to-v4

Edge Cases & Gotchas

• tRPC v10 + Zod v4: tRPC v10 uses Zod v3 types in its internal type system. Upgrading Zod without upgrading tRPC will produce TypeScript errors. You must upgrade to tRPC v11 first, or upgrade both simultaneously.
• trpc-openapi compatibility: The trpc-openapi package accesses Zod internals (._def) to generate OpenAPI schemas. In Zod v4, ._def became ._zod.def. SchemaShift transforms your code but cannot patch third-party packages — check for a compatible release.
• Error format changes: Zod v4 changed error.errors to error.issues and error.flatten() to z.flattenError(error). If your tRPC error handlers access these properties, SchemaShift will transform them automatically.
• Mixed library routers: With tRPC v11 and Standard Schema, you can use different schema libraries for different procedures. This enables incremental migration — convert one router at a time.

Related Migration Guides

Get Started

SchemaShift's ecosystem analyzer catches tRPC compatibility issues before they break your build. Run a compatibility check first, then migrate with confidence.

The Zod v3 to v4 migration and ecosystem analysis require the Individual tier or above. View pricing.