express-zod-validations

0.1.1 verified Sat May 09 auth: no javascript

Express middleware for validating request headers, params, query, and body using Zod schemas. Current stable version 0.1.1, released as the sole version to date. It offers granular validation (each request part independently), async validation by default via safeParseAsync, and flexible error handling (store errors on req or throw to Express error handler). Ships TypeScript declarations. Requires peer dependencies express ^5 and zod ^4, which are breaking changes from express v4/zod v3 ecosystem. Differentiates from express-zod-safe by requiring explicit version compatibility and providing a middleware factory for global configuration.

Common errors

error Cannot find module 'express-zod-validations' or its corresponding type declarations. ↓

cause Package not installed or missing TypeScript declaration resolution.

fix

Run npm install express-zod-validations. Ensure tsconfig.json has 'moduleResolution': 'node' (or 'bundler') and 'esModuleInterop': true.

error TypeError: req.validationValues is undefined ↓

cause Middleware not applied before route handler, or middleware configuration resets validationValues.

fix

Ensure validateBody() (or validate) is used as middleware on the route. Do not spread middleware return value.

error Error [ERR_REQUIRE_ESM]: require() of ES Module /node_modules/express-zod-validations/index.mjs not supported. ↓

cause Package is ESM-only and cannot be required() in CommonJS context without transpilation.

fix

Use import syntax or set type: 'module' in package.json. Alternatively, use a dynamic import: const { validateBody } = await import('express-zod-validations').

Warnings

breaking Requires Express v5 (peer dependency express ^5). Express 5 has breaking changes compared to Express 4 (e.g., async error handling, middleware signatures). ↓

fix Use Express 5 exclusively; do not use with Express 4.

breaking Requires Zod v4 (peer dependency zod ^4). Zod 4 introduces breaking changes from Zod 3 (e.g., new API for coerce, nullable, etc.). ↓

fix Upgrade to Zod 4 and adjust schemas per Zod 4 migration guide.

deprecated No deprecated features reported in this early version.

gotcha By default, throwErrors is false and validation errors are stored in req.validationErrors. If you use throwErrors: true, errors are passed to next(error) and must be handled by Express error middleware; otherwise the request will hang. ↓

fix Ensure an Express error handler is registered when throwErrors is true, or use default false and check req.validationErrors manually.

gotcha When overwriteRequest is true, the original req.body, req.params, etc. are replaced with parsed values. This may bypass original type declarations. ↓

fix Use overwriteRequest: false (default) and access validated data via req.validationValues to preserve original request properties.

Install

npm install express-zod-validations

yarn add express-zod-validations

pnpm add express-zod-validations

Imports

validateBody

wrong

import validateBody from 'express-zod-validations'

correct

import { validateBody } from 'express-zod-validations'

Named export, not default

validate

wrong

const validate = require('express-zod-validations').validate

correct

import { validate } from 'express-zod-validations'

ESM-only package; CommonJS require may not work without bundler

expressZodValidations

wrong

import { expressZodValidations } from 'express-zod-validations/middleware'

correct

import { expressZodValidations } from 'express-zod-validations'

Global config factory, not from subpath

validateParams

import { validateParams } from 'express-zod-validations'

Named export for params validation

validateQuery

import { validateQuery } from 'express-zod-validations'

Named export for query validation

validateHeaders

import { validateHeaders } from 'express-zod-validations'

Named export for headers validation

Quickstart

Sets up an Express server with Zod body validation middleware using validateBody, checks for errors stored on req, and responds accordingly.

import express from 'express';
import { z } from 'zod';
import { validateBody } from 'express-zod-validations';

const app = express();
app.use(express.json());

const userSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
  age: z.number().int().positive().optional(),
});

app.post('/users', validateBody(userSchema), (req, res) => {
  const user = req.validationValues.body;
  if (req.validationErrors?.body) {
    return res.status(400).json({ errors: req.validationErrors.body.errors });
  }
  res.json({ message: 'User created', user });
});

app.listen(3000);