🧠 IntellError

Transform ugly JavaScript/Node.js stack traces into clean, readable, and actionable output. Designed for humans, not robots.

✨ Why IntellError?

Standard error logs are noisy, cluttered with node_modules, and lack context. IntellError gives you the "Why" and "How to Fix" instantly.

• ❌ Clean Stack Traces: Auto-hides Node.js internals and collapses node_modules noise.
• 📍 Source Map Support: Auto-translates minified/compiled code back to original TypeScript/Source locations.
• 🔗 Async Stack Chaining: Recursively traverses Error.cause to show the full async story.
• 💡 Actionable Suggestions 2.0: 100+ context-aware rules with confidence scoring.
• 📸 Code Snapshots: See the exact line of code directly in your terminal (Node.js only).
• 📊 Observability Ready: Includes JSON Mode, Error Fingerprinting, and Severity Levels.
• 🌐 Universal Runtime Support: Native support for Node.js, Bun, Deno, and Edge/Serverless.

🚀 Quick Start (Zero-Config)

Add this at the very top of your entry file to catch all unhandled errors automatically.

For Browser (React, Vite, Next.js)

import 'intellerror/register';

For Node.js / Bun / Deno

# Node.js 20+
node --import intellerror/register index.js

# Bun
bun index.ts  # (Auto-detected if you import it)

🛠️ Advanced Features

🤖 Machine-Readable JSON Mode

Enable production logging that flows perfectly into Datadog, Splunk, or Loki.

import { formatErrorJSON } from 'intellerror';

try {
  // your code
} catch (err) {
  console.log(formatErrorJSON(err));
}

🔗 Error Chaining (Error.cause)

Never lose context again. IntellError recursively handles nested errors.

  ERROR  Failed to fetch user from DB
  2026-04-06T06:07:49.123Z | uptime: 12.5s | ID: a1b2c3d4

  🔗 Causes:
  caused by: Error: Connection refused (timeout after 5000ms)

📍 Source Map Integration

If a .map file exists alongside your compiled script, IntellError will automatically show the original source location.

📍 Location:
src/users/service.ts:45:10 [mapped]   ← YOUR CODE

⚙️ Configuration

Fine-tune the output or add your own project-specific intelligence.

import { setupConfig } from 'intellerror';

setupConfig({
  showNodeModules: false,    // Hide noise?
  showNodeInternals: false,  // Hide node internals?
  suggestionsEnabled: true,  // Show the "💡 Suggestions"?
  sourceMapsEnabled: true,   // Enable original source mapping?
  webhookUrl: 'https://...'  // Push to Slack/Discord?
});

📖 Manual Usage

Terminal / Node.js

import { formatError } from 'intellerror';

try {
  // your code...
} catch (err) {
  console.log(formatError(err)); 
}

Browser Console (React/Vite)

import { formatErrorBrowser } from 'intellerror';

try {
  // ...
} catch (err) {
  // MUST use the spread operator (...) for CSS styling
  console.log(...formatErrorBrowser(err));
}

🚅 Framework Integration

Express Middleware

import express from 'express';
import { errorFormatter } from 'intellerror';

const app = express();
app.use(errorFormatter());

🌍 Environment Variables (Zero-Config)

You can configure IntellError without changing a single line of code using environment variables.

| Variable | Default | Description | | :--- | :--- | :--- | | INTELLERROR_JSON | false | Enable structured JSON output for all unhandled errors. | | INTELLERROR_SOURCE_MAPS | true | Enable/disable original source mapping via .map files. | | INTELLERROR_SUGGESTIONS | true | Show the "💡 Suggestions" section. | | INTELLERROR_SHOW_MODULES | false | Show node_modules frames in the stack trace. | | INTELLERROR_SHOW_INTERNALS | false | Show Node.js internal frames in the stack trace. | | INTELLERROR_SEARCH_LINKS | true | Show troubleshooting links. |

🎮 Examples

Explore the examples/ directory for ready-to-run demos:

• npm run example:basic
• npm run example:async
• npm run example:advanced (New: Chaining & JSON mode)

📄 License

MIT © darshan1005

🤝 Contributing

IntellError is open for contributions! Whether it's adding new suggestion rules, improving the parser, or adding more framework integrations, feel free to open a PR or Issue on GitHub.

Built with humans in mind.