Is incremental migration to zod 4 possible?

[ValentinGurkov]

Hello,

I am wondering whether we can do an incremental migration to zod 4, since we have a ton of schemas across our microservices.
Judging by the breaking changes, I imagine not, but I'd still like to ask.

Thanks,
Valentin

[xabierlameiro]

Great question! Yes, incremental migration to Zod v4 is absolutely possible and actually recommended, especially for microservices architectures with many schemas.

Migration Strategy

Zod v4 is specifically designed to support incremental migration through its subpath versioning strategy:

1. Side-by-Side Installation

Zod v4 is published alongside v3 in the same package:

npm upgrade zod@^3.25.0

After upgrading, you can use both versions simultaneously:

// Existing v3 code continues to work
import { z } from "zod"; // or "zod/v3"

// New v4 code
import { z } from "zod/v4";

2. No Breaking Changes to v3

Importantly, there were no code changes between [email protected] and [email protected] - only the addition of v4 subpaths. Your existing v3 code continues to work exactly as before.

3. Microservice-by-Microservice Migration

You can migrate each microservice independently:

// Service A (still on v3)
import { z } from "zod/v3";
const userSchema = z.object({ name: z.string() });

// Service B (migrated to v4)
import { z } from "zod/v4";
const productSchema = z.object({ name: z.string() });

4. File-by-File Migration Within Services

Even within a single codebase, you can migrate file by file:

// legacy-schemas.ts (v3)
import { z } from "zod/v3";
export const legacySchema = z.string();

// new-schemas.ts (v4)
import { z } from "zod/v4";
export const newSchema = z.string();

// main.ts (mixed usage)
import { legacySchema } from "./legacy-schemas";
import { newSchema } from "./new-schemas";

Migration Timeline

1. Phase 1: Install zod@^3.25.0 - no immediate changes needed
2. Phase 2: Gradually migrate new code to use "zod/v4"
3. Phase 3: Update existing schemas when convenient (not urgent)
4. Phase 4: Eventually move to [email protected] when the ecosystem is ready

Library Compatibility

Most ecosystem libraries can support both v3 and v4 simultaneously without breaking changes. Library authors should:

• Bump peer dependency to ^3.25.0
• Test against both "zod/v3" and "zod/v4" imports
• Support both APIs where possible

Bundle Size Benefits

One key advantage: you can start using "zod/v4-mini" for new code where bundle size matters most, while keeping existing v3 code unchanged.

Breaking Changes to Consider

While migration is incremental, be aware of these key breaking changes when you do migrate specific schemas:

• Error object structure changes
• Some deprecated APIs removed (.deepPartial(), .nonstrict())
• z.function() API changes
• String format methods moved to top-level (z.email() instead of z.string().email())

See the Migration Guide for the complete list.

Recommendation

Start with new features and gradually migrate existing code. The side-by-side approach means there's no pressure to migrate everything at once, making this perfect for large codebases and microservice architectures.

The Zod team specifically designed this versioning strategy to make migration as smooth as possible for exactly your use case!