Support for Zod 4

[colinhacks]

I'm posting this issue to all the libraries currently listed in the Ecosystem section of Zod's README. Apologies for the spam! Zod 4 is a big release and it's important to get as much of the ecosystem migrated as possible! 👍

Zod 4 is now in beta

Hello! Colin here, creator of Zod. Thank you for contributing this package to the Zod ecosystem!

FYI, the first beta of Zod 4 has been released. It will be in beta for 4 weeks to allow time for ecosystem libraries (such as yours) to implement support before the first stable version is released. The first stable release will be in mid-May. Keep an eye on this PR to track progress: colinhacks/zod#4074

Announcement post: https://v4.zod.dev/v4
Migration guide: https://v4.zod.dev/v4/changelog

⚠️ Note — To avoid confusion and outdated information, the Ecosystem page for Zod 4 is starting from scratch. You'll need to implement support for Zod 4 (guidance below). Once you've done that, submit a PR adding yourself to this file: https://github.com/colinhacks/zod/blob/v4/packages/docs/components/ecosystem.tsx

Migration

There have been some significant changes.

• A new library @zod/mini has been released with a treeshakable/functional API that mirrors Zod's
• To facilitate code sharing between zod and @zod/mini, they both have a dependency on a new common core library @zod/core.
• This new package implements the schema subclasses that are then extended by zod and @zod/mini (and potentially future libraries). It makes it easy to support all these libraries simultaneously, with just one peerDependency on your end. There is little reason for any framework/library to depend directly on zod anymore.

pnpm install @zod/core@^0.0.1

This page is intended as a jumping-off point with some guidance for library authors: @zod/core docs

Don't hesitate to reach out for help/guidance!

• Post to the #zod4 channel on the Discord
• Open an issue/discussion on the repo
• DM me on Discord or X

[RobinTail]

New version of the framework now supports Zod 4: ^24.0.0-beta.1.

Because the versioning strategy of Zod has changed since the original message above, the minimum supported version of Zod is 3.25.1, BUT (and this is important) all imports must be from "zod/v4".

This is a breaking change. The framework does NOT support both Zod 3 and Zod 4 simultaneously due to:

• incompatibility of data structures;
• operating composite schemas (need to avoid mixing schemas of different versions);
• the temporary nature of this transition;
• the advantages of Zod 4 that provide opportunities to simplifications and corrections of known issues.

In particular, the new version utilizes the new feature of Zod 4 on making JSON Schema for including it into the generated Documentation. Thus, the most of the schema depiction logic is now delegated to Zod 4.

There are some other minor breaking changes related to adopting Zod 4 — described in the Changelog.
There is an automated migration script (using ESLint) that can change all the imports and make other arrangements.

Users are encouraged to try v24 and write their feedback.
The PR for baking the future stable release: #2546

[RobinTail]

v24.0.0-beta.2 is out 🚀

This version addresses another major opportunity offered by Zod 4 — storage for schema examples.
Since Zod 4 offers the .meta({ examples }) method, I wanted to utilize its power.
However, in opposite to previously implemented framework's examples, those are typed as z.output<> and this is a breaking change.

• The ZodType.example() (the plugin method) now acts as an alias for ZodType::meta({ examples });
• The argument has to be the output type of the schema (used to be the opposite);
• This change is only breaking for transforming schemas;
• In order to specify an example for an input schema the .example() method must be called before .transform();

  input: z.string()
+   .example("123") // place for input examples
    .transform(Number)
-   .example("123") // moves to position before transformation

Also, the getExamples() public helper removed — use .meta()?.examples instead;

[RobinTail]

v24.0.0-beta.3 is out 🚀

This time I take one more step forward to native Zod 4's metadata system.
Improved handling of request examples (whichever they way they are set) by approaching them in a postprocessing step.
Addressing the related issue on proprietary transforming and branded schemas ez.dateIn() and ez.dateOut().
Provided a convenient interface for setting metadata as an argument of those schemas, so that ez.dateIn() examples could be set before internal transformation AND providing the way to avoid examples "branding".

- ez.dateIn().example("2021-12-31");
+ ez.dateIn({ examples: ["2021-12-31"] });

[RobinTail]

v24.0.0-beta.4 is out 🚀

• featuring the retention of descriptions for proprietary ez.dateIn() and ez.dateOut() schemas;
• better handling for cases when ZodError does not inherit from Error;
• clenup and polishing;

v24.0.0-beta.5 🚀

• Compatibility fix for Documentation generator with latest Zod release 3.25.28.

v24.0.0-beta.6 🚀

• Additional fix for deduplicating circular references in the generated Documentation by taking the uniqueness of .meta({ id }) into account

[RobinTail]

v24.0.0-beta.7 is out 🚀

• Changed the path format in the error message from slash-separated to dot-seperated one (zod core helper):
  • I'm not gonna gonna use z.prettifyError() because its prettiness is questionable to me due to the usage of icons/symbols (such as ❌ and ➡️ ) which I believe should be the responsibility and the decision of a particular UI, as well as \n separator and -offsets, that is also not yet configurable.
• The feature of pulling from object props made a default behavior (in betas before it was exclusive feature of defaultResultHandler), so now it's back to how it worked for custom result handlers in v23.

I'm probably gonna make a couple more minor adjustments, but overall I'm glad how it works in this state.
The stable release of v24 is planned for June, which is on the next week.

[RobinTail]

v24.0.0-beta.8 🚀

• Introducing the proprietary schema ez.buffer();
• The proprietary schema ez.file() removed in order to avoid confusion with the new z.file() of Zod 4;
• ez.file() used to be a hint for the generated Documentation that can be now replaced with either z.string(), z.base64() or the new ez.buffer().

[RobinTail]

v24.0.0-beta.9 🚀

I paired with an AI to perform the final polishing and make small improvements:

• Small performance tuning and code clarity adjustments;
• Added types generation for z.never(), z.void() and z.unknown() schemas;
• The fallback type for unsupported schemas and unclear transformations in response changed from any to unknown;

[RobinTail]

v24.0.0-beta.10 🚀

There was I minor breaking change within internal implementation of Zod's discriminated union schema in version 3.25.35.
This version addresses it as well as provides a backwards compatibility support.

[RobinTail]

v24.0.0-beta.11 🚀

I decided to elevate the min Zod version to 3.25.35 taking advantage of the fact that the stable v24 is not yet released, so that I could remove the backward compatibility fix and keep the code cleaner.
The latest release of Zod also fixed its portability issue regarding z.iso, so I'm removing another workaround for ez.dateIn()

[RobinTail]

v24.0.0 🚀

Stable release is out 🥳
All changes and specifics described in the release notes: https://github.com/RobinTail/express-zod-api/releases/tag/v24.0.0

[maximilianhurl]

🎉 This is great stuff. Thanks for getting to this so quickly!