@wthek/zod-express-interceptor

Official @wthek Extension – Zod Express Interceptor for http-error-kit

Seamlessly intercept and transform Zod validation errors in Express using http-error-kit — no clutter, just clean error handling

Built for Express projects using http-error-kit, this interceptor captures Zod validation errors and converts them into structured HttpError.BadRequest responses.

💡 What the HEK?! Still manually catching Zod errors in every route? Let @wthek/zod-express-interceptor intercept them globally and standardize your error flow.

Features

• Express-native – Built specifically for Express request/response lifecycle
• Automatic ZodError Handling – Captures Zod errors and transforms them into HttpError.BadRequest
• Built on WTHek stack – Fully compatible with @wthek/express-middleware
• Keeps raw Zod issues – Sends all validation issue data in structured details
• Plug-and-play logic – Minimal setup, no need to wrap schema validation manually
• Composable – Can be used alongside @wthek/*-middleware extension

Table of Content

• Installation
• Usage
• Explore More WTHek Extensions
• People
• Donations
• License

Installation

npm install @wthek/zod-express-interceptor

Usage

Add Middleware Just Before defining Routes

Use KitZodExpressInterceptor after your route definitions, but before the final error-handling middleware like @wthek/express-middleware.

This ensures Zod validation errors are transformed into http-error-kit errors early, allowing WTHek or any other middlewares to handle them cleanly.

If the interceptor is placed before your routes, it won't catch the Zod errors since those are thrown inside route execution — after middleware execution phase.

import express from 'express';
import { z } from 'zod';
import { KitZodExpressInterceptor } from '@wthek/zod-express-interceptor';
import { KitExpressMiddleware } from '@wthek/express-middleware';

const app = express();

app.use(express.json());



app.post('/user', (req, res) => {
    const schema = z.object({
        name: z.string(),
        age: z.number().min(18),
    });

    const parsed = schema.parse(req.body); // Will throw if invalid
    res.send({ status: 'ok', parsed });
});

// ✅ Place interceptor BEFORE your routes
app.use(KitZodExpressInterceptor());

// ✅ Global error handler (after routes)
app.use(KitExpressMiddleware());

app.listen(3000);

Optional: Custom Formatting with KitHttpErrorConfig

To define how your error responses look in production:

import { KitHttpErrorConfig } from "http-error-kit";

KitHttpErrorConfig.configureFormatter(
    (statusCode, message, details, ...args) => ({
        code: statusCode,
        msg: message,
        extra: details,
        traceId: args[0] || "0fcb44cb-4f09-4900-8c4f-73ddd37ffe0a",
    })
);


// Response
{
    "code": 400,
    "msg": "Zod validation failed",
    "extra": {
        "issues": [
            {
                "code": "too_small",
                "minimum": 18,
                "type": "number",
                "inclusive": true,
                "exact": false,
                "message": "Number must be greater than or equal to 18",
                "path": ["age"]
            }
        ]
    },
    "traceId": "0fcb44cb-4f09-4900-8c4f-73ddd37ffe0a"
}

Explore More WTHek Extensions

The WTHek ecosystem continues to grow with new extensions to simplify error handling across various frameworks and libraries. Stay updated with the latest tools that integrate seamlessly with http-error-kit.

Check out the official list of extensions: Official Extensions List

People

The original author of the project is Himanshu Bansal

Donations

This is all voluntary work, so if you want to support my efforts you can

• Buy Me A Coffee
• Paypal
• GitHub Sponsor
• Patreon
• Open Collective

You can also use the following:

License

@wthek/zod-express-interceptor project is open-sourced software licensed under the MIT license by Himanshu Bansal.