This library wraps Zod validation errors in more user-friendly, readable messages, with options to customize formatting. It helps you return or display validation feedback for end users while still preserving the original Zod error details in `error.details`, and it supports Zod v3 and v4.
Project status
- Actively maintained: The repo shows a very recent upstream push (2026-06-04), and there have been multiple version updates in late 2025 (including a major update plus a compatibility-focused patch on the same day).
- Update cadence: Documented updates appear in a relatively steady window, with a patch in mid-September 2025 (v4.0.2) followed by major and patch updates in early November 2025 (v5.0.0, v3.5.4), suggesting ongoing iteration rather than maintenance only.
AI summary generated Today
Recent updates
v5.0.0
7 months agov5.0.0 is a major release that refactors the library’s errorMap output so messages are more consistently phrased as “expected ...”. It also introduces a new reportInput option to control whether the produced error text includes the user’s input details.
BreakingFeaturesv3.5.4
7 months agov3.5.4 is a patch release focused on restoring compatibility with Zod v3.24.4. The documented change is reverting the use of the `zod/v3` import paths so that the package works with the older Zod typings.
v4.0.2
8 months agov4.0.2 is a patch release that specifically improves how the library formats validation errors coming from zod.discriminatedUnion. The change centers on error mapping logic and associated tests, with no explicit breaking-change notes in the release notes beyond “improve handling for zod.discriminatedUnion errors.”
v4.0.1
10 months agov4.0.1 is a patch release focused on improving how Zod union validation issues are converted into user-friendly error messages. The release notes mention specifically handling missing path information for the "invalid_union" issue type.
v.4.0.0
10 months agoRelease v4.0.0 makes the v4 implementation the default export, adds support for Zod v4 (as a peer dependency), and restructures the API to separate error mapping from message building. The code diff shows more than just wiring changes, it also moves significant responsibility for formatting and path handling from the error mapper to the message builder, with corresponding option and export surface changes.
Breakingv3.5.2
11 months agov3.5.2 makes a patch-level change to how validation messages are built for Zod invalid union errors, specifically around including the paths of nested/sub-issues. It also updates tests and snapshots to reflect the new message composition behavior.
v3.5.1
11 months agov3.5.1 is a patch release focused on improving compatibility with older Node versions and module resolution, along with documentation updates. The code diff shows a larger packaging refactor, splitting build outputs into separate v3 and v4 directories and adjusting published entrypoints.
v3.5.0
12 months agoRelease v3.5.0 adds support for Zod v4. The code diff shows a new v4-specific implementation (ValidationError, error mapping, message builder) and supporting utilities for formatting paths and values, plus an update to joinPath to handle broader property key types like symbols.
BreakingFeaturesv3.4.1
5/6/2025v3.4.1 primarily updates the zod dependency to 3.24.4. However, the repository configuration also switches the test runner from Jest to Vitest, which is not mentioned in the release notes.
Breakingv3.4.0
9/16/2024v3.4.0 introduces a new MessageBuilder abstraction and refactors existing error-message generation to use it. The release notes mention customizing error messages, but the code also adds new public exports and changes the accepted options shape for fromZodIssue and fromZodError to support supplying a custom messageBuilder function.
Features