npm is an absolute disaster of a dependency management system. Peer dependencies are so broken that they had to make v4 pretend it's v3.
Ultimately you're right that npm doesn't work well to manage the situation Zod finds itself in. But Zod is subject to a bunch of constraints that virtually no other libraries are subject to. There are dozens or hundreds of libraries that directly import interfaces/classes from "zod" and use them in their own public-facing API.
Since these libraries are directly coupled to Zod, they would need to publish a new major version whenever Zod does. That's ultimately reasonable in isolation, but in Zod's case it would trigger a "version avalanche" would just be painful for everyone involved. Selfishly, I suspect it would result in a huge swath of the ecosystem pinning on v3 forever.
The approach I ended up using is analogous to what Golang does. In essence a given package never publishes new breaking versions: they just add a new subpath when a new breaking release is made. In the TypeScript ecosystem, this means libraries can configure a single peer dependency on zod@^3.25.0 and support both versions simultaneously by importing what they need from "zod/v3" and "zod/v4". It provides a nice opt-in incremental upgrade path for end-users of Zod too.
Let's say a library is trying to implement an `acceptSchema` function that can accepts `Zod3Type | Zod4Type`. For starters: those two interfaces won't both be available if Zod 3 and Zod 4 are in separate packages. So that's already a non-starter. And differentiating them at runtime requires knowing which package is installed, which is impossible in the general case (mostly because frontend bundlers generally have no affordance for optional peer dependencies).
I describe this in more detail here: https://x.com/colinhacks/status/1922101292849410256
I am still curious about the `zod4` idea though. Any thoughts on adding an `__api_version` type of property to distinguish on to all of zod's public types? Perhaps it's prohibitive code-size wise but wondering if it's possible somehow. Then downstream libraries could differentiate by doing the property check.
Just wanted to share the idea but the current state seems ok too.
I'm not sure this is the right conclusion here. I think zod v4 is being included within v3 so consumers can migrate over incrementally. I.e refactor all usages, one by one to `import ... from 'zod/v4'`, and once that's done, upgrade to v4 entirely.
It seems like Zod is a library that provides schema to your (domain) objects in JS/TS projects, so if you're all-in with this library, it's probably a base-layer for a ton of stuff in the entire codebase.
Now imagine that the codebase is worked on by multiple parties, in different areas, and you're dealing with 100K-1M lines of code. Realistically, you can't coordinate such a huge change with just one "Migrated to Zod 4" commit and call it a day, and you most likely want to do it in pieces.
I'm not convinced publishing V4 as version 3 on npm is the best way of achieving this, but to make that process easier seems to be the goal of that as far as I understand.
One of the strange things from the NPM/JS culture is the focus to write everything in one language leading to everyone forgetting about modularization and principles like SOLID. We link everything together with strange mechanisms for "DX", which really means "make it easy to write the first version, maintenance be damned".
You don't get anything remotely like this in any other backend frontend combo.
In simple applications, you can get away with defining a single schema for all, but it helps with keeping in mind that you may have to design a better data shape for some logic.
If the teams working on the two are different, or even if the expertise level is uneven, something like a typed serialization library is a great boon.
At work, I maintain a Haskell-like programming language which spits out JSON representations of charts over OLAP queries. I’m the only one who knows the language extensively, but everyone is expected to do work with the JSON I push. If I serialize something incorrectly, or if someone else mistypes the frontend JSON response definition, we’re in for a world of pain.
Needless to say, I’ll be adding something like Zod to make that situation safer for everyone.
You don't even need that, I use typed serialization on both sides when talking to myself. How else do I guarantee the shape of what I send and receive? I want my codebase to scream at me if I ever mess it up.
It is not a flawed approach, it's an important need for most web apps. Zod is a validation library, the whole purpose of is to define structures that can safely be shared across domains.
You can import aliases.
If you have a code that needs to use two versions of axios, or zod, or whatever...
"zod4": "npm:zod@4.0.0"That said, you do see a cultural difference in node-land vs. many other ecosystems where library maintainers are much quicker to go for the new major version vs. iterating on the existing version and maintaining backward compatibility. I think that's what people are mostly really referring to when they complain about node/npm.
Webpack is a good example—what's it on now, version 5? If it was a Go project, it would probably still be on v1 or maybe v2. While the API arguably does get 'better' with each major version, in practice a lot of the changes are cosmetic and unnecessary, and that's what frustrates people I think. Very few people really care how nice the API of their bundler is. They just want it to work, and to receive security updates etc. Any time you spend on upgrading and converting APIs is basically a waste—it's not adding value for users of your software.
When it's time to go for a refactoring, the trade-off between costs and returns are worth it as you can go for years between those huge refactors.
Edit: reading the rationale, it's about peer dependencies rather than direct dependencies. I am still a little confused.
I already gave my argument on why this won't happen. People stick to what they know and trust. They don't change because there is some other thing that is supposedly better. It has to be 10x better before people will migrate off one thing to another. If you want to do incremental improvements to a thing, then you'll have to do incremental improvements to that thing.
That's the point, and it makes sense from their perspective, I'd probably do the same as well.
Creating a new library instead of changing the existing one lets people chose between those two approaches. Want the latest and greatest but with API breakage? Use this library. Wanna continue using the current API? Use this library.
Instead, we kind of force the first approach on people, which I personally aren't too much of a fan of.
What package management system has a solution to this? Even so called "stable" platforms like Maven deal with this nonsense by publishing new versions under a new namespace (like Apache Commons did from v2 to v3).
They could at least also publish it as a major version without the legacy layer
EDIT: I've just seen the reason described here: https://github.com/colinhacks/zod/issues/4371 TLDR: He doesn't want to trigger a "version bump avalanche" across the ecosystem. (Which I believe, wouldn't happen as they could still backport fixes and support the v3 for a time, as they do it right now)
Edit: Thinking about it, that's the origin story of JavaScript as well, so rather fitting.