Registry / http-networking / express-zod-safe

express-zod-safe

library3.2.1jsnpmunverified

Express Zod Safe is a TypeScript-first middleware for Express.js applications, offering robust and typesafe validation of incoming HTTP request bodies, URL parameters, and query strings. It leverages Zod schemas to define validation rules, ensuring data integrity and preventing invalid or malicious data from reaching application logic. The current stable version is 3.2.1, which targets Zod v4.0.0 and above. While a specific release cadence isn't published, it appears to follow Zod's major version updates. Key differentiators include its strict type safety, seamless integration with the Express middleware stack, comprehensive coverage of request parts (body, params, query), and developer-friendly error handling, aiming to be a more robust alternative to similar packages like `zod-express-middleware`.

http-networking web-framework serialization

npm install express-zod-safe

github ↗package ↗

INSTALL

IMPORT

SIG · EXPRESS-ZOD-SAFE

express-zod-safe

http-networkingjavascriptv3.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

validate

✓ import validate from 'express-zod-safe';

✗ import { validate } from 'express-zod-safe';

`validate` is a default export, not a named one. Importing it with curly braces will result in an undefined value.

ValidatedRequest

✓ import type { ValidatedRequest } from 'express-zod-safe';

✗ import { ValidatedRequest } from 'express-zod-safe';

`ValidatedRequest` is a TypeScript type helper. Using `import type` ensures it's stripped from the compiled JavaScript output.

✓ import { z } from 'zod';

✗ import z from 'zod';

`z` is the primary named export from the `zod` library, essential for defining schemas. It is not exported by `express-zod-safe` itself.

This quickstart demonstrates how to set up an Express route with `express-zod-safe` to validate URL parameters, query strings, and the request body using Zod schemas, including basic error handling.

import express from 'express'; import validate from 'express-zod-safe'; import { z } from 'zod'; const app = express(); app.use(express.json()); // Essential for parsing JSON bodies // Define your Zod schemas for request parts const userParamsSchema = z.object({ userId: z.string().uuid(), }); const userQuerySchema = z.object({ age: z.coerce.number().optional().default(18), // Coerce string to number, provide default country: z.string().min(2).max(2).optional() }); const userBodySchema = z.object({ name: z.string().min(1, 'Name is required'), email: z.string().email('Invalid email address'), isActive: z.boolean().default(true) }); // Use the validate middleware in your route definition app.post('/user/:userId', validate({ params: userParamsSchema, query: userQuerySchema, body: userBodySchema }), (req, res) => { // Access validated data directly from req.body, req.params, req.query console.log('Validated user ID:', req.params.userId); console.log('Validated age:', req.query.age); console.log('Validated body:', req.body); res.status(200).json({ message: 'User data is valid!', data: { userId: req.params.userId, age: req.query.age, ...req.body } }); }); // Basic error handling middleware for Zod errors app.use((err: any, req: express.Request, res: express.Response, next: express.NextFunction) => { if (err instanceof z.ZodError) { return res.status(400).json({ errors: err.issues }); } console.error(err); res.status(500).send('Something broke!'); }); const PORT = process.env.PORT || 3000; app.listen(PORT, () => console.log(`Server running on port ${PORT}`));

Debug

Known issues

breakingExpress Zod Safe versions are tied to Zod major versions. For `express-zod-safe@3.x.x`, Zod v4.0.0 or higher is required. Older versions like `express-zod-safe@1.5.4` are compatible with Zod v3.x.x. Using incompatible versions will lead to runtime errors or incorrect validation behavior.

fix

Ensure your installed `express-zod-safe` package matches the major version of your `zod` package. Upgrade `zod` to `^4.0.0` for `express-zod-safe@3.x.x` or downgrade `express-zod-safe` to `1.5.4` for `zod@3.x.x`.

affects: >=3.0.0

gotchaThe `validate` middleware *must* be placed after any other middleware that parses or modifies the request body, such as `express.json()` or `express.urlencoded()`. If `validate` is used before a body parser, `req.body` will be undefined, and body validation will fail or report an empty object.

fix

Always ensure `app.use(express.json());` (or similar body parsing middleware) is called *before* any route or middleware that uses `express-zod-safe`'s `validate` function.

affects: >=1.0.0

gotchaAll query parameters and URL parameters are strings by default in Express. When using Zod schemas for these, use `z.coerce.<type>()` (e.g., `z.coerce.number()`, `z.coerce.boolean()`) if you expect non-string types. Failing to coerce will result in validation errors for non-string input that looks like numbers or booleans.

fix

For query and path parameters that are expected to be numbers, booleans, or dates, use `z.coerce.number()`, `z.coerce.boolean()`, `z.coerce.date()`, etc., in your Zod schemas.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot destructure property 'params' of 'undefined' as it is undefined.

Attempting to use `validate({ params, query, body })` without providing one of the schema objects (e.g., `params` was not defined or passed as `undefined`).

fix

Ensure all properties (`params`, `query`, `body`) passed to `validate` are defined Zod schemas or empty objects (`z.object({})`) if not needed, instead of being `undefined`.

ZodError: [ { code: 'invalid_type', expected: 'object', received: 'undefined', path: [], message: 'Expected object, received undefined' } ]

This typically occurs when `express.json()` or another body-parsing middleware is missing or placed after the `validate` middleware, leading to an undefined `req.body`.

fix

Add `app.use(express.json());` (or `express.urlencoded()`) early in your middleware chain, ensuring it runs *before* any route handlers or middleware that use `express-zod-safe`.

Argument of type 'Request<Params, ResBody, ReqBody, ReqQuery>' is not assignable to parameter of type 'object'.

TypeScript error when trying to infer types for `req.body`, `req.params`, or `req.query` in a route handler without using the `ValidatedRequest` utility or correctly typing the handler.

fix

Use the `ValidatedRequest` type from `express-zod-safe` to correctly type your Express `Request` object. For example: `app.post('/user', validate({ body: userSchema }), (req: ValidatedRequest<typeof userSchema>, res) => { ... });`

Upgrade

Version history

3.2.1latest on npm

Audit

Dependencies

expressrequiredCore web framework integration, peer dependency.

@types/expressrequiredTypeScript typings for Express, peer dependency.

zodrequiredSchema definition and validation library, peer dependency.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/AngaBlue/express-zod-safe ↗

packagehttps://www.npmjs.com/package/express-zod-safe ↗