@hono/zod-validator

@hono/zod-validator is the official validation middleware for the Hono web framework, bridging Zod’s schema-based validation into the request pipeline. Define a Zod schema, wrap it in the zValidator helper, and every incoming JSON body, query string, route parameter, form field, or header is validated before your handler runs.

Beyond runtime checks, the middleware infers the fully-typed validated value so c.req.valid('json') returns a strongly-typed object with no manual casting. It supports both Zod v3 and v4, custom validation functions, and error hooks that let you shape or short-circuit invalid responses.

What You Get

• A single zValidator helper that validates any request target: json, form, query, param, header, or cookie
• End-to-end type inference so c.req.valid(target) returns the schema’s output type with no manual casting
• Support for both Zod v3 and Zod v4 schemas from the same API
• An optional hook to customize error responses or throw instead of returning the default 400
• A validationFunction option to override the default safeParseAsync behavior (e.g. passthrough parsing)

Common Use Cases

• Validating and typing JSON request bodies for REST and RPC-style Hono APIs
• Guarding query strings and route parameters before business logic executes
• Normalizing and validating request headers with case-insensitive key matching
• Returning consistent, structured 400 error payloads for malformed input

Under The Hood

Architecture The entire package is a single src/index.ts that exports one function, zValidator, aliased over an internal zValidatorFunction. That function delegates to Hono’s built-in validator(target, cb) from hono/validator, supplying an async callback that runs the schema against the request target. When the target is header, it first remaps Hono’s lowercased header keys back to the schema’s original keys via a case-insensitive keymap. It then calls schema.safeParseAsync (or a user-supplied validationFunction), passes the result through an optional hook, returns c.json(result, 400) on failure, and otherwise hands the typed result.data back to Hono to expose via c.req.valid(target).

Tech Stack Written entirely in TypeScript and shipped as dual ESM/CJS via tsdown. It declares hono (>=4.11.2) and zod (^3.25 || ^4) as peer dependencies, so it carries no runtime dependencies of its own. It publishes to npm with provenance and also targets JSR/Deno (a deno.json is present). Tests run under Vitest.

Code Quality The package is small but heavily type-driven: overloaded signatures distinguish the hook and non-hook call forms, and conditional types (ZodError, zInfer, ExtractValidationResponse) derive precise input/output and error-response types across both Zod v3 and v4. Test coverage is explicit, with separate v3.test.ts and v4.test.ts suites exercising each supported Zod major version. A handful of @ts-expect-error pragmas bridge the two Zod type systems where their internal shapes diverge.

API Design The public surface is a single, well-named zValidator(target, schema, hook?, options?) helper, which keeps the learning curve low: one import, one call per route. Type inference means callers rarely annotate anything, and the README documents the common patterns (basic validation, error hooks, throwing errors, custom validation functions) with concise runnable snippets.