👉 View on npm

A lightweight, production-ready error handling toolkit for Express.js applications — written in TypeScript with full support for both CommonJS and ESM.

If you like the project, please give the project a GitHub ⭐

It provides:

• Custom error classes (NotFoundError, BadRequestError, ValidationError, etc.)
• Express middleware: globalErrorHandler, notFoundHandler
• An asyncHandler utility to handle async errors without boilerplate
• A httpError() factory function to create custom error instances easily
• isCustomAPIError() type guard for safe error type checks

• ✅ Type-safe custom error classes
• ✅ Centralized error-handling middleware
• ✅ Async error wrapper for route handlers
• ✅ Built-in 404 (Not Found) handler
• ✅ Factory method for generating custom errors
• ✅ Type guard for runtime error checking
• ✅ Out-of-the-box support for both CJS and ESM

You can install express-error-toolkit using your favorite package manager.

npm install express-error-toolkit

yarn add express-error-toolkit

pnpm add express-error-toolkit

⚙️ Requires Node.js v14 or higher. ℹ️ Make sure you have express installed in your project, as this toolkit is built specifically to enhance Express.js error handling.

import express from 'express'; import { asyncHandler } from 'express-error-toolkit'; const app = express(); app.get( '/users/:id', asyncHandler(async (req, res) => { // Your async code here throw new Error('Something went wrong!'); }) );

import { NotFoundError, BadRequestError } from 'express-error-toolkit'; app.get('/test', (req, res) => { throw new NotFoundError('User not found'); });

Each custom error automatically sets the correct statusCode and name.

You can also pass optional errorDetails as a string, object, or leave it out:

throw new BadRequestError('Invalid data', { field: 'email' }); throw new BadRequestError('Invalid input', 'Missing required field'); throw new BadRequestError('Generic client error');

import { notFoundHandler } from 'express-error-toolkit'; app.use(notFoundHandler);

This will throw a NotFoundError with the method and route info.

import { globalErrorHandler } from 'express-error-toolkit'; app.use(globalErrorHandler);

By default, the handler includes the stack trace and logs the error in development. In production (NODE_ENV=production), both are automatically suppressed for safety.

To enhance developer experience during debugging, this toolkit uses ANSI escape codes — no external dependencies like chalk required — to make console logs more readable.

Each part of the error log is styled using a traffic light-inspired color scheme:

• 🔴 Error Status & Message – Red
• 🟡 Error Details – Yellow (optional; string or object)
• 🟢 Stack Trace – Green (shown only if available and enabled)

🖼️ Example: Here's how the console might look in development mode:

By default, an introductory line ("Even the best code breaks sometimes! Let's debug...") is displayed before each error block.

You can control this with the introLine option:

import { setErrorOptions } from 'express-error-toolkit'; // Disable the intro line setErrorOptions({ introLine: false }); // Customize the intro line setErrorOptions({ introLine: '🚨 Debugging session begins here...' });

You can configure the error handling behavior (e.g., hide stack traces and disable console logging even in development) using either:

SHOW_STACK=false LOG_ERROR=false

or directly in your code:

import { setErrorOptions } from 'express-error-toolkit'; setErrorOptions({ showStack: false, logError: false });

This overrides the default behavior (based on NODE_ENV or .env file).

import { httpError } from 'express-error-toolkit'; throw httpError('Something custom', 418);

You can also pass optional errorDetails as a string, object, or leave it out:

throw httpError('Expectation failed', 417, { reason: 'The server could not meet the Expect header requirements' }); throw httpError('Failed Dependency', 424, 'This request relies on a previous request that failed' ); throw httpError('Unavailable for legal reason', 451);

import { isCustomAPIError } from 'express-error-toolkit'; if (isCustomAPIError(err)) { console.log(err.statusCode, err.message); // your rest of the code  }

├── src/ │ ├── error/ │ │ ├── BadRequestError.ts │ │ ├── NotFoundError.ts │ │ └── ... │ ├── global-error-handler.ts │ ├── async-handler.ts │ ├── http-error.ts │ └── index.ts ├── example/ │ └── index.ts ├── __tests__/ │ └── *.test.ts 

• Fully written in TypeScript
• Outputs:
  • CommonJS: dist/index.cjs
  • ESM: dist/index.js
  • Types: dist/index.d.ts

MIT © Rashedin Islam

This project includes http-status-toolkit, also created by me.

We welcome contributions! Please check out the Contributing Guide.

• GitHub: dev-rashedin
• Portfolio: rashedin.dev

Made with ❤️ by Rashedin Islam