Regarding the versioning: I wrote a fairly detailed writeup here[0] for those who are interested in the reasons for this approach.
Ultimately npm is not designed to handle the situation Zod finds itself in. Zod is subject to a bunch of constraints that virtually no other libraries are subject to. Namely, the 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.
Many thanks for your work! Definitely looking forward to the upgrade - especially the performance-boosts with regards to tsc will be very welcome in our relatively large code-base, and the changes to discriminated unions will probably help us big time in a very specific scenario where so far they fell short.
That being said, I'm fully understanding of the reasons for the somewhat odd versioning given your special situation, but still, I'd wish there would be a 4.0.0-package for folks like us who simply don't need to worry or bother about zod-version-clashes in transitive dependencies bacause those don't exist (or at least I think so; npm ls zod only returns our own dependency of zod). If I understood correctly, we'll need to adapt the import to "zod/v4", which will be an incredibly noisy change and will probably cause quite a few headaches when IDEs auto-import from 'zod' and such, which we then need to catch with linting-rules.
But that's probably a small gripe for a what sounds overall like a very promising upgrade - many thanks for your work once again!
+1. We use Zod only for internal validation and would love a standalone release for v4 (or another package like zod4 or @zod/zod). I'm sure many greenfield projects would prefer that, too.
> 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.
This is extremely sensible. And it means you can provide security updates for older versions, just all in the same codebase's releases.
Sorry if it's mentioned in the article but I'm on mobile.
Is fixing .optional() in TS[0] part of the 9/10 top-issues fixed? This has been my biggest pain point with Zod... but still Zod is so good I still choose to just deal with it :) Thanks for an amazing part of the ecosystem.
First thank you for the hard work, many of my local hacks will go away with the new features!
As a convenience and mostly avoid typos in form names I use my own version of https://github.com/raflymln/zod-key-parser. I've been surprised something like this hasn't been implemented directly in the library.
Curious if you think this is out of scope for Zod or just something you haven't gotten around to implement?
Some kind of affordance for FormData/URLSearchParams-style structures is definitely in scope. It was a late cut. Ultimately HTML inputs/forms are an implicit type system unto itself—certainly HTML has a very different notion of "optional" than TypeScript. So my approach to this would likely involve another sub-library ("zod/v4-form").
I like your library! Put in a PR to add it to the ecosystem page :)
Great to hear this is something you are considering!
To be clear: this isn't my library. This is just something I found while trying to solve the FormData issue. Props go to https://github.com/raflymln who created it.
Am I to understand the earliest version of Zod 4 is 3.25.0?
Does this not sound insane?
---
I've been using the alpha versions of Zod for months, I just want to edit package.json and upgrade. But now I need to shotgun across git history instead.
Colin, I appreciate your project immensely. As a point of feedback, you made this ^ much harder than you had to. (Perhaps publish a 4.x along with the 3.x stuff?)
I understand this as a knee-jerk reaction. I didn't do this lightly.
> Perhaps publish a 4.x along with the 3.x stuff
You have some misconceptions about how npm works. Unfortunately it's less reasonable than you think. There's a single `latest` tag, and there's only one "latest" version at a time. It's expected that successive versions here will follow semver. Once I publish zod@4 I can no longer publish additional zod@3.x.x versions. The workaround here is to publish v3 versions to a separate dist tag (zod@three) but anyone consuming that dist-tag (e.g. "zod": "three" in their package.json) loses the ability to specify a semver range.
I recommend reading the writeup[0]. I don't think you're appreciating the magnitude of the disruption a simple major version bump would have caused, or the reasons why this approach is necessary to unlock continuity for Zod's ecosystem libraries. They're quite subtle.
Just would like to say I really appreciate your consideration of releasing breaking changes. I know not all libraries can employ your methodology but I wish many more of them would, as a frontend platform engineer.
Is there any interop between v3 and v4 schemas themselves? We have an enormous graph of hundreds (if not thousands) of Zod schemas, many inheriting or extending others. It's difficult to envisage us being able to do an incremental upgrade unless both versions can interact neatly.
But I am looking forward to seeing if this fixes our issue where in the worst case a 500 line schema file turns into 800,000 lines of generated types.
No, that kind of interop, especially static interop (assignability), would've been totally unworkable. Despite the length of the changelog, there are very few breaking changes to the user-facing API surface. It's mostly internal/structural changes and deprecations (most of which can be fixed with a find&replace).
Report back about that .d.ts issue. It should be far better. That kind of type explosion usually happens when TypeScript needs to infer function/method return types. Zod 4 uses isolatedDeclarations so this kind of thing shouldn't happen.
While publishing both versions together helps with compatibility issues, the library now becomes even heavier in environments where tree-shaking is not enabled. In React Native, for example, you have to jump through a lot of hoops to get tree-shaking to work (including getting off the default metro bundler, which can often be a non-starter).
I saw your tweet about cracking type inference for recursive schemas. It seems like the solution to this problem is pretty straightforward and simple. Was the solution really as simple as using a getter, or is there some additional complexity that I am failing to grok?
Big thank you for the work on Zod - it's a fantastic library and it's been incredibly valuable for data validation/parsing in Node environments for me over the last two years.
A perfectly valid evolution strategy is to add new APIs while keeping the old (which you may or may not choose to deprecate). That is, add the new APIs to 3.x (but probably call them something other than v4.
Now, that's effectively what 3.25 is. But there are some problematic extras... the semantics of the semantic versioning is muddled. That means confusion, which means some people will spin their wheels after not initially grokking the situation correctly. Also, there seems to be an implication there could be a strong deprecation of v3 APIs coming. That is, you have to wonder how long the window for incremental migration will remain open.
To be frank, I wouldn't touch zod on any project I hoped will be around for a while. Predicting the future is an uncertain business, but we can look at the past. In a few years, I think it's reasonable to guess zod v4 will be getting the same treatment zod v3 is getting now.
Not that I think you ought to do anything different. I probably wouldn't want to maintain some old API I came up with years ago indefinitely either (not without a decent support contract, that is).
> To simplify the migration process both for users and Zod's ecosystem of associated libraries, Zod 4 is being published alongside Zod 3 as part of the zod@3.25 release. [...] import Zod 4 from the "/v4" subpath
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.
Author here. I wrote a fairly detailed writeup here[0] for those who are interested in the reasons for this approach.
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.
Are there any plans of doing an actual v4 release and making zod/v4 the default there? Perhaps make simulatenous releases of zod v3 containing a /v4 path and a zod v4 containing a /v3 path? Then converge on just zod v4 with no /v3 from 4.1 onwards.
Yep, at some indeterminate point when I gauge that there's sufficient support for Zod 4 in the ecosystem, I'll publish `zod@4.0.0` to npm. This is detailed in the writeup[0]
Is there any advantage to this approach over publishing a separate "zod4" package? That would be just as opt-in and incremental, not bloat download sizes forever, and make it easier to not accidentally import the wrong thing.
Ecosystem libraries would need to switch from a single peer dependency on Zod to two optional peer dependencies. Despite "optional peer dependencies" technicall being a thing, its functionally impossible for a library to determine which of the two packages your user is actually bringing to the table.
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).
Thanks a lot for zod and really looking forward to trying out the new version! Also as a primary Go developer this issue just has been really interesting to read about. Go avoids this issue by just not having peer dependencies and relying on the compiler to not bundle unused code - or just live with huge binaries when it doesn't work out :-)
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.
> Peer dependencies are so broken that they had to make v4 pretend it's v3
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.
How do you even migrate incrementally? why keep both old and new code together like a Frankeinstein project? Especially on a codebase you own. It's a library, not a platform.
> why keep both old and new code together like a Frankeinstein project?
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.
If it's part of your core domain, I'd say that one of the reasons you want the feature set and the API to be as stable as possible. And your core domain should probably be isolated from the things that depends on it in such way that only business logic ripples out.
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".
This comment feels very detached from reality. Migrating core dependencies in large projects is always cumbersome. One universal truth is that you can make complex tasks easy by breaking it up into small pieces. Providing a sensible forward migration path like what Zod does causes 0 harm and makes everyone's life easier. This has absolutely nothing to do with "NPM/JS" culture, whatever that means.
You use Zod to define all the schemas and types used in "your core domain". It is the base layer tool of your business logic and models, and for defining your interfaces. And yes it makes it possible to share all of this between the frontend and backend, which is a tremendous improvement in both correctness and in development productivity.
You don't get anything remotely like this in any other backend frontend combo.
I get the wish to have that, but IMO, it's a flawed approach. The frontend and the backend are generally different domains. Initially, their model may look alike, but they will probably differs during the lifetime of the project as they serve different needs. That's why the shape of the data stored in the DB differs from the one involved in business logic, which differs from the DTOs, which can differs from the objects involved in the presentation.
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.
> The frontend and the backend are generally different domains
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.
The point is that somewhere, you need to chuck bytes over the network and someone needs to receive them.
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.
> 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.
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.
This is not done for Zod's benefit. It's done for the benefit of libraries that depend on Zod, and the users of those libraries. If a library wants to add "incremental" support for Zod4 (that is, without dropping support for Zod 3 and publishing a new major), they need access to types (and possibly runtime code) from both libraries to do so in a sound way. I detail a number of other approaches for achieving this here[0] and why they ultimately fall short. Ultimately npm wasn't designed for this particular set of circumstances.
Yeah, importing two versions could allow you to pass v3 objects to v4 methods and vice versa, and that seems like an extremely bad idea (if it would even type-check / run).
I feel like people will upvote anything negative. This is not much a limitation of npm, there's nothing intrinsically wrong with npm that lead to this decision, this is more a pragmatic way of allowing progressive change of a library that introduced a lot of braking changes.
Right, you have the same issues to consider when shipping a breaking major version upgrade to a new library in any language/ecosystem.
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.
This very much. If I'm using your library, I've already committed to it's architecture and API with all its flaws. And my users don't care for the technology I use. Even if they're not that good, I can build wrapper over the worst aspects and then just focus on building features. New features are nice, but I'm more interested in getting security updates for the current version that I have.
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.
I might be blindsided by using npm exclusively for years by this point, but what would be a better way to support iteratively migrating from v3 to v4 without having to do it all in one large batch?
As you allude to: your aliased "zod-next" dependency wouldn't be able to satisfy the requirements of any packages with a peer dep on Zod. But this approach has a more fundamental flaw. My goal is to let ecosystem libraries support Zod 3 and Zod 4 simultaneously. There's no reliable way to do that if they aren't in the same package.[0]
One possible solution: Publish a new package with a new name. I've personally been thinking of doing that for some libraries, where I'd commit to never change the public API, and if I figure out a nicer way of doing something, I'd create a new library for it instead, and people who wanna use/maintain the old API can continue to do so.
If they need the new one, they will switch to it. And you have the right to drop support for the old one after a while (hopefully giving everyone the time to migrate).
> If they need the new one, they will switch to it.
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.
> 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.
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.
As I’ve said in other comments. If you’re developing a library, you can commit to its API and do security and optimization fixes and build a new one where you try a new design/approach. Merging the two together is always a bad idea.
This isn't an npm exclusive issue. A dependency having some other transitive deps also depend on an older version is a problem that happens in literally every other ecosystem. If anything, npm gives you more escape hatches by actually allowing you to run multiple versions concurrently if you need to or selectively overriding parts of your transitive dependency graph.
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).
We've been using zod 4 beta already with great improvements but due to our huge codebase not being able to handle the required moduleResolution settings, we cannot upgrade...
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)
I feel like both Node.js and NPM were initially vibe coded before LLMs existed. Just a quick hack, kind of, that got hugely popular somewhat by accident.
Edit: Thinking about it, that's the origin story of JavaScript as well, so rather fitting.
I'm curious if anyone here can answer a question I've wondered about for a long time. I've heard Zod might be in the right ballpark, but from reading the documentation, I'm not sure how I would go about it.
Say I have a type returned by the server that might have more sophisticated types than the server API can represent. For instance, api/:postid/author returns a User, but it could either be a normal User or an anonymous User, in which case fields like `username`, `location`, etc come back null. So in this case I might want to use a discriminated union to represent my User object. And other objects coming back from other endpoints might also need some type alterations done to them as well. For instance, a User might sometimes have Post[] on them, and if the Post is from a moderator, it might have special attributes, etc - another discriminated union.
In the past, I've written functions like normalizeUser() and normalizePost() to solve this, but this quickly becomes really messy. Since different endpoints return different subsets of the User/Post model, I would end up writing like 5 different versions of normalizePost for each endpoint, which seems like a mess.
You can define passthrough behavior if there are a bunch of special attributes for a moderator but you don't want to list/check them all.
With different methods that have different schema- If they share part of the same schema with alterations, you can define an object for the shared part and create objects that contain the shared object schema with additional fields.
If you have a lot of different possibilities, it will be messy, but it sounds like it already is for you, so validators could still at least validate the messines.
Hmm, this is pretty interesting, but I still have issues. While Zod seems to be able to transform my server-returned object into a discriminated union, it doesn't seem to be able to tell which of the unions it is. For instance, say that api/user/mod-panel (e.g.) returns only moderator user objects. My API endpoint already knows that it will have moderator-related fields, but Zod forgets that when I parse it.
You can use an ‘is’ method to pick out a type from union. Although, if union is discriminated, it’s discriminated with a ‘kind’ so you should be able to know which kind you received.
I am not totally sure what your API's look like but if you know the API only has a certain type (or subset of types), you would only validate that type on the method. Don't use a single union for everything.
Here is some pseudocode.
Person = { name: string, height: number }
Animal = {name: string, capability: string}
A = { post: object, methodType: string, person: Person }
You can define all the different sub types separately and make the discriminated union using them. The use only a single type for an endpoint if it only uses a single type. Only use the discriminated union where you actually might be handling multiple types.
In an ideal world you'd have one source of truth for what the shape of a User could be (which may well be a discriminated union of User and AnonymousUser or similar).
Without fullstack TS this could look something like: (for a Python backend) Pydantic models+union for the various shapes of `User`, and then OpenAPI/GraphQL schema generation+codegen for the TS client.
The problem with this is that your One True User shape tends to have a bunch of optional properties on it. e.g., in the user profile you fetch Post[], but in the user directory you don't, and so on with other joined properties. If every endpoint returns the One True User, then you end up needing to write conditional logic to guard against (say) `.posts` when you fetch users in the profile, even though you know that `.posts` exists.
In Typescript at least, if the discriminated union is set up correctly, you just need a single check of the type field. That lets TS narrow the type so it knows whether e.g. `.posts` is present or not.
I think I can do this, yes, but it becomes a very large amount of repetitive work.
Let's say I have api/profile (which has `.posts`) and api/user-directory (which does not). I define User as a discriminated union - one has type `user-with-posts` and one has type `user-no-posts`. OK, good so far. But now say I have a photo gallery, which returns photos on user. Now I have to add that into my discriminated union type, e.g. `user-with-posts-and-photos`, `user-with-posts-but-not-photos`, `user-with-no-posts-but-yes-photos`... and it gets worse if I also have another page with DMs...
You can use a string union to discriminate when it makes sense, but that's not the only way to discriminate and in this case you'd instead use the presence of the items themselves (essentially duck-typing with strong type guarantees)
Change the design of the API so that the posts and the photos and so on are not returned inside the user object but on the same level as it.
So {user: {...}, photos: [...]}, not {user: {..., photos: [...]}}.
Alternatively define separate schemas for each endpoint that extend the base User schema. But I'd prefer having the same structure everywhere as much as possible.
Not sure how other stacks solve this, but with GraphQL the backend defines a `User` type with a full set of fields, and the client specifies only the fields it wants to query. And with codegen you get type safety.
So on the /posts page the client asks for `{ user: { id, posts: { id, content }[] } }`, and gets a generated properly-typed function for making the query.
It's hard to unpack without knowing more about the use case, but adding discriminant properties (e.g. "user_type") to all the types in the union can make it easier to handle the general and specific case.
E.g.
if (user.user_type === 'authenticated') {
// do something with user.name because the type system knows we have that now
}
Your server should export the types. Don't write types by hand in your client, that makes no sense. The server knows what data it is sending and should provide that information as metadata to the client. Practically this can mean that a Python backend uses Pydantic schemas which can be used to automatically generate an OpenAPI specification that your client can use to generate types.
This answer is how I wish the world would work, but I am stuck with a server with a poor type system that can't refine the types nearly as accurately as TS can. :(
Zod is a lot better than some of the alternative solutions I've seen. That said, the need for this sort of explicit validation always felt like a failure of where modern web development has taken us. It's so frustrating how full-stack development requires so many ways of describing the same shapes: JS input validation, Swagger for API definition, server-side input validation, ORM for schema conformance, and TypeScript often requiring separate definitions on server and client side. It's so tedious.
TypeScript's insistence on being a static checking/compile time only system is such a sad wound to the whole ecosystem. I don't want TypeScript to be a runtime checker, but I want it to export useful usable type data for classes, functions, objects. TypeScript feels like the best source of truth we have, but instead so many of the attempts to reflect on what we have are all going it alone, having to define their own model and their own builders for describing what stuff is. You've mentioned 5 major areas where reflection is a core part of the mission, and each of these have multiple implementations.
There is the old TypeScript type emitter, reflect-metadata, which would provide some type information at runtime, but it targets very old decorator and metadata specifications, not the current version. I don't super know how accurate or complete it's model really is, how closely it writes down what typescript knows versus how much it defines its own model to export to. https://www.npmjs.com/package/reflect-metadata
We are maybe at the cusp of some unifying, some coming together, albeit not via typescript at this time, still as a separate layer. The Standard Schema project has support from I dare say most of the top validation libraries. But extending this to API definitions, ORM tools is in extremely early stages.
https://github.com/standard-schema/standard-schema?tab=readm...
If the types are internally consistent, then they don't need runtime validation, it'd just be extra code to download and run.
If you accept external data, you may already opt in using something like Zod. I don't see why conflate the two things just because their quacks echo the same.
Hard agree - TSC already has this information, why should so many libraries in the world duplicate it ? A single source of truth works better than everyone repeating the same in different, finicky runtime validation libraries.
Yes. Although I am more familiar with TypeScript and prefer it for a few reasons, I've been inspired seeing how Pydantic has been used in the field for both design-time and runtime validation.
But that’s the whole point of something like this. You do it once and dynamically generate everything else downstream. So change it once in the zod schema and it propagates with type checking through your entire app.
One way might be to convert the Zod schema to a JSON schema and then to Java? I found a library to do that. [1] But I don’t know how lossy that would be. A purpose-built converter might do better.
Does zod really support that? What if the code base start out with a go backend and a TS/JS component is only added later? It would be nice if the source of truth was a bit more language agnostic.
You shouldn’t typically need to redefine your data all over the places. There are zillions of converters for everything to zod, and zod to everything.
If you already have JSON schema/swagger schemas, generate zod from em. If you use a typescript orm, I bet you $10 there’s a zod generator for it.
Honestly zod has gotten so popular that for me, it’s the unifying schema definition that everything else in the stack can rely on. And since directly defines the types, devs actually keep it up to date (swagger docs at my company are ALWAYS lagging behind changes)
> It's so frustrating how full-stack development requires so many ways of describing the same shapes: JS input validation, Swagger for API definition, server-side input validation, ORM for schema conformance, and TypeScript often requiring separate definitions on server and client side. It's so tedious.
Many of the same people who complain about how complicated modern web dev is would also shudder at the suggestion to just replace all those things with TypeScript (and Zod, if that's your TS schema definition and validation library of choice).
Drizzle has a zod addon, to generate zod schema from table defn. So table defn is source of truth, we mix generated zod schemas to get hono request validators. Same zod schema are also used on client to validate forms.
How else would you do it? You could use something like trpc for full end to end type safety but that requires using TypeScript on both the frontend and backend (which not everyone does) and also locking yourself into only the web platform (so no mobile, etc).
Yes there should at least be a way to consolidate so that we can agree on format to treat as the source of truth that we can generate the other formats from.
Zod 4 looks good but even with their latest improvements, ArkType is still an order of magnitude faster. Sometimes for the sake of backward and syntax compatibility, it is difficult to make something much faster than a fully greenfield newer library. We recently did an analysis of all these types of tools for our project and decided to go with ArkType for partially this reason, the other was TypeScript ergonomics felt nicer.
I was looking at all their speed metrics, and can you explain to me where the speed makes a difference?
We only use zod to validate forms, so I keep thinking "how does this matter?" Are people maybe using it to validate high throughput API input messages or something like that, where performance may matter more?
Yes, we use it to validate the API responses from the backend (as well as type validation on the backend itself from any frontend POST requests), and especially on the client side, speed and bundle size is very important.
Does arktype not come with a larger bundle size than zod? That was the reason I was shying away from it at the moment, especially with the bundle size reductions with zod 4 as well
Yeah, I can't see zod really adding that much overhead in the critical latency path for all but extremely large responses. Sometimes people pick "the fastest" library without considering whether the performance is relevant for a given code path.
Interesting, that one didn't even appear in my research. I was specifically looking for typescript ergonomics too. Probably still not going to switch away from Zod, though.
Congratulations to the Zod team on the new release. At the risk of sounding overtly negative, I can't help but shudder when I think about the number of breaking changes outlined in the migration guide. For projects that rely heavily on Zod, it feels like a daunting task ahead—one that will demand a lot of developer attention and time to navigate. Having maintained a few frontend projects that are 4-5 years old at work, I really empathize with them.
In my experience, large React projects often depend on a multitude of libraries, and when each one rolls out substantial changes—sometimes with barely any documentation—it can quickly become overwhelming. This is honestly one of my least favorite aspects of working with JavaScript. It just feels like a constant uphill battle to keep everything in sync and functioning smoothly.
I am 100% in agreement here. I operate a couple large Next.js apps and in the last year we've had to deal with Next.js 14 -> 15 which introduced a ton of breaking cache changes, Next.js pages -> app router, React 18 -> 19, Eslint 8 -> 9, and Tailwind 3 -> 4.
It's honestly been a nightmare, and I wish I had just built in Django instead. The Tailwind 3 -> 4 migration was probably among the most painful, which I was not expecting.
I will continue to beat the drum that using easy-to-migrate frameworks like Django that don't go around introducing major breaking changes is one of the bigger web development superpowers.
Django doesn't run in the browser though. All of the tech they listed can run in the browser which gives you other superpowers at the expense of having moving targets, but that's what they opted into when they decided to run code on user machines instead of in a single server environment.
The main browser API is pretty stable, all things considered. It's just that people can't seem to stay put on a given design, instead trying everything under the sun.
When you have something like SDL which is at it's third version at 27 years old, I'm very doubtful about the culture of NPM/JS world. A closer example is jQuery which is also in its third version at 18 years old.
True, the browser API might be stable, but the best way to build stateful client applications is unstable.
It's a constantly improving and experimental domain - not just on the web but also the desktop and mobile environment.
Next.js is a good example since it (and its competitors) are a natural iteration on top of SPAs where you want the first request to the server to also inline the initial state of the SPA to remove the double-request problem.
But you pay a huge price trying to live on the edge like that, and when you run into issues, it doesn't make much sense to call that the state of web development since you could have used boring server tech or even a boring React SPA which also hasn't changed much in a decade.
that's why they're taking the dual-availability approach, with a separate 'mini' edition. it's easy to perform a progressive migration without messing with the package manager.
consumers uninterested in the 'mini' edition don't have to bother with that part.
but, the benefits of the 'mini' edition are so drastic for tree-shaking that it was driving development of alternatives - zod had to either do it (and benefit), or deprecate.
Was just looking at their release strategy. This is being handled by people that have experienced the hell that is dependency management in the JS ecosystem. Kudos to them.
This is the kind of task that LLMs are precisely terrible at; there isn't an abundance of Zod 4 examples, and the LLM will sure as shit will give you _something_ you are now by definition ill-equipped to assess.
I'm confident about this assessment because I maintain a large-ish piece of software and perenially have to decipher user reports of hallucinated LLM syntax for new features.
Are you sure that's not a skill issue? Zod v4 has .mdx documentation which can be given to the LLM as context, including a migration guide. A reasoning LLM should be able to manage.
I've only tried Claude in Cursor's free trial, but it became very confused during a React 19 upgrade even after showing it a guide. It also kept telling me to install irrelevant dependencies saying my code would not work without them. My experience was more or less shared with several other senior devs using their companies AI subscriptions. Are we all using the tools wrong? Or is there just an expected amount of having to fight with the machine to get a usable result?
> I've only tried Claude in Cursor's free trial, but it became very confused during a React 19 upgrade even after showing it a guide.
I have never used Cursor, but I see more and more people who used LLMs specifically via Cursor complain. It makes me think there's an issue specifically with Cursor, e.g., they try to save on tokens and end up not including enough context in the prompt.
> I've only tried Claude in Cursor's free trial, but it became very confused during a React 19 upgrade even after showing it a guide.
I am working on a Next.js 15 / React 19 app, and at least 95% of code is written by Gemini 2.5 Pro Preview, and I barely ever need to "fight" it really. But it's not a Cursor workflow of course. I keep a directory with LLM-readable documentation[0], use a repository serialization tool to serialize my repository into a prompt (this includes both the source code and the LLM-readable documentation), and send it to Gemini 2.5 Pro Preview. It ends up being over 100K tokens per query but works really well for me.
LLMs can't even not write React when you explicitly tell them not to write React in your Vue codebase. I still, with Gemini 2.5 Pro and Claude 3.7 both, get this annoying ass interaction almost daily, despite a universe of context there that should make it obvious I don't want a React component in my Vue codebase.
As a full stack dev that runs their own SaaS with thousands of users in production, sometimes I get a very pleasant reminder of how many problems I am blissfully unaware of just because I decided not to build an SPA or use JS frontend frameworks. It never occurred to me that I need such a thing as Zod/ArkType - first time hearing of it, and I have no use for it.
It boggles my mind how much effort and complexity and tooling goes into building an SPA. Entire classes of problems simply don't exist if you choose not to build an SPA. Meanwhile, I use the browser as designed: with full page reloads, backend development only, and occasional reactivity using a backend-only framework like Laravel Livewire. Everything is so simple: from access control to validation to state management. And yes, my app is fast, reactive, modern, SEO friendly, and serves thousands of users in production.
I worked on two large projects that use Zod and Protobuf to ensure schema evolution goes well with 5+ teams. Even if you have a lightweight frontend, it makes sense to use something that validates the schemas in the backend.
In the end you'll have a schema somewhere. Maybe defined in the database system, maybe defined in the models of an object-relational mapper. Since defining the schemas in database system or using object-relational mappers can cause very difficult problems in large projects we do not use it and use Zod and Protobuf instead. While I think you could even replace Protobuf completely with Zod or something similar.
There is the British Post Office scandal [1] around an IT system called Horizon (the legacy system in this case). After reading about the details I'm pretty sure something like Zod (I mean any schema validation) would have contributed to prevent this scandal. They even mentioned the lack of using a schema in the technical appendices in the court documents of the group legal action [2].
In that case, your objection seems to be to light weight or minimal frameworks rather than SPAs on this point. There are plenty of minimal backend frameworks for Node (and Python, and others) that can be and are used to build traditional "load a page for every interaction" applications, and Zod or something like it would be useful for those since minimal frameworks often don't include validation. Zod isn't exclusively for SPAs or even web applications. It's schema validation, which is useful in many domains.
Yeah, it's very useful to validate schemas at compile-time and runtime. It prevents several different problems to occur.
Lately, I used code agents a lot, and having typescripts types infered from Zod schemas allows me to catch errors when the large-language model generated slightly wrong code.
Because now I have the impression that you're just defensively writing a bunch of if-statements. Or worse, you rely on html client-side form validation only.
Any good backend framework (Laravel, Django, Livewire, Rails) does server side validation out of the box without me as a developer needing to manually pass around JSON objects and continually checking their shape. The boundary between user input and backend code is well defined and border checks are easy.
> manually pass around JSON objects and continually checking their shape
Well Zod is a library that's typically used on the boundary.
I don't know why you're assuming stuff about a library that you've never used. No one would continually check their shape once it's validated at the api boundary.
We have an enormous number of backend-only Zod schemas that are used as part of our data pipelines; so it doesn't seem like something that only exists to solve SPA problems.
Use the database? As in just throw user input straight into the DB without so much as checking its length to make sure it fits? Just let it error out? No sanitization, nothing?
If a JSON shape is maintained by another team, e.g. how can you know they did not change the shape without speaking with them? You could instead validate the schema and log the errors and get notified by the errors and then change your client code. This also means your client code does not need to know about the details of the database.
Yes, and it actually works. I use something like htmx or fixi [1] for my frontends of side-projects. Alternatively, I could also use laravel livewire, I even argue you could use them for large-scale projects like ERP systems. I even re-build small parts of a large ERP system including the design system implemention using htmx. No need for react or similar things, if you know HTML and CSS well and are a bit disciplined.
But once you don't use ORMs or have a non-monolithic architecture, you need something to validate your schema.
I am not an expert here but I had a thought that JSON-Schema might be a good choice because since it's schema based, i can implement the validators in Non-Typescript languages too.
https://ajv.js.org is one such JSON Schema library. How does zod compare to this?
Well, Zod isn't just for validating JSON. It supports validating objects that can't be represented in JSON without transformation (dates, class instances, and so on). You can also use it as your JSON transformer if you want to - you can write your schema so it accepts strings, validates them as ISO date strings, and outputs Date objects, for instance.
> Well, Zod isn't just for validating JSON. It supports validating objects that can't be represented in JSON without transformation (dates, class instances, and so on).
Thanks, this was the missing piece for me. I'd been thinking about using Zod for an old client's Node codebase, but I'd only need it to validate the shape of json objects received by http endpoints. Zod was looking like overkill, but I know it's popular so I wasn't sure what I was missing.
Zod 4 supports converting a Zod schema to JSON-Schema (natively, this has always been possible with 3rd-party libs).
One key difference is preprocessing/refine. With Zod, you can provide a callback before running validation, which is super useful and can't be represented in JSON. This comes in handy more often than you'd think - e.g converting MM/DD/YYYY to DD/MM/YYYY before validating as date.
It is a good choice and in that case TypeBox is a decent way to generate it.
And you can use AVJ or its own schema validation system (which is much faster, but only sync where avj has asynchronous validation options in case you want to check against a database or something).
I tested early versions of zod v4 and liked the new API, but was very concerned about what will be the migration path. I was even going to suggest to publish under a new package name.
But the author's approach is ingenious. It allows for someone like me to start adopting v4 immediately without waiting for every dependency to update.
I just got started working Zod into a new project. This could not have happened at a better time. I would have needed to change so much ot migrate to v4 based on what I'm seeing.
We're currently evaluating both Zod and ArkType as a replacement for earlier JSON schema validations. The thing I can't get over with Zod is the syntax is _so_ different from defining TS types.
On the ArkType website they talk about speed and DX, but no mention of bundle size. I assume, and maybe this is an unfair assumption, that's because it's bad. I haven't come across ArkType until just now, but I was just checking out Valibot today because it's got a small bundle size.
These numbers don't reflect anything useful. This is the total size of the code in the package, most of which will be tree-shaken. In Zod's case, the package now contains three independent sub-libraries. I recommend plugging a script into bundlejs.com[0] to see bundle size numbers for a particular script
We also chose ArkType after evaluating Zod, Valibot, and Effect Schema, among others. It seemed to have the best developer experience while also being much faster. It also supports the Standard Schema project which I believe Effect Schema does not fully support.
Could you elaborate on how exactly do you use these? I was assuming its for some kind of contract testing, but there are mentions of bundle size, is it used on fetching data to fail early if the format is wrong, something like that?
I believe Effect Schema fully supports Standard Schema, the issue is that it supports much more than Standard Schema, so not all schemas will work and thus provide compile time errors.
Yes that's correct, it's more powerful but we wanted to maintain full compatibility just for the future as well. But if you're all in on the Effect ecosystem, it's quite nice.
Everyone else is using Zod so the LLMs understand it well, there’s a big ecosystem, it’s unlikely to disappear overnight, and new hires may well already use it. It’s the boring solution.
With yet another exciting new release of something reaching the top of HN, I would just like to urge devs to put a description of the project they're actually releasing and a link to the page describing the project in the release announcement.
These announcements could be a valuable touchpoint for you to reach a whole new audience, but I can't remember a single one that starts with something like "exciting new release of NAME, the X that does Y for users of Z. Check out the project home page at https:// for more."
Quite often, the release announcement is a dead end that can't even take me to the project! In this case, the only link is a tiny octocat in the lower left-hand corner, AFAICS.
I was using TypeBox but switched to Zod. I like TypeBox but I found I don't actually need my schema to be a JSON Schema and the one time I did want a JSON Schema it was hard to get actual JSON back out of TypeBox.
The thing I like about Zod is the "refinements" and "transforms" and the new "overwrite" in Zod 4 was just what I wanted.
The versioning approach here is a really interesting compromise — especially in the npm ecosystem where breaking changes ripple out so painfully through transitive dependencies. From a developer ergonomics standpoint though, the shift to zod/v4 imports will definitely create some friction. For teams with IDEs auto-importing from 'zod' and linters enforcing import styles, it might introduce subtle DX issues until workflows are adjusted.
That said, the strategy does seem to prioritize ecosystem stability over short-term convenience, which is fair. Would love to see better tooling (maybe even IDE plugins or codemods) to help projects transition cleanly. Really appreciate the thoughtful design behind all of this.
One decision that seems dubious to me is the zod/v4-mini import. I suspect that this will actually increase bundle sizes across the ecosystem. The docs specifically say "zod/v4 is still recommended for the majority of use cases", so application developers will use it. Library authors will think to themselves, "but I want to enable my library to be used by those with uncommonly strict bundle size requirements", and so will use that. The net result is that both zod/v4 and zod/v4-mini will be included in the application bundle.
I guess this could be mostly avoided if zod/v4 actually a wrapper around zod/v4-mini. Is that the case?
But how is the below possible - doesn't it need to include most of the TypeScript compiler? Does it compile the type definitions to some kind of validation structure (like how a compiled regex works) and then use just that?
- Zero external dependencies
- Works in Node.js and all modern browsers
- Tiny: 2kb core bundle (gzipped)
The TypeScript compiler is only needed during development, the compiled JavaScript code contains no TypeScript-specific logic. Zod’s validation is entirely JavaScript-based, relying on simple checks (e.g., typeof, regexes, comparisons).
Also, the 2kb bundle just for the zod/v4-mini package, the full zod/v4 package is quite large.
I think Zod uses JIT compilation via `new Function`, rather than including the entire TypeScript compiler. This method allows for concise validation logic, executing only what’s necessary at runtime.
The library pretty much remained unusable garbage without documentation comments. I have no idea why it became so popular and why this release is named "stable" when there is even no 4.0.0.
Great job! I love support of json conversion you built-in. However, I find top level string bad choice as it was more verbose before, to have them under string() namespace.
All that text. So, so much text and not one single (maybe there was, but I fell asleep), not one single "Let me tell you what Zod is" paragraph. Lots of "Zod 4 is better than Zod 3" and "Here's what we pulled back, out, in, from Zod 2".
great job on zod. it’s an incredible library. also really excited about the locale errors. finally I can push the zod errors directly to the frontend. would love to take responsibility for the BG locale.
Obligatory shameless plug whenever Zod is posted: if you want similar, but much more minimal schema validation at runtime, with a JSON representation, try Spartan Schema: https://github.com/ar-nelson/spartan-schema
i would use it if there was just 1 normal zod lib not like how it is now: zod and zod mini and who knows what.
I rather use arktype or valibot if i am in browser only.
Seeing an announcement for a new version of some typescript library I've never heard of shoot to the top of the front page makes me feel extremely out of touch with mainstream dev.
Great if that's the only validation you need, but I can't imagine using it in a real app, and there are some obvious bugs (e.g. never use `instanceof Array`).
Array.isArray isn't needed when you know your array isn't going to be deserialized e.g. via MessagePort. What other supposed bugs?
And yes I'm aware this doesn't have a huge API surface. That's the whole point. If I already have a JSON object, I can reach into it and get either what I ask for or nothing. In many real world cases, this is enough.
let someArray = [1, 2, , 4];
console.log(as.numbers(someArray) === someArray); // => true
for (let number of numbers) {
// This should be safe because I know everything in the array is a number, right?
console.log(number.toFixed(2)); // => TypeError: number is undefined
}
I mean, it's probably fine if you're only ever getting your data from JSON.parse(). But I would hesitate to use this in production.
You use a different function than Validate_Parsed_JSON in those cases. But most typescript programs are only going to need JSON-compatible input. Maybe some XML but that's also going to have similar formulaic output from your parser.
If something can directly hand you a maliciously built data structure, you're probably designing your system wrong. Are you running untrusted javascript in the same interpreter? That's a very hard problem that should be avoided if at all possible.
Basically, only working on JSON.parse is something to document but it's not at all a weird restriction, or a reason to balk at putting it into production.
If you don't do web dev (or at least, the latest web dev) then it's understandable, I often see lots of posts in the top spots whose languages I have no idea about either.
Between GraphQL and Zod, there really is no comparison. The latter feels clunky and superfluous by design when the former ecosystem can smoothly provide static TS typings without extra work or schema duplication.
Squid ink is black so are teflon pans, the latter feels clunky and superfluous by design when the former type of fruit can smoothly provide vitamins to vertically integrate with our stack.
Author here, AMA!
Regarding the versioning: I wrote a fairly detailed writeup here[0] for those who are interested in the reasons for this approach.
Ultimately npm is not designed to handle the situation Zod finds itself in. Zod is subject to a bunch of constraints that virtually no other libraries are subject to. Namely, the 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.
[0] https://github.com/colinhacks/zod/issues/4371
Many thanks for your work! Definitely looking forward to the upgrade - especially the performance-boosts with regards to tsc will be very welcome in our relatively large code-base, and the changes to discriminated unions will probably help us big time in a very specific scenario where so far they fell short.
That being said, I'm fully understanding of the reasons for the somewhat odd versioning given your special situation, but still, I'd wish there would be a 4.0.0-package for folks like us who simply don't need to worry or bother about zod-version-clashes in transitive dependencies bacause those don't exist (or at least I think so; npm ls zod only returns our own dependency of zod). If I understood correctly, we'll need to adapt the import to "zod/v4", which will be an incredibly noisy change and will probably cause quite a few headaches when IDEs auto-import from 'zod' and such, which we then need to catch with linting-rules.
But that's probably a small gripe for a what sounds overall like a very promising upgrade - many thanks for your work once again!
+1. We use Zod only for internal validation and would love a standalone release for v4 (or another package like zod4 or @zod/zod). I'm sure many greenfield projects would prefer that, too.
> 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.
This is extremely sensible. And it means you can provide security updates for older versions, just all in the same codebase's releases.
Sorry if it's mentioned in the article but I'm on mobile.
Is fixing .optional() in TS[0] part of the 9/10 top-issues fixed? This has been my biggest pain point with Zod... but still Zod is so good I still choose to just deal with it :) Thanks for an amazing part of the ecosystem.
[0] https://github.com/colinhacks/zod/issues/635
Yes! Zod now differentiates between `z.string().optional()` and `z.union([z.string(), z.undefined()])` (as in TypeScript itself). Details: https://x.com/colinhacks/status/1919291504587137496
First thank you for the hard work, many of my local hacks will go away with the new features!
As a convenience and mostly avoid typos in form names I use my own version of https://github.com/raflymln/zod-key-parser. I've been surprised something like this hasn't been implemented directly in the library.
Curious if you think this is out of scope for Zod or just something you haven't gotten around to implement?
(Here are discussions around it: https://github.com/colinhacks/zod/discussions/2134)
Some kind of affordance for FormData/URLSearchParams-style structures is definitely in scope. It was a late cut. Ultimately HTML inputs/forms are an implicit type system unto itself—certainly HTML has a very different notion of "optional" than TypeScript. So my approach to this would likely involve another sub-library ("zod/v4-form").
I like your library! Put in a PR to add it to the ecosystem page :)
Great to hear this is something you are considering!
To be clear: this isn't my library. This is just something I found while trying to solve the FormData issue. Props go to https://github.com/raflymln who created it.
Am I to understand the earliest version of Zod 4 is 3.25.0?
Does this not sound insane?
---
I've been using the alpha versions of Zod for months, I just want to edit package.json and upgrade. But now I need to shotgun across git history instead.
Colin, I appreciate your project immensely. As a point of feedback, you made this ^ much harder than you had to. (Perhaps publish a 4.x along with the 3.x stuff?)
I understand this as a knee-jerk reaction. I didn't do this lightly.
> Perhaps publish a 4.x along with the 3.x stuff
You have some misconceptions about how npm works. Unfortunately it's less reasonable than you think. There's a single `latest` tag, and there's only one "latest" version at a time. It's expected that successive versions here will follow semver. Once I publish zod@4 I can no longer publish additional zod@3.x.x versions. The workaround here is to publish v3 versions to a separate dist tag (zod@three) but anyone consuming that dist-tag (e.g. "zod": "three" in their package.json) loses the ability to specify a semver range.
I recommend reading the writeup[0]. I don't think you're appreciating the magnitude of the disruption a simple major version bump would have caused, or the reasons why this approach is necessary to unlock continuity for Zod's ecosystem libraries. They're quite subtle.
[0] https://github.com/colinhacks/zod/issues/4371
You can absolutely publish 3.x.x after 4.x.x, they just won’t be “latest” (of course).
Speaking bluntly, this isn’t how libraries in the npm upgrade, and pitching this does not inspire confidence.
Just would like to say I really appreciate your consideration of releasing breaking changes. I know not all libraries can employ your methodology but I wish many more of them would, as a frontend platform engineer.
The path of least short term pain is often the best path.
Everyone old in Python ecosystem remembers the Python 2/3 migration madness.
A heartfelt thank you for not breaking the world like many other libraries do!
Breaking changed in fundamental but auxiliary libraries are so painful in the world of frontend development that it's not even funny anymore.
Is there any interop between v3 and v4 schemas themselves? We have an enormous graph of hundreds (if not thousands) of Zod schemas, many inheriting or extending others. It's difficult to envisage us being able to do an incremental upgrade unless both versions can interact neatly.
But I am looking forward to seeing if this fixes our issue where in the worst case a 500 line schema file turns into 800,000 lines of generated types.
No, that kind of interop, especially static interop (assignability), would've been totally unworkable. Despite the length of the changelog, there are very few breaking changes to the user-facing API surface. It's mostly internal/structural changes and deprecations (most of which can be fixed with a find&replace).
Report back about that .d.ts issue. It should be far better. That kind of type explosion usually happens when TypeScript needs to infer function/method return types. Zod 4 uses isolatedDeclarations so this kind of thing shouldn't happen.
No. You will have errors if you try this.
While publishing both versions together helps with compatibility issues, the library now becomes even heavier in environments where tree-shaking is not enabled. In React Native, for example, you have to jump through a lot of hoops to get tree-shaking to work (including getting off the default metro bundler, which can often be a non-starter).
I saw your tweet about cracking type inference for recursive schemas. It seems like the solution to this problem is pretty straightforward and simple. Was the solution really as simple as using a getter, or is there some additional complexity that I am failing to grok?
the solution is to avoid TypeScript eagerly validating the object's value type. eager validation breaks cyclic references.
Zod's source code is a bit unwieldy to explain what's going on I feel, so here's a small validation library I wrote that uses the same principle
https://github.com/mary-ext/atcute/blob/596e023bcb490b16d09a...
Big thank you for the work on Zod - it's a fantastic library and it's been incredibly valuable for data validation/parsing in Node environments for me over the last two years.
I had so much difficulty with recursive types mixed with discriminated union (think xml in json for example) hopefully it'll be better now
this blog post was a delight to read. great work, colin && thanks!!
A perfectly valid evolution strategy is to add new APIs while keeping the old (which you may or may not choose to deprecate). That is, add the new APIs to 3.x (but probably call them something other than v4.
Now, that's effectively what 3.25 is. But there are some problematic extras... the semantics of the semantic versioning is muddled. That means confusion, which means some people will spin their wheels after not initially grokking the situation correctly. Also, there seems to be an implication there could be a strong deprecation of v3 APIs coming. That is, you have to wonder how long the window for incremental migration will remain open.
To be frank, I wouldn't touch zod on any project I hoped will be around for a while. Predicting the future is an uncertain business, but we can look at the past. In a few years, I think it's reasonable to guess zod v4 will be getting the same treatment zod v3 is getting now.
Not that I think you ought to do anything different. I probably wouldn't want to maintain some old API I came up with years ago indefinitely either (not without a decent support contract, that is).
Uhm... Wouldn't it make more sense just to publish a `zod4` package?
TLDR: What do I put on my package json to get latest latest latest? "^4" ?
> To simplify the migration process both for users and Zod's ecosystem of associated libraries, Zod 4 is being published alongside Zod 3 as part of the zod@3.25 release. [...] import Zod 4 from the "/v4" subpath
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.
Author here. I wrote a fairly detailed writeup here[0] for those who are interested in the reasons for this approach.
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.
[0] https://github.com/colinhacks/zod/issues/4371
Are there any plans of doing an actual v4 release and making zod/v4 the default there? Perhaps make simulatenous releases of zod v3 containing a /v4 path and a zod v4 containing a /v3 path? Then converge on just zod v4 with no /v3 from 4.1 onwards.
Yep, at some indeterminate point when I gauge that there's sufficient support for Zod 4 in the ecosystem, I'll publish `zod@4.0.0` to npm. This is detailed in the writeup[0]
[0] https://github.com/colinhacks/zod/issues/4371
Is there any advantage to this approach over publishing a separate "zod4" package? That would be just as opt-in and incremental, not bloat download sizes forever, and make it easier to not accidentally import the wrong thing.
Ecosystem libraries would need to switch from a single peer dependency on Zod to two optional peer dependencies. Despite "optional peer dependencies" technicall being a thing, its functionally impossible for a library to determine which of the two packages your user is actually bringing to the table.
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
Thanks a lot for zod and really looking forward to trying out the new version! Also as a primary Go developer this issue just has been really interesting to read about. Go avoids this issue by just not having peer dependencies and relying on the compiler to not bundle unused code - or just live with huge binaries when it doesn't work out :-)
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.
> Peer dependencies are so broken that they had to make v4 pretend it's v3
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.
How do you even migrate incrementally? why keep both old and new code together like a Frankeinstein project? Especially on a codebase you own. It's a library, not a platform.
> why keep both old and new code together like a Frankeinstein project?
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.
If it's part of your core domain, I'd say that one of the reasons you want the feature set and the API to be as stable as possible. And your core domain should probably be isolated from the things that depends on it in such way that only business logic ripples out.
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".
This comment feels very detached from reality. Migrating core dependencies in large projects is always cumbersome. One universal truth is that you can make complex tasks easy by breaking it up into small pieces. Providing a sensible forward migration path like what Zod does causes 0 harm and makes everyone's life easier. This has absolutely nothing to do with "NPM/JS" culture, whatever that means.
You use Zod to define all the schemas and types used in "your core domain". It is the base layer tool of your business logic and models, and for defining your interfaces. And yes it makes it possible to share all of this between the frontend and backend, which is a tremendous improvement in both correctness and in development productivity.
You don't get anything remotely like this in any other backend frontend combo.
I get the wish to have that, but IMO, it's a flawed approach. The frontend and the backend are generally different domains. Initially, their model may look alike, but they will probably differs during the lifetime of the project as they serve different needs. That's why the shape of the data stored in the DB differs from the one involved in business logic, which differs from the DTOs, which can differs from the objects involved in the presentation.
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.
> The frontend and the backend are generally different domains
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.
The point is that somewhere, you need to chuck bytes over the network and someone needs to receive them.
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.
> 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.
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.
This is not done for Zod's benefit. It's done for the benefit of libraries that depend on Zod, and the users of those libraries. If a library wants to add "incremental" support for Zod4 (that is, without dropping support for Zod 3 and publishing a new major), they need access to types (and possibly runtime code) from both libraries to do so in a sound way. I detail a number of other approaches for achieving this here[0] and why they ultimately fall short. Ultimately npm wasn't designed for this particular set of circumstances.
[0] https://github.com/colinhacks/zod/issues/4371
Yeah, importing two versions could allow you to pass v3 objects to v4 methods and vice versa, and that seems like an extremely bad idea (if it would even type-check / run).
It won't typecheck, which is good in this case, because as you say that's a very bad idea :)
But that was always a choice.
You can import aliases.
If you have a code that needs to use two versions of axios, or zod, or whatever...
I feel like people will upvote anything negative. This is not much a limitation of npm, there's nothing intrinsically wrong with npm that lead to this decision, this is more a pragmatic way of allowing progressive change of a library that introduced a lot of braking changes.
Right, you have the same issues to consider when shipping a breaking major version upgrade to a new library in any language/ecosystem.
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.
This very much. If I'm using your library, I've already committed to it's architecture and API with all its flaws. And my users don't care for the technology I use. Even if they're not that good, I can build wrapper over the worst aspects and then just focus on building features. New features are nice, but I'm more interested in getting security updates for the current version that I have.
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.
I might be blindsided by using npm exclusively for years by this point, but what would be a better way to support iteratively migrating from v3 to v4 without having to do it all in one large batch?
Using npm's built in support for package aliases to simultaneously install zod@3 as zod and zod@4 as zod-next?
Edit: reading the rationale, it's about peer dependencies rather than direct dependencies. I am still a little confused.
As you allude to: your aliased "zod-next" dependency wouldn't be able to satisfy the requirements of any packages with a peer dep on Zod. But this approach has a more fundamental flaw. My goal is to let ecosystem libraries support Zod 3 and Zod 4 simultaneously. There's no reliable way to do that if they aren't in the same package.[0]
[0] https://github.com/colinhacks/zod/issues/4371
One possible solution: Publish a new package with a new name. I've personally been thinking of doing that for some libraries, where I'd commit to never change the public API, and if I figure out a nicer way of doing something, I'd create a new library for it instead, and people who wanna use/maintain the old API can continue to do so.
People wouldn't change to the new one, because names are extremely sticky, so what's the point?
Ok, that's fine by me. They can continue using the original library for whatever reason they want, including because of the name.
If they need the new one, they will switch to it. And you have the right to drop support for the old one after a while (hopefully giving everyone the time to migrate).
> If they need the new one, they will switch to it.
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.
> 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.
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.
As I’ve said in other comments. If you’re developing a library, you can commit to its API and do security and optimization fixes and build a new one where you try a new design/approach. Merging the two together is always a bad idea.
The point is API stability. Not enough people in the JS world care about this.
This isn't an npm exclusive issue. A dependency having some other transitive deps also depend on an older version is a problem that happens in literally every other ecosystem. If anything, npm gives you more escape hatches by actually allowing you to run multiple versions concurrently if you need to or selectively overriding parts of your transitive dependency graph.
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).
Horrible, not going to use it now. My ide will import whichever interchangeably, and it'll be a mess
We've been using zod 4 beta already with great improvements but due to our huge codebase not being able to handle the required moduleResolution settings, we cannot upgrade...
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)
Would not be hard for you or anyone else to do that as well.
Yeah this seems like very poor reasoning tbh.
apart from the other things people raised, as leerob also points out it hints to an llm that the api may be different https://x.com/leerob/status/1924504939818008791
I feel like both Node.js and NPM were initially vibe coded before LLMs existed. Just a quick hack, kind of, that got hugely popular somewhat by accident.
Edit: Thinking about it, that's the origin story of JavaScript as well, so rather fitting.
I'm curious if anyone here can answer a question I've wondered about for a long time. I've heard Zod might be in the right ballpark, but from reading the documentation, I'm not sure how I would go about it.
Say I have a type returned by the server that might have more sophisticated types than the server API can represent. For instance, api/:postid/author returns a User, but it could either be a normal User or an anonymous User, in which case fields like `username`, `location`, etc come back null. So in this case I might want to use a discriminated union to represent my User object. And other objects coming back from other endpoints might also need some type alterations done to them as well. For instance, a User might sometimes have Post[] on them, and if the Post is from a moderator, it might have special attributes, etc - another discriminated union.
In the past, I've written functions like normalizeUser() and normalizePost() to solve this, but this quickly becomes really messy. Since different endpoints return different subsets of the User/Post model, I would end up writing like 5 different versions of normalizePost for each endpoint, which seems like a mess.
How do people solve this problem?
I think you would use discrimated unions.
const MyResult = z.discriminatedUnion("status", [ z.object({ status: z.literal("success"), data: z.string() }), z.object({ status: z.literal("failed"), error: z.string() }), ]);
You can define passthrough behavior if there are a bunch of special attributes for a moderator but you don't want to list/check them all.
With different methods that have different schema- If they share part of the same schema with alterations, you can define an object for the shared part and create objects that contain the shared object schema with additional fields.
If you have a lot of different possibilities, it will be messy, but it sounds like it already is for you, so validators could still at least validate the messines.
Hmm, this is pretty interesting, but I still have issues. While Zod seems to be able to transform my server-returned object into a discriminated union, it doesn't seem to be able to tell which of the unions it is. For instance, say that api/user/mod-panel (e.g.) returns only moderator user objects. My API endpoint already knows that it will have moderator-related fields, but Zod forgets that when I parse it.
Then you don't use the discriminated union for that endpoint, but the schema that only accepts moderator user objects.
That's not surprising, "this endpoint will only return moderator user objects" is a bit of knowledge that has to be represented in code somehow.
You can use an ‘is’ method to pick out a type from union. Although, if union is discriminated, it’s discriminated with a ‘kind’ so you should be able to know which kind you received.
I am not totally sure what your API's look like but if you know the API only has a certain type (or subset of types), you would only validate that type on the method. Don't use a single union for everything.
Here is some pseudocode.
Person = { name: string, height: number }
Animal = {name: string, capability: string}
A = { post: object, methodType: string, person: Person }
ModeratorA = { post: object, moderatorField1: string, moderatorField2: string, person: Person }
UnionA = A && ModeratorA (There's probably a better way of defining A and ModeratorA to share the shared fields)
B = { post: object, animal: Animal }
endpoint person parses UnionA
endpoint animal parses B
You don't put all of your types in one big Union.
You can define all the different sub types separately and make the discriminated union using them. The use only a single type for an endpoint if it only uses a single type. Only use the discriminated union where you actually might be handling multiple types.
In an ideal world you'd have one source of truth for what the shape of a User could be (which may well be a discriminated union of User and AnonymousUser or similar).
Without fullstack TS this could look something like: (for a Python backend) Pydantic models+union for the various shapes of `User`, and then OpenAPI/GraphQL schema generation+codegen for the TS client.
The problem with this is that your One True User shape tends to have a bunch of optional properties on it. e.g., in the user profile you fetch Post[], but in the user directory you don't, and so on with other joined properties. If every endpoint returns the One True User, then you end up needing to write conditional logic to guard against (say) `.posts` when you fetch users in the profile, even though you know that `.posts` exists.
In Typescript at least, if the discriminated union is set up correctly, you just need a single check of the type field. That lets TS narrow the type so it knows whether e.g. `.posts` is present or not.
I think I can do this, yes, but it becomes a very large amount of repetitive work.
Let's say I have api/profile (which has `.posts`) and api/user-directory (which does not). I define User as a discriminated union - one has type `user-with-posts` and one has type `user-no-posts`. OK, good so far. But now say I have a photo gallery, which returns photos on user. Now I have to add that into my discriminated union type, e.g. `user-with-posts-and-photos`, `user-with-posts-but-not-photos`, `user-with-no-posts-but-yes-photos`... and it gets worse if I also have another page with DMs...
You can use a string union to discriminate when it makes sense, but that's not the only way to discriminate and in this case you'd instead use the presence of the items themselves (essentially duck-typing with strong type guarantees)
Typescript playground: https://www.typescriptlang.org/play/?#code/C4TwDgpgBACg9gZ2F...
Now you run into the issue I mentioned in GP, where you end up writing `if (blah)` everywhere, even though you know that `blah` is definitely present.
Change the design of the API so that the posts and the photos and so on are not returned inside the user object but on the same level as it.
So {user: {...}, photos: [...]}, not {user: {..., photos: [...]}}.
Alternatively define separate schemas for each endpoint that extend the base User schema. But I'd prefer having the same structure everywhere as much as possible.
Not sure how other stacks solve this, but with GraphQL the backend defines a `User` type with a full set of fields, and the client specifies only the fields it wants to query. And with codegen you get type safety.
So on the /posts page the client asks for `{ user: { id, posts: { id, content }[] } }`, and gets a generated properly-typed function for making the query.
It's hard to unpack without knowing more about the use case, but adding discriminant properties (e.g. "user_type") to all the types in the union can make it easier to handle the general and specific case.
E.g.
if (user.user_type === 'authenticated') {
This doesn't help in your case, but this is what GraphQL was invented for.
TS libraries for GQL queries can dynamically infer the response shape from the shape of the selected fields.
Such that the query
Would be And a query with just { user { username } } would have the posts property omitted entirely.Your server should export the types. Don't write types by hand in your client, that makes no sense. The server knows what data it is sending and should provide that information as metadata to the client. Practically this can mean that a Python backend uses Pydantic schemas which can be used to automatically generate an OpenAPI specification that your client can use to generate types.
This answer is how I wish the world would work, but I am stuck with a server with a poor type system that can't refine the types nearly as accurately as TS can. :(
Either Unions, or optional fields
Zod is a lot better than some of the alternative solutions I've seen. That said, the need for this sort of explicit validation always felt like a failure of where modern web development has taken us. It's so frustrating how full-stack development requires so many ways of describing the same shapes: JS input validation, Swagger for API definition, server-side input validation, ORM for schema conformance, and TypeScript often requiring separate definitions on server and client side. It's so tedious.
TypeScript's insistence on being a static checking/compile time only system is such a sad wound to the whole ecosystem. I don't want TypeScript to be a runtime checker, but I want it to export useful usable type data for classes, functions, objects. TypeScript feels like the best source of truth we have, but instead so many of the attempts to reflect on what we have are all going it alone, having to define their own model and their own builders for describing what stuff is. You've mentioned 5 major areas where reflection is a core part of the mission, and each of these have multiple implementations.
There is the old TypeScript type emitter, reflect-metadata, which would provide some type information at runtime, but it targets very old decorator and metadata specifications, not the current version. I don't super know how accurate or complete it's model really is, how closely it writes down what typescript knows versus how much it defines its own model to export to. https://www.npmjs.com/package/reflect-metadata
We are maybe at the cusp of some unifying, some coming together, albeit not via typescript at this time, still as a separate layer. The Standard Schema project has support from I dare say most of the top validation libraries. But extending this to API definitions, ORM tools is in extremely early stages. https://github.com/standard-schema/standard-schema?tab=readm...
> I don't want TypeScript to be a runtime checker
I do.
If the types are internally consistent, then they don't need runtime validation, it'd just be extra code to download and run.
If you accept external data, you may already opt in using something like Zod. I don't see why conflate the two things just because their quacks echo the same.
Hard agree - TSC already has this information, why should so many libraries in the world duplicate it ? A single source of truth works better than everyone repeating the same in different, finicky runtime validation libraries.
Yes. Although I am more familiar with TypeScript and prefer it for a few reasons, I've been inspired seeing how Pydantic has been used in the field for both design-time and runtime validation.
But that’s the whole point of something like this. You do it once and dynamically generate everything else downstream. So change it once in the zod schema and it propagates with type checking through your entire app.
The zod schema becomes the source of truth.
Does it? I don't use Zod on my JVM backend. How would I?
In addition to using OpenAPI, I generate TS interfaces from my data classes in a Gradle task.
One way might be to convert the Zod schema to a JSON schema and then to Java? I found a library to do that. [1] But I don’t know how lossy that would be. A purpose-built converter might do better.
[1] https://jsontypedef.com/docs/java-codegen/
Looks like there are libraries for generating zod schemas from OpenAPI definitions and others.
https://zod.dev/ecosystem?id=x-to-zod
Does zod really support that? What if the code base start out with a go backend and a TS/JS component is only added later? It would be nice if the source of truth was a bit more language agnostic.
Better to use something like OpenApi and generate your zod schema using it.
And thus is born the 15th IDL for cross language API calls...
Does it?
Most Go, Java, and Python APIs are practically all Swagger based.
You shouldn’t typically need to redefine your data all over the places. There are zillions of converters for everything to zod, and zod to everything.
If you already have JSON schema/swagger schemas, generate zod from em. If you use a typescript orm, I bet you $10 there’s a zod generator for it.
Honestly zod has gotten so popular that for me, it’s the unifying schema definition that everything else in the stack can rely on. And since directly defines the types, devs actually keep it up to date (swagger docs at my company are ALWAYS lagging behind changes)
All APIs are experimental and in a state of constant flux and evolution, including the web.
The only time status quo is fine is when it's for clients and employers who just want stuff done and don't care how.
In that context, all these unfortunate layers of complexity at least mean more billable hours.
> All APIs are experimental and in a state of constant flux and evolution, including the web.
for better or worse the web only adds, don't change or remove APIs
> It's so frustrating how full-stack development requires so many ways of describing the same shapes: JS input validation, Swagger for API definition, server-side input validation, ORM for schema conformance, and TypeScript often requiring separate definitions on server and client side. It's so tedious.
Many of the same people who complain about how complicated modern web dev is would also shudder at the suggestion to just replace all those things with TypeScript (and Zod, if that's your TS schema definition and validation library of choice).
We use drizzle + Hono + client with zod. So the entire chain from ui to client to server to DB follow same validation and shape.
How do you use the same validation for drizzle and zod? I have been writing duplicate schemas and hoping they match...
Drizzle has a zod addon, to generate zod schema from table defn. So table defn is source of truth, we mix generated zod schemas to get hono request validators. Same zod schema are also used on client to validate forms.
I've heard of this stack, glad to hear it works, still hate that you need three separate external dependencies to do it
How else would you do it? You could use something like trpc for full end to end type safety but that requires using TypeScript on both the frontend and backend (which not everyone does) and also locking yourself into only the web platform (so no mobile, etc).
Yes there should at least be a way to consolidate so that we can agree on format to treat as the source of truth that we can generate the other formats from.
OpenAPI TypeScript is the closest thing I’ve found to perfection when your API is written in a different language than your client.
https://openapi-ts.dev/
GraphQL is another one, with schema introspection and codegen for queries and types.
Zod 4 looks good but even with their latest improvements, ArkType is still an order of magnitude faster. Sometimes for the sake of backward and syntax compatibility, it is difficult to make something much faster than a fully greenfield newer library. We recently did an analysis of all these types of tools for our project and decided to go with ArkType for partially this reason, the other was TypeScript ergonomics felt nicer.
I was looking at all their speed metrics, and can you explain to me where the speed makes a difference?
We only use zod to validate forms, so I keep thinking "how does this matter?" Are people maybe using it to validate high throughput API input messages or something like that, where performance may matter more?
Yes, we use it to validate the API responses from the backend (as well as type validation on the backend itself from any frontend POST requests), and especially on the client side, speed and bundle size is very important.
Does arktype not come with a larger bundle size than zod? That was the reason I was shying away from it at the moment, especially with the bundle size reductions with zod 4 as well
[1] https://www.reddit.com/r/typescript/comments/1i3ogwi/announc...
Yeah, I can't see zod really adding that much overhead in the critical latency path for all but extremely large responses. Sometimes people pick "the fastest" library without considering whether the performance is relevant for a given code path.
Why ArkType over TypeBox?
Interesting, that one didn't even appear in my research. I was specifically looking for typescript ergonomics too. Probably still not going to switch away from Zod, though.
ArkType is a nightmare to use, zod is nice to use
Out of interest, why is it a nightmare to use?
I've always been worried about how overly clever the approach is, does it have problems?
Congratulations to the Zod team on the new release. At the risk of sounding overtly negative, I can't help but shudder when I think about the number of breaking changes outlined in the migration guide. For projects that rely heavily on Zod, it feels like a daunting task ahead—one that will demand a lot of developer attention and time to navigate. Having maintained a few frontend projects that are 4-5 years old at work, I really empathize with them.
In my experience, large React projects often depend on a multitude of libraries, and when each one rolls out substantial changes—sometimes with barely any documentation—it can quickly become overwhelming. This is honestly one of my least favorite aspects of working with JavaScript. It just feels like a constant uphill battle to keep everything in sync and functioning smoothly.
I am 100% in agreement here. I operate a couple large Next.js apps and in the last year we've had to deal with Next.js 14 -> 15 which introduced a ton of breaking cache changes, Next.js pages -> app router, React 18 -> 19, Eslint 8 -> 9, and Tailwind 3 -> 4.
It's honestly been a nightmare, and I wish I had just built in Django instead. The Tailwind 3 -> 4 migration was probably among the most painful, which I was not expecting.
I will continue to beat the drum that using easy-to-migrate frameworks like Django that don't go around introducing major breaking changes is one of the bigger web development superpowers.
Django doesn't run in the browser though. All of the tech they listed can run in the browser which gives you other superpowers at the expense of having moving targets, but that's what they opted into when they decided to run code on user machines instead of in a single server environment.
The main browser API is pretty stable, all things considered. It's just that people can't seem to stay put on a given design, instead trying everything under the sun.
When you have something like SDL which is at it's third version at 27 years old, I'm very doubtful about the culture of NPM/JS world. A closer example is jQuery which is also in its third version at 18 years old.
True, the browser API might be stable, but the best way to build stateful client applications is unstable.
It's a constantly improving and experimental domain - not just on the web but also the desktop and mobile environment.
Next.js is a good example since it (and its competitors) are a natural iteration on top of SPAs where you want the first request to the server to also inline the initial state of the SPA to remove the double-request problem.
But you pay a huge price trying to live on the edge like that, and when you run into issues, it doesn't make much sense to call that the state of web development since you could have used boring server tech or even a boring React SPA which also hasn't changed much in a decade.
jQuery should get more praise for this.
Couldn't agree more. I'm considering getting into Phoenix for this very reason.
i am just simply not touching tailwind v3 -> 4. v4 is for new projects only.
OPINION WARNING
Eslint 8 → 9 was not just incredibly painful with a shock wave that still propagates through the industry, but it was also totally useless
that's why they're taking the dual-availability approach, with a separate 'mini' edition. it's easy to perform a progressive migration without messing with the package manager.
consumers uninterested in the 'mini' edition don't have to bother with that part.
but, the benefits of the 'mini' edition are so drastic for tree-shaking that it was driving development of alternatives - zod had to either do it (and benefit), or deprecate.
Was just looking at their release strategy. This is being handled by people that have experienced the hell that is dependency management in the JS ecosystem. Kudos to them.
> For projects that rely heavily on Zod, it feels like a daunting task ahead—one that will demand a lot of developer attention and time to navigate.
Or just use an LLM.
This is the kind of task that LLMs are precisely terrible at; there isn't an abundance of Zod 4 examples, and the LLM will sure as shit will give you _something_ you are now by definition ill-equipped to assess.
I'm confident about this assessment because I maintain a large-ish piece of software and perenially have to decipher user reports of hallucinated LLM syntax for new features.
Are you sure that's not a skill issue? Zod v4 has .mdx documentation which can be given to the LLM as context, including a migration guide. A reasoning LLM should be able to manage.
"It will solve all your problems!"
"It didn't solve my problems"
"You're the problem!"
> "You're the problem!"
He said users sent reports with hallucinated syntax, he wasn't even the one who used LLMs.
I've only tried Claude in Cursor's free trial, but it became very confused during a React 19 upgrade even after showing it a guide. It also kept telling me to install irrelevant dependencies saying my code would not work without them. My experience was more or less shared with several other senior devs using their companies AI subscriptions. Are we all using the tools wrong? Or is there just an expected amount of having to fight with the machine to get a usable result?
> I've only tried Claude in Cursor's free trial, but it became very confused during a React 19 upgrade even after showing it a guide.
I have never used Cursor, but I see more and more people who used LLMs specifically via Cursor complain. It makes me think there's an issue specifically with Cursor, e.g., they try to save on tokens and end up not including enough context in the prompt.
> I've only tried Claude in Cursor's free trial, but it became very confused during a React 19 upgrade even after showing it a guide.
I am working on a Next.js 15 / React 19 app, and at least 95% of code is written by Gemini 2.5 Pro Preview, and I barely ever need to "fight" it really. But it's not a Cursor workflow of course. I keep a directory with LLM-readable documentation[0], use a repository serialization tool to serialize my repository into a prompt (this includes both the source code and the LLM-readable documentation), and send it to Gemini 2.5 Pro Preview. It ends up being over 100K tokens per query but works really well for me.
[0]: https://llmstxt.org/
And then pick through all the LLM's mistakes.
Ask another LLM to pick for you
LLMs can't even not write React when you explicitly tell them not to write React in your Vue codebase. I still, with Gemini 2.5 Pro and Claude 3.7 both, get this annoying ass interaction almost daily, despite a universe of context there that should make it obvious I don't want a React component in my Vue codebase.
Do you mean TSX? Because Vue supports that. Might be worth asking it to create a SFC file and no TSX explicitly in your case!
better yet: use an LLM to generate a subset of Zod that is fit for the project
As a full stack dev that runs their own SaaS with thousands of users in production, sometimes I get a very pleasant reminder of how many problems I am blissfully unaware of just because I decided not to build an SPA or use JS frontend frameworks. It never occurred to me that I need such a thing as Zod/ArkType - first time hearing of it, and I have no use for it.
It boggles my mind how much effort and complexity and tooling goes into building an SPA. Entire classes of problems simply don't exist if you choose not to build an SPA. Meanwhile, I use the browser as designed: with full page reloads, backend development only, and occasional reactivity using a backend-only framework like Laravel Livewire. Everything is so simple: from access control to validation to state management. And yes, my app is fast, reactive, modern, SEO friendly, and serves thousands of users in production.
I worked on two large projects that use Zod and Protobuf to ensure schema evolution goes well with 5+ teams. Even if you have a lightweight frontend, it makes sense to use something that validates the schemas in the backend.
In the end you'll have a schema somewhere. Maybe defined in the database system, maybe defined in the models of an object-relational mapper. Since defining the schemas in database system or using object-relational mappers can cause very difficult problems in large projects we do not use it and use Zod and Protobuf instead. While I think you could even replace Protobuf completely with Zod or something similar.
There is the British Post Office scandal [1] around an IT system called Horizon (the legacy system in this case). After reading about the details I'm pretty sure something like Zod (I mean any schema validation) would have contributed to prevent this scandal. They even mentioned the lack of using a schema in the technical appendices in the court documents of the group legal action [2].
[1] https://en.wikipedia.org/wiki/British_Post_Office_scandal
[2] https://en.wikipedia.org/wiki/Bates_%26_Others_v_Post_Office...
Zod has nothing to do with SPAs and isn't just a frontend tool. Do you not validate inputs in your code?
Laravel/Livewire handles it. I have no idea why something like Zod should be the concern for a high level application dev. For a framework dev, sure
Zod is basically the standalone version of Laravel's validation (https://laravel.com/docs/12.x/validation#quick-writing-the-v...) so I'm not sure what exactly you're objecting to.
Unless you're saying
a) You don't validate user inputs b) You prefer validation to be bundled with the framework rather than having a choice
In that case, your objection seems to be to light weight or minimal frameworks rather than SPAs on this point. There are plenty of minimal backend frameworks for Node (and Python, and others) that can be and are used to build traditional "load a page for every interaction" applications, and Zod or something like it would be useful for those since minimal frameworks often don't include validation. Zod isn't exclusively for SPAs or even web applications. It's schema validation, which is useful in many domains.
Well zod is for typescript, not laravel/livewire
Yeah, it's very useful to validate schemas at compile-time and runtime. It prevents several different problems to occur.
Lately, I used code agents a lot, and having typescripts types infered from Zod schemas allows me to catch errors when the large-language model generated slightly wrong code.
Entire classes of problems simply don't exist, if you also close your eyes.
Well how do you do server-side validation?
Because now I have the impression that you're just defensively writing a bunch of if-statements. Or worse, you rely on html client-side form validation only.
Any good backend framework (Laravel, Django, Livewire, Rails) does server side validation out of the box without me as a developer needing to manually pass around JSON objects and continually checking their shape. The boundary between user input and backend code is well defined and border checks are easy.
> manually pass around JSON objects and continually checking their shape
Well Zod is a library that's typically used on the boundary.
I don't know why you're assuming stuff about a library that you've never used. No one would continually check their shape once it's validated at the api boundary.
We have an enormous number of backend-only Zod schemas that are used as part of our data pipelines; so it doesn't seem like something that only exists to solve SPA problems.
If it’s backend only why do JSON shapes need to be continually checked? Can’t you serialize higher level classes or use the database?
Use the database? As in just throw user input straight into the DB without so much as checking its length to make sure it fits? Just let it error out? No sanitization, nothing?
If a JSON shape is maintained by another team, e.g. how can you know they did not change the shape without speaking with them? You could instead validate the schema and log the errors and get notified by the errors and then change your client code. This also means your client code does not need to know about the details of the database.
What's your SaaS? I would like to check out your use case that allowed you to build a great product without SPA.
Basecamp and Hey are $100m+ software companies that use Ruby on Rails without an SPA.
Yes, and it actually works. I use something like htmx or fixi [1] for my frontends of side-projects. Alternatively, I could also use laravel livewire, I even argue you could use them for large-scale projects like ERP systems. I even re-build small parts of a large ERP system including the design system implemention using htmx. No need for react or similar things, if you know HTML and CSS well and are a bit disciplined.
But once you don't use ORMs or have a non-monolithic architecture, you need something to validate your schema.
[1] https://github.com/bigskysoftware/fixi
I am not an expert here but I had a thought that JSON-Schema might be a good choice because since it's schema based, i can implement the validators in Non-Typescript languages too.
https://ajv.js.org is one such JSON Schema library. How does zod compare to this?
Well, Zod isn't just for validating JSON. It supports validating objects that can't be represented in JSON without transformation (dates, class instances, and so on). You can also use it as your JSON transformer if you want to - you can write your schema so it accepts strings, validates them as ISO date strings, and outputs Date objects, for instance.
> Well, Zod isn't just for validating JSON. It supports validating objects that can't be represented in JSON without transformation (dates, class instances, and so on).
Thanks, this was the missing piece for me. I'd been thinking about using Zod for an old client's Node codebase, but I'd only need it to validate the shape of json objects received by http endpoints. Zod was looking like overkill, but I know it's popular so I wasn't sure what I was missing.
Zod 4 supports converting a Zod schema to JSON-Schema (natively, this has always been possible with 3rd-party libs).
One key difference is preprocessing/refine. With Zod, you can provide a callback before running validation, which is super useful and can't be represented in JSON. This comes in handy more often than you'd think - e.g converting MM/DD/YYYY to DD/MM/YYYY before validating as date.
Does it support the other way around too? I'd live to ditch AJV.
It is a good choice and in that case TypeBox is a decent way to generate it.
And you can use AVJ or its own schema validation system (which is much faster, but only sync where avj has asynchronous validation options in case you want to check against a database or something).
JSON Schema is the way for cross-language validation. Wrap it in OpenAPI and you also get nice API docs for free.
Shocked by the negativity around this.
I tested early versions of zod v4 and liked the new API, but was very concerned about what will be the migration path. I was even going to suggest to publish under a new package name.
But the author's approach is ingenious. It allows for someone like me to start adopting v4 immediately without waiting for every dependency to update.
Well done!
Yeah, it's a nice route. There's no way I could afford to do an all or nothing migration for something like validation.
I just got started working Zod into a new project. This could not have happened at a better time. I would have needed to change so much ot migrate to v4 based on what I'm seeing.
We're currently evaluating both Zod and ArkType as a replacement for earlier JSON schema validations. The thing I can't get over with Zod is the syntax is _so_ different from defining TS types.
Are there reasons to go with Zod over ArkType?
You might like Typia better.
I recently put together a deck for this after some investigation: https://docs.google.com/presentation/d/1fToIKvR7dyvQS1AAtp4Y...
On the ArkType website they talk about speed and DX, but no mention of bundle size. I assume, and maybe this is an unfair assumption, that's because it's bad. I haven't come across ArkType until just now, but I was just checking out Valibot today because it's got a small bundle size.
https://bundlephobia.com/package/arktype@2.1.20: 38.3 KB
https://bundlephobia.com/package/zod@3.24.4: 64.3 KB
https://bundlephobia.com/package/valibot@1.1.0: 84.1 KB
These numbers don't reflect anything useful. This is the total size of the code in the package, most of which will be tree-shaken. In Zod's case, the package now contains three independent sub-libraries. I recommend plugging a script into bundlejs.com[0] to see bundle size numbers for a particular script
[0] https://bundlejs.com
We also chose ArkType after evaluating Zod, Valibot, and Effect Schema, among others. It seemed to have the best developer experience while also being much faster. It also supports the Standard Schema project which I believe Effect Schema does not fully support.
Could you elaborate on how exactly do you use these? I was assuming its for some kind of contract testing, but there are mentions of bundle size, is it used on fetching data to fail early if the format is wrong, something like that?
I believe Effect Schema fully supports Standard Schema, the issue is that it supports much more than Standard Schema, so not all schemas will work and thus provide compile time errors.
Yes that's correct, it's more powerful but we wanted to maintain full compatibility just for the future as well. But if you're all in on the Effect ecosystem, it's quite nice.
Does ArkType support generating data from schema?
Everyone else is using Zod so the LLMs understand it well, there’s a big ecosystem, it’s unlikely to disappear overnight, and new hires may well already use it. It’s the boring solution.
With yet another exciting new release of something reaching the top of HN, I would just like to urge devs to put a description of the project they're actually releasing and a link to the page describing the project in the release announcement.
These announcements could be a valuable touchpoint for you to reach a whole new audience, but I can't remember a single one that starts with something like "exciting new release of NAME, the X that does Y for users of Z. Check out the project home page at https:// for more."
Quite often, the release announcement is a dead end that can't even take me to the project! In this case, the only link is a tiny octocat in the lower left-hand corner, AFAICS.
I came here to say this. I clicked on the link and had no idea what this was about.
The next step is to click the project logo in the top left.
The little animation that highlights what section you are reading currently is beautiful
This is a feature of Fumadocs that the site uses!
[1] https://fumadocs.dev/
What animation? I actually do not see it.
Hopefully someone can compare Zod4 to TypeBox.
Last I looked, the nice thing about TypeBox was that is _was_ JsonSchema just typed which was nice for interoperability.
I was using TypeBox but switched to Zod. I like TypeBox but I found I don't actually need my schema to be a JSON Schema and the one time I did want a JSON Schema it was hard to get actual JSON back out of TypeBox.
The thing I like about Zod is the "refinements" and "transforms" and the new "overwrite" in Zod 4 was just what I wanted.
TypeBox does have a transform (https://github.com/sinclairzx81/typebox?tab=readme-ov-file#t...) but you can't transform and then apply more validations and then maybe another transform, etc. For example, I like to trim strings before checking length.
> TypeScript-first schema validation with static type inference
Is there a comparison guide? Never heard of this before, but I used io-ts and ajv.
The versioning approach here is a really interesting compromise — especially in the npm ecosystem where breaking changes ripple out so painfully through transitive dependencies. From a developer ergonomics standpoint though, the shift to zod/v4 imports will definitely create some friction. For teams with IDEs auto-importing from 'zod' and linters enforcing import styles, it might introduce subtle DX issues until workflows are adjusted.
That said, the strategy does seem to prioritize ecosystem stability over short-term convenience, which is fair. Would love to see better tooling (maybe even IDE plugins or codemods) to help projects transition cleanly. Really appreciate the thoughtful design behind all of this.
Seeing v4-mini reminds me of an LLM. I can only assume the next major release will be zod-3.9-medium-high
Or maybe 3.8-q4_K_M for a quantized version
One decision that seems dubious to me is the zod/v4-mini import. I suspect that this will actually increase bundle sizes across the ecosystem. The docs specifically say "zod/v4 is still recommended for the majority of use cases", so application developers will use it. Library authors will think to themselves, "but I want to enable my library to be used by those with uncommonly strict bundle size requirements", and so will use that. The net result is that both zod/v4 and zod/v4-mini will be included in the application bundle.
I guess this could be mostly avoided if zod/v4 actually a wrapper around zod/v4-mini. Is that the case?
Library authors should only import from `core`, which is used by both v4 and v4-mini.
ref: https://zod.dev/library-authors?id=how-to-support-zod-and-zo...
Glad to see that this was also considered. I’m curious why they went with a third API, though.
But how is the below possible - doesn't it need to include most of the TypeScript compiler? Does it compile the type definitions to some kind of validation structure (like how a compiled regex works) and then use just that?
The TypeScript compiler is only needed during development, the compiled JavaScript code contains no TypeScript-specific logic. Zod’s validation is entirely JavaScript-based, relying on simple checks (e.g., typeof, regexes, comparisons).
Also, the 2kb bundle just for the zod/v4-mini package, the full zod/v4 package is quite large.
5.36kB is not "quite large". It's pretty reasonable, esp. if you're only running it on the server.
I think Zod uses JIT compilation via `new Function`, rather than including the entire TypeScript compiler. This method allows for concise validation logic, executing only what’s necessary at runtime.
The library pretty much remained unusable garbage without documentation comments. I have no idea why it became so popular and why this release is named "stable" when there is even no 4.0.0.
Great job! I love support of json conversion you built-in. However, I find top level string bad choice as it was more verbose before, to have them under string() namespace.
Zod and the way to define schemas with it has been one of the reasons I didn't want to touch TypeScript as it's becoming more prevalent!
Can you elaborate?
It defines yet another way to declare schemas in a way that's not reusable. ArkType mostly uses TypeScript's, so, it feels more natural.
That's going in the wrong direction IMO. TypeScript checks types only, not business logic. Zod does both.
Zod's way to check business logic is extremely underpowered and, again, it's not reusable!
We've been using zod for our open source tool and are loving it! Will definitely try to migrate over to v4 soon, thanks for the project!
The website fails to load with a javascript error in Safari.
`SyntaxError: Invalid regular expression: invalid group specifier name`
Looks like this feature is not yet supported in Safari.
Lookbehind in JS regular expressions - https://caniuse.com/js-regexp-lookbehind
Defining schemas in zod and using z.infer<> to get my types is just lovely, thank you!
All that text. So, so much text and not one single (maybe there was, but I fell asleep), not one single "Let me tell you what Zod is" paragraph. Lots of "Zod 4 is better than Zod 3" and "Here's what we pulled back, out, in, from Zod 2".
there's an 'Intro' link under the 'Documentation' header on the left side
"TypeScript-first schema validation with static type inference"
great job on zod. it’s an incredible library. also really excited about the locale errors. finally I can push the zod errors directly to the frontend. would love to take responsibility for the BG locale.
Impressive results, we need some deep dive on the performance improvements!
Obligatory shameless plug whenever Zod is posted: if you want similar, but much more minimal schema validation at runtime, with a JSON representation, try Spartan Schema: https://github.com/ar-nelson/spartan-schema
When I see a repository with many files "updated 4 years ago" I'm usually inclined to think it's abandoned.
Or the code is done and doesn’t need to be iterated on continuously?
Then say so in the readme :)
Hard to please everyone
Who else here is going to the Zod meetup tonight?
Wow! This is great!!!
What is it?
Zod, version 4
Which tells me less than what the link to the web site tells me.
i would use it if there was just 1 normal zod lib not like how it is now: zod and zod mini and who knows what. I rather use arktype or valibot if i am in browser only.
hmmm. Zod on Zed?
Still no hapi support?
[dead]
Mind blowing.
I read this, and I find myself not wanting to migrate since I know that LLMs can't generate Zod 4 syntax yet.
Seeing an announcement for a new version of some typescript library I've never heard of shoot to the top of the front page makes me feel extremely out of touch with mainstream dev.
What do you use for validation in TS? Anyone who deals with data should be validating/parsing it.
Effect Schema (the next incarnation of fp-ts/io-ts) is my go-to for parsing external data in TypeScript, and I heavily recommend it.
Great if that's the only validation you need, but I can't imagine using it in a real app, and there are some obvious bugs (e.g. never use `instanceof Array`).
Array.isArray isn't needed when you know your array isn't going to be deserialized e.g. via MessagePort. What other supposed bugs?
And yes I'm aware this doesn't have a huge API surface. That's the whole point. If I already have a JSON object, I can reach into it and get either what I ask for or nothing. In many real world cases, this is enough.
> I mean, it's probably fine if you're only ever getting your data from JSON.parse().
So 90% of use cases?
Sure, and then only 10% of your use cases contain easily exploitable vulnerabilities.
You use a different function than Validate_Parsed_JSON in those cases. But most typescript programs are only going to need JSON-compatible input. Maybe some XML but that's also going to have similar formulaic output from your parser.
If something can directly hand you a maliciously built data structure, you're probably designing your system wrong. Are you running untrusted javascript in the same interpreter? That's a very hard problem that should be avoided if at all possible.
Basically, only working on JSON.parse is something to document but it's not at all a weird restriction, or a reason to balk at putting it into production.
The point is that it's layered.
1. Validate your Buffer/UInt8Array for valid size/encoding/etc first
2. Parse it to an object via JSON.parse or whatever your use-case needs
3. Reach into it with this function to get data if it matches the type you need
This code only deals with #3 and makes a few assumptions about #2 (e.g. no undefined, typical JSON-like object, etc).
If you don't do web dev (or at least, the latest web dev) then it's understandable, I often see lots of posts in the top spots whose languages I have no idea about either.
Zod is quite common, if not the most used validation library for JS/TS projects.
Between GraphQL and Zod, there really is no comparison. The latter feels clunky and superfluous by design when the former ecosystem can smoothly provide static TS typings without extra work or schema duplication.
Also, I think teflon pans are much better than squids.
Squid ink is black so are teflon pans, the latter feels clunky and superfluous by design when the former type of fruit can smoothly provide vitamins to vertically integrate with our stack.
Ah yes two totally different technologies - let's compare them like they're designed to solve the exact same problem
GraphQL is a different animal, but I was only comparing the features Zod implements to those found in the GraphQL ecosystem.