express-error-toolkit — the One NPM Package to Handle All Express Errors

As a full-stack developer, I’ve spent countless hours building robust backend applications with Express.js. While Express is lightweight and unopinionated — exactly what makes it great — error handling has always been repetitive and tedious.

I was tired of copy-pasting the same boilerplate across projects:

• ✅ Writing notFoundHandler manually
• ✅ Writing globalErrorHandler for every single project
• ✅ Wrapping every async function in a try-catch or asyncHandler
• ✅ Creating CustomApiError, NotFoundError, BadrequestError and other custom errors.
• ✅ Installing separate libraries like chalk just to make my logs more readable

Even after using popular libraries like express-async-errors or async-error-handler, I still had to manually wire up custom errors and error-handling middleware. And none of them improved the developer experience in the terminal.

So, I built - 🔗 express-error-toolkit — the one package to handle all Express errors.

---

🧰 What's Included?

This package provides everything you need to handle errors in a production-grade Express app:

• ✅ Type-safe custom error classes (NotFoundError, BadRequestError, etc.)
• ✅ Drop-in middleware: globalErrorHandler, notFoundHandler
• ✅ A clean asyncHandler utility
• ✅ A httpError() function for custom one-liners
• ✅ Colorful and readable console logs — no need for chalk or similar
• ✅ Flexible .env or programmatic configuration
• ✅ Built-in support for CommonJS and ESM
• ✅ Designed with DX in mind

---

🏗 Build Process

The package is written entirely in TypeScript and built with:

• tsup — lightning-fast bundler
• http-status-toolkit — my own utility, to handle http-status-codes in more human readable way
• ANSI escape codes — to create colorful terminal output (no dependencies required)

The idea was to bundle everything in a single utility that you can drop into any Express project, and instantly get a polished, configurable, DX-optimized error system.

---

⚡ Installation

npm install express-error-toolkit

ℹ️ Requires Node.js version >=14

Make sure you have express installed in your project.

---

📦 Usage Examples

1. Wrap async route handlers

import { asyncHandler } from 'express-error-toolkit';

app.get('/users/:id', asyncHandler(async (req, res) => 
{throw new Error('User not found');   }) );

---

2. Use custom errors

import { NotFoundError } from 'express-error-toolkit';  

app.get('/user/:id', (req, res) => 
{throw new NotFoundError('User not found'); });

---

3. Catch unregistered routes

import { notFoundHandler } from 'express-error-toolkit';

app.use(notFoundHandler);

---

4. Global error handler

import { globalErrorHandler } from 'express-error-toolkit';  

app.use(globalErrorHandler);

By default, it includes stack trace and logs the error, but removes both when NODE_ENV=production.

---

🧪 Console Output — Traffic Light Theme

To make debugging more intuitive, express-error-toolkit uses ANSI escape codes to show:

• 🔴 Error Message in bold red

• 🟡 Error Details in bold yellow

• 🟢 Stack Trace in dim green, line-by-line

📸 Console Preview:

_{Colors are styled without external libraries — just pure ANSI codes}

---

🛠️ Optional Configuration

5. Set Options Globally (Optional)

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

✅ Via && .env**:

SHOW_STACK=false LOG_ERROR=false

✅ Or directly in your code:

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

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

---

📚 Utility Helpers

import { httpError, StatusCodes } from 'express-error-toolkit';

throw httpError('Something broke!', StatusCodes.BAD_REQUEST);

import { isCustomAPIError } from 'express-error-toolkit';  

if (isCustomAPIError(err)) {   console.log(err.statusCode, err.message); }

---

🔥 Why It Improves Developer Experience

• 🧼 Cleaner, centralized error handling

• ⌛ Saves hours of repetitive setup

• 🧠 Human-readable, styled error logs

• 🚫 No unnecessary dependencies (like chalk)

• ⚙️ Easily configurable — no lock-in, no magic

---

📁 Output

The build generates:

• dist/index.cjs.js — CommonJS

• dist/index.esm.js — ESM

• dist/index.d.ts — TypeScript types

---

💼 Ideal For

• Full-stack teams building REST APIs

• Developers who care about clean DX

• Production-ready Express.js apps

• Anyone tired of writing error handlers over and over

---

🧭 Want to Explore?

• 🔗 View on npm
• 💻 View source on GitHub
• 🌐 Visit my portfolio

---

📃 License

MIT © Rashedin Islam

---

🙌 Acknowledgements

• http-status-toolkit

• ANSI escape codes — for stylish logging without bloat

---

Built with ❤️ and TypeScript by Rashedin Islam
If you find it useful, consider giving it a ⭐ on GitHub.