DEV Community

Cover image for express-error-toolkit — the One NPM Package to Handle All Express Errors
Rashedin | FullStack Developer
Rashedin | FullStack Developer

Posted on • Edited on

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

#npm #express #dx #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
Enter fullscreen mode Exit fullscreen mode

ℹ️ 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');   }) );
Enter fullscreen mode Exit fullscreen mode

2. Use custom errors 

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

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

3. Catch unregistered routes 

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

app.use(notFoundHandler);
Enter fullscreen mode Exit fullscreen mode

4. Global error handler 

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

app.use(globalErrorHandler);
Enter fullscreen mode Exit fullscreen mode

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 });
Enter fullscreen mode Exit fullscreen mode

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);
Enter fullscreen mode Exit fullscreen mode 
import { isCustomAPIError } from 'express-error-toolkit';  

if (isCustomAPIError(err)) {   console.log(err.statusCode, err.message); }
Enter fullscreen mode Exit fullscreen mode

🔥 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?

📃 License

MIT © Rashedin Islam

🙌 Acknowledgements

Built with ❤️ and TypeScript by Rashedin Islam

If you find it useful, consider giving it a ⭐ on GitHub.

Top comments (8)

Collapse
 
dr-63 profile image
dr •

Great work! Copy-pasting notFoundHandler, globalErrorHandler, and asyncHandler has always felt repetitive and a bit tedious. I’ve often wished there was something to handle this boilerplate for me—looks like your package might be exactly what I’ve been looking for.

Collapse
 
dev-rashedin profile image
Rashedin | FullStack Developer •

Thank you. It's definitely can improve your developer experience. Please let me know your feedback after using it. And if you found the project helpful, don't forget to give a ⭐ in the project repo.

Collapse
 
dr-63 profile image
dr •

Already gave you a star, you totally deserve this man!

Thread Thread
 
dev-rashedin profile image
Rashedin | FullStack Developer •

Thank you so much for your kind words

Collapse
 
yogi_jibonanando_389d3d05 profile image
Yogi Jibonanando •

This is super cool! 🚀 As someone who has also repeated the same boilerplate across projects, I really relate to the pain points you mentioned.

I like how express-error-toolkit goes beyond just handling errors and actually improves the dx with better logging and built-in utilities. The fact that it removes the need for external packages like chalk and still keeps things type-safe is a big plus.

I’m definitely going to try this out in my next Express project — anything that saves time and makes error handling less repetitive is a win in my book. Thanks for building and sharing this! 🙌

Collapse
 
dev-rashedin profile image
Rashedin | FullStack Developer •

It would be my pleasure if it helps other developers. Please let me know your feedback. And a github ⭐ would mean world to me :)

Collapse
 
laila_arjuman profile image
Laila Arjuman •

In all my recent Express projects I use this — it saves me writing repetitive code. And the colorful console is cherry on the top. It's definitely worth trying.

Collapse
 
dev-rashedin profile image
Rashedin | FullStack Developer •

Thank you so much for your kind words and the github star.