@stacktrace-lite/core

Parse, filter, and format JavaScript stack traces with plugins for browsers and Node.js.

@stacktrace-lite/core is a lightweight toolkit for working with JavaScript error stack traces. It helps you:

• Parse stack traces into structured frames.
• Filter out noisy frames (e.g., from node_modules or internals).
• Format stacks for console or browser display.
• Enrich frames with environment metadata or source map lookups.
• Hook into browser and Node.js global error events.

When to Use

• In development: Clean, readable stacks in the console or overlays.
• In production: Normalize and enrich stack traces before sending to your error tracker.
• In monitoring tools: Add plugins for PII masking, environment context, or source map mapping.

Installation

npm install @stacktrace-lite/core
# or
pnpm add @stacktrace-lite/core
# or
yarn add @stacktrace-lite/core
Copy

Usage

Parse a stack trace

import { parseStack } from '@stacktrace-lite/core';

try {
  throw new Error('Boom');
} catch (e) {
  const frames = parseStack(e);
  console.log(frames[0]);
  // { functionName: 'myFunc', fileName: '/src/app.ts', lineNumber: 10, columnNumber: 5, raw: 'at myFunc (src/app.ts:10:5)' }
}
Copy

Filter noisy frames

import { filterStack } from '@stacktrace-lite/core';

const filtered = filterStack(frames, {
  preset: 'app-only', // drop node_modules, internals, <anonymous>
  include: [/src\//], // keep only app code
});
Copy

Format for output

import { formatStack } from '@stacktrace-lite/core';

console.log(formatStack(filtered, 'cli'));
// or in browser UI
// document.body.innerHTML = formatStack(filtered, "html");
Copy

Plugins

Enrich with environment metadata

import { enrichEnvPlugin } from '@stacktrace-lite/core/plugins';

const withEnv = enrichEnvPlugin();
const framesWithEnv = withEnv(frames);

console.log(framesWithEnv.env);
// { timestamp: '2025-08-22T19:34:00.000Z', userAgent: 'Mozilla/5.0 ...', platform: 'Win32', language: 'en-US' }
Copy

Mask PII (emails)

import { piiMaskPlugin } from '@stacktrace-lite/core/plugins';

const masked = piiMaskPlugin(frames);
// fileName and functionName emails replaced with [email]
Copy

Map with source maps

import { makeSourceMapPlugin } from '@stacktrace-lite/core/plugins';

const plugin = await makeSourceMapPlugin({
  '/dist/app.js': rawSourceMap,
});

const mapped = plugin(frames);
// frames now point to original TypeScript source
Copy

Global error hooks

Browser

import { installBrowserErrorHooks } from '@stacktrace-lite/core/browser';

installBrowserErrorHooks({
  preset: 'app-only',
  onStack(frames, error) {
    sendToBackend({ frames, error });
  },
});
Copy

Node.js

import { installNodeErrorHooks } from '@stacktrace-lite/core/node';

installNodeErrorHooks({
  onStack(frames, err) {
    console.error('Uncaught:', err.message);
    sendToBackend({ frames, err });
  },
});
Copy

API Reference

View the Reference Docs