Package Exports

explainable-errors
explainable-errors/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (explainable-errors) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

explainable-errors

Errors are meant for humans, not just machines.
Turn cryptic errors into clear, actionable messages your team can understand instantly.

Most error messages tell you what broke, not why or what to do next. explainable-errors turns raw technical errors into clear, teachable explanations.

Designed for developers who care about clarity, learning, and good DX.

The Problem

This is a common error:

TypeError: Cannot read property 'name' of undefined

But what you really want to know is:

What happened?
Why did it happen?
What should I do now?

That context usually lives:

in someone’s head
in Slack messages
or in code reviews

This library makes that context part of the error itself.

The Idea

Every error should answer three human questions:

What happened
Why it happened
What you can do

That’s it. No dashboards. No services. No magic.

Installation

npm install explainable-errors

pnpm add explainable-errors

Basic Usage

import { explain } from 'explainable-errors';

try {
  await fetchUser();
} catch (err) {
  throw explain(err, {
    what: 'Failed to load user profile',
    why: 'The API request returned an error',
    fix: 'Check if the backend is running or the endpoint is correct',
  });
}

Dev Output

❌ Failed to load user profile

Why it happened:
→ The API request returned an error

What you can do:
→ Check if the backend is running or the endpoint is correct

Readable. Actionable. Teachable.

Why This Exists

Most error-handling tools focus on:

logging
monitoring
machines

explainable-errors focuses on:

developers
learning
understanding

It’s especially useful for:

frontend applications
shared APIs
onboarding junior developers
internal tools
teaching environments

Design Principles

✅ Teaching-first
✅ Framework-agnostic
✅ Zero configuration
✅ Preserves original stack traces
✅ No automatic logging
✅ Works in frontend and backend

If you remove this package later, your code still works.

API

`explain(error, explanation)`

`error`

Any Error, string, or unknown value

`explanation`

{
  what: string; // required
  why?: string;
  fix?: string;
}

Returns a standard Error with explanation metadata attached.

You decide whether to throw, log, or handle it.

Production vs Development

Development: full, readable explanation
Production: compact error message, same stack trace

No sensitive information is exposed by default.

What This Is NOT

❌ Not a logging framework
❌ Not an error tracking service
❌ Not a replacement for Sentry
❌ Not AI-powered (by design)

It does one thing well.

Philosophy

Good error messages are a form of documentation. Great error messages are a form of teaching.

Roadmap (Intentionally Small)

Error explanation presets (e.g. network, null access)
Optional colour formatting
Framework adapters (React / Express)

No plans for dashboards or SaaS.

Contributing

Ideas, feedback, and discussions are welcome. This project values clarity over cleverness.

License

MIT