Versioning with subpaths ("zod/v4") to enable incremental migration
#4371
Comments
|
Implemented in #4364 |
"zod/v4", "zod/v4/core" (dropping @zod/core), "zod/v4-mini" (dropping @zod/mini)"zod/v4") to enable incremental migration
This was referenced May 16, 2025
Closed
This was referenced May 16, 2025
Closed
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
This is a writeup of a number of structural changes to the package, with the goal of making it easier for the ecosystem to migrate to Zod 4. TLDR:
zod@4.0.0on npm."zod/v4") alongsidezod@3.25.0). Despite this, Zod 4 is considered stable and production-ready."zod"). Projects can incrementally migrate as they see fit.@zod/corepackage is being dropped in favor of"zod/v4/core"@zod/minipackage is being dropped in favor of"zod/v4-mini"Sometime later:
zod@4.0.0on npm"zod") will switch over from exporting Zod 3 to Zod 4"zod/v4"subpath will continue to be available.Ecosystem libraries are encouraged to build against
"zod/v3"and"zod/v4"exclusively as these will remain stable/available across all future versions, including majors.A more detailed breakdown:
To give the ecosystem time to migrate, Zod 4 will initially be published alongside Zod 3. It will be consumable as a subpath import:
During this transition window:
"zod"package will continue to be published in the3.x.xversion range on npm. The/v4subpath will be added in thezod@3.25.0release."zod") as well as a new subpath ("zod/v3"). It will continue to receive bug fixes & stability improvements.More generally, the multi-package structure has been abandoned in favor of a "monopackage". The
@zod/coreand@zod/minipackages are being dropped in favor ofzod/v4/coreandzod/v4-minisubpaths, respectively.Why? Zod occupies a unique place in the ecosystem. Many libraries/frameworks in the ecosystem accept user-defined Zod schemas. This means their user-facing API is strongly coupled to Zod and its various classes/interfaces/utilities. For these libraries/frameworks, a breaking change to Zod necessarily causes a breaking change for their users. A Zod 3
ZodTypeis not assignable to a Zod 4ZodType.So why can't libraries just support v3 and v4 simultaneously? Unfortunately the limitations of peerDependencies (and inconsistencies between package managers) make it extremely difficult to elegantly support two major versions of one library simultaneously.
If I naively published
zod@4.0.0to npm, the vast majority of the libraries in Zod's ecosystem would need to publish a new major version to properly support Zod 4. this includes some high-profile libraries like theaiSDK. it would trigger a "version bump avalanche" across the ecosystem and generally create a huge amount of frustration and work.By co-publishing v3 and v4 together, we solve this problem. it provides a straightforward way to support Zod 3 and Zod 4 (including Zod Mini) simultaneously. they can continue defining a single peerDependency on
"zod"; no need for more arcane solutions like npm aliases, optional peer dependencies, or a"zod-compat"package.Existing projects will be able upgrade Zod to the latest minor version (
zod@3.25) to get access to"zod/v4"and its many improvements. (During the beta period, they can usezod@next.) The can do this with confidence that there will be zero breakage.Libraries will need to bump the minimum version of their
"zod"peer dependency tozod@^3.25.0. They can then reference both Zod 3 and Zod 4 in their implementation:Later, once there's broad support for v4, we'll bump the major version on npm and start exporting Zod 4 from the package root, completing the transition. Zod 3 will remain available at
"zod/v3"forever. While it may seem unorthodox, this is the only approach I'm aware of that enables a clean, incremental migration path for both Zod's users and the libraries in the broader ecosystem.The text was updated successfully, but these errors were encountered: