JSPM

error-explainer

1.0.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 8
  • Score
    100M100P100Q58131F
  • License MIT

Transforms cryptic JavaScript/TypeScript error messages into human-readable explanations with actionable fix suggestions.

Package Exports

  • error-explainer

Readme

error-explainer

Transform cryptic JavaScript & TypeScript error messages into human-readable explanations with actionable fix suggestions.

npm version zero dependencies TypeScript license: MIT

Why?

Error messages like Cannot read properties of undefined (reading 'name') are confusing — especially for beginners and junior developers. error-explainer translates them into plain English with a clear reason and a concrete fix suggestion.

Perfect for:

  • 🧑‍💻 Beginner-friendly developer tools
  • 🤖 AI-powered IDEs and coding assistants
  • 🛠️ Custom error dashboards and loggers
  • 📚 Learning platforms and code editors

Install

npm install error-explainer

Quick Start

import { explain } from 'error-explainer';

const result = explain("Cannot read properties of undefined (reading 'name')");

console.log(result);
// {
//   original:   "Cannot read properties of undefined (reading 'name')",
//   reason:     "You are trying to access the property `name` on a value that is `undefined`.",
//   suggestion: "Add a null-check before accessing the property: `if (value) { value.name }` or use optional chaining: `value?.name`.",
//   category:   "TypeError",
//   severity:   "high"
// }

API

explain(error, options?)

Explains a single error. Accepts a string, an Error object, or any unknown thrown value.

import { explain } from 'error-explainer';

// From a string
explain("user is not defined");

// From a caught Error object
try {
  doSomething();
} catch (err) {
  const info = explain(err);
  console.log(info.reason);
  console.log(info.suggestion);
}

Options

Option Type Default Description
includeCauses boolean false Include a commonCauses string array
includeDocs boolean false Include an MDN/docs URL when available 
explain("Cannot find module 'react'", {
  includeCauses: true,
  includeDocs: true,
});
// {
//   ...
//   commonCauses: ["Package not installed (`npm install` not run)", ...],
//   docs: "https://nodejs.org/api/modules.html"
// }

quickExplain(error)

Returns only reason and suggestion — ideal for tooltips and compact logging.

import { quickExplain } from 'error-explainer';

quickExplain("Maximum call stack size exceeded");
// {
//   reason:     "A function is calling itself without a proper base case ...",
//   suggestion: "Add a base/termination condition to your recursive function ..."
// }

explainAll(errors, options?)

Explain multiple errors at once.

import { explainAll } from 'error-explainer';

const results = explainAll([
  "Failed to fetch",
  "Assignment to constant variable",
  new TypeError("foo is not a function"),
]);

Return Type: ExplainedError

interface ExplainedError {
  original:      string;          // The raw input error message
  reason:        string;          // Human-readable explanation
  suggestion:    string;          // Actionable fix
  category:      ErrorCategory;  // "TypeError" | "ReferenceError" | ...
  severity:      "low" | "medium" | "high";
  commonCauses?: string[];        // With includeCauses: true
  docs?:         string;          // With includeDocs: true
}

Supported Error Types

Category Example Message
TypeError Cannot read properties of undefined (reading 'x')
TypeError Cannot read properties of null
TypeError foo is not a function
TypeError Assignment to constant variable
TypeError undefined is not iterable
ReferenceError user is not defined
SyntaxError Unexpected token '}'
SyntaxError Unexpected end of input
RangeError Maximum call stack size exceeded
PromiseError Unhandled promise rejection
NetworkError Failed to fetch / net::ERR_*
ModuleError Cannot find module 'react'

Integration Example — Express Error Handler

import { explain } from 'error-explainer';

app.use((err, req, res, next) => {
  const info = explain(err, { includeCauses: true });
  res.status(500).json({
    error:      info.original,
    reason:     info.reason,
    suggestion: info.suggestion,
    severity:   info.severity,
  });
});

Integration Example — React Error Boundary

import { explain } from 'error-explainer';

class ErrorBoundary extends React.Component {
  componentDidCatch(error: Error) {
    const info = explain(error);
    console.warn(`[${info.severity.toUpperCase()}] ${info.reason}`);
    console.info(`Fix: ${info.suggestion}`);
  }
}

License

MIT © error-explainer contributors