error-less

Beautiful, Rust-style error reporting for Node.js

Transform noisy Node.js stack traces into beautiful, actionable error reports with source code context—just like Rust, Next.js, and other modern frameworks.

Features

• Zero Configuration: Just import and errors become beautiful
• Source Code Context: See the exact line that caused the error with surrounding code
• Syntax Highlighting: Code snippets are colorized for readability
• Source Map Support: Works with TypeScript and transpiled code
• Smart Filtering: Focuses on your code, not node_modules
• Zero Runtime Cost: Only activates when errors are thrown
• Graceful Fallback: Never crashes your app—falls back to standard traces if needed

Before & After

Before (Standard Node.js):

TypeError: Cannot read properties of undefined (reading 'name')
    at getUser (/app/src/services/user.ts:45:12)
    at processRequest (/app/src/handlers/api.ts:23:8)
    at /app/src/index.ts:67:5

After (error-less):

TypeError: Cannot read properties of undefined (reading 'name')
   → ./src/services/user.ts:45:12

   43 │ function getUser(id: string) {
   44 │   const user = users.get(id);
 > 45 │   return user.name;
      │               ^^^
   46 │ }
   47 │

  tip: Verify the value type matches what the operation expects

Installation

npm install error-less

Quick Start

Zero-Config (Recommended)

Just import at the top of your entry file:

import 'error-less/register';

// Your code here...
throw new Error('Something went wrong!');

Manual Installation

For more control:

import { install, configure } from 'error-less';

install({
  showFullStack: true,
  contextLinesBefore: 3,
  contextLinesAfter: 3,
});

Format Errors in try/catch

import { formatError } from 'error-less';

try {
  riskyOperation();
} catch (error) {
  console.error(formatError(error));
  // Handle the error...
}

Configuration Options

import { install } from 'error-less';

install({
  // Lines of context before the error line (default: 2)
  contextLinesBefore: 2,

  // Lines of context after the error line (default: 2)
  contextLinesAfter: 2,

  // Enable source map resolution (default: true)
  enableSourceMaps: true,

  // Filter out node_modules frames (default: true)
  filterNodeModules: true,

  // Show full stack trace after code frame (default: false)
  showFullStack: false,

  // Force colors on/off (default: auto-detected)
  colors: true,

  // Custom frame filter
  frameFilter: (frame) => !frame.filePath.includes('test'),
});

API Reference

Core Functions

install(config?: ErrorLessConfig): void

Installs the custom stack trace handler.

uninstall(): void

Restores the original stack trace behavior.

configure(config: Partial<ErrorLessConfig>): void

Updates configuration without reinstalling.

formatError(error: Error): string

Returns a formatted error string. Useful for try/catch blocks.

formatThrown(thrown: unknown): string

Formats any thrown value (not just Error instances).

isEnabled(): boolean

Returns whether error-less is currently active.

Utility Functions

getErrorFrames(error: Error): ParsedFrame[]

Get parsed stack frames for advanced usage.

clearFileCache(): void

Clear the file content cache.

clearSourceMapCache(): void

Clear the source map consumer cache.

TypeScript Support

error-less is written in TypeScript and provides full type definitions.

import type { ErrorLessConfig, ParsedFrame } from 'error-less';

Source Map Support

error-less automatically detects and uses source maps:

1. Inline source maps: Embedded in the compiled file as base64
2. External source maps: .map files alongside compiled files
3. Embedded source content: Uses sourcesContent from maps when available

For TypeScript, ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "sourceMap": true
  }
}

How It Works

error-less hooks into V8's Error.prepareStackTrace API. When an error's .stack property is accessed:

1. The custom handler receives structured stack frame data
2. Frames are parsed to extract file paths, line numbers, and columns
3. Source maps are checked for original source locations
4. Source files are read and code context is extracted
5. A beautiful, syntax-highlighted output is generated

This approach has zero performance impact during normal execution—code only runs when an error is thrown and its stack is accessed.

Comparison

| Feature | error-less | pretty-error | youch | |---------|-----------|--------------|-------| | Zero config | ✅ | ❌ | ❌ | | Source code display | ✅ | ❌ | ✅ | | Source map support | ✅ | ❌ | ✅ | | Syntax highlighting | ✅ | ❌ | ❌ | | Smart filtering | ✅ | ✅ | ✅ | | Pure terminal output | ✅ | ✅ | ❌ (HTML) |

License

MIT