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.

GitHub Workflow Status

npms.io (final) npm npm bundle size (version) NPM Type Definitions

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

Installation

npm install @wthek/zod-express-interceptor

Usage

Add Middleware Just Before defining Routes

Use KitZodExpressInterceptor in your error pipeline before routes and global 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 after your routes, Zod errors will bypass it and reach the final error handler in raw form.

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());

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

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 });
});

// 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

You can also use the following:

License

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

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