Registry / observability / stacktrace-js

stacktrace-js

library2.0.2jsnpmunverified

stacktrace.js is a framework-agnostic micro-library designed to generate, parse, and enhance JavaScript stack traces across all environments, including browsers and Node.js. The current stable version is 2.0.2. It maintains a moderate release cadence, with updates typically addressing dependency bumps, bug fixes, and minor enhancements. Key differentiators include its ability to parse ES6 code, extensible StackFrame objects that report on constructor, native, or eval code, and its use of source maps for enhanced trace accuracy. It modularizes functionality into several sub-projects like error-stack-parser and stacktrace-gps to handle specific aspects of stack trace processing, providing both asynchronous (Promise-based) and synchronous API methods for flexibility. The library is particularly useful for robust error reporting and debugging applications.

observability testing

npm install stacktrace-js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · STACKTRACE-JS

stacktrace-js

observabilityjavascriptv2.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

StackTrace

✓ import * as StackTrace from 'stacktrace-js'; // or import { get, fromError, instrument, getSync, generateArtificially } from 'stacktrace-js';

✗ const StackTrace = require('stacktrace-js');

While CommonJS `require` still works, modern TypeScript/ESM projects should use named or namespace imports. The library exposes its API as named exports and also as a default export (StackTrace object) in UMD builds.

StackFrame

✓ import { StackFrame } from 'stackframe';

✗ import { StackFrame } from 'stacktrace-js';

StackFrame is a separate modularized project; instances are returned by stacktrace-js methods, but the class itself is typically imported directly from 'stackframe' if you need to create them manually or access static methods. Starting with v2.0.0, StackFrame objects have additional properties for extensibility.

fromError

✓ import { fromError } from 'stacktrace-js';

✗ StackTrace.fromError(error); // This works after a namespace import, but direct named import is preferred.

Preferred way to get a stack trace from an existing Error object. Returns a Promise resolving to an array of StackFrame objects.

Demonstrates asynchronous stack trace capture from a new Error object and the current execution context, as well as a synchronous trace.

import { get, fromError } from 'stacktrace-js'; async function captureAndLogStackTraces() { try { // Simulate an error to capture its stack let simulatedError = new Error('This is a simulated error for demonstration.'); const stackframesFromError = await fromError(simulatedError); console.log('--- Stack trace from Error object ---'); console.log(stackframesFromError.map(sf => sf.toString()).join('\n')); // Get the stack trace from the current execution point const stackframesCurrent = await get(); console.log('\n--- Stack trace from current location ---'); console.log(stackframesCurrent.map(sf => sf.toString()).join('\n')); } catch (err: any) { console.error('Failed to get stack trace:', err.message); } } captureAndLogStackTraces(); // Example of synchronous usage (without source map resolution) import { getSync } from 'stacktrace-js'; function callSynchronousTrace() { console.log('\n--- Synchronous Stack trace (no source maps) ---'); const syncStackframes = getSync(); console.log(syncStackframes.map(sf => sf.toString()).join('\n')); } callSynchronousTrace();

Debug

Known issues

breakingVersion 2.0.0 introduced breaking changes related to the `StackFrame` object, enhancing its extensibility. If you were directly manipulating or relying on specific internal structures of `StackFrame` instances prior to v2.0.0, you might need to adjust your code.

fix

Consult the official StackFrame documentation or the v2.0.0 release notes for details on new properties and updated usage. Generally, relying on `sf.toString()` or accessing public properties like `fileName`, `lineNumber` is safer.

affects: >=2.0.0

gotchaThe `StackTrace.getSync()` method does not enhance stack traces with source maps or guess anonymous function names. This means the trace will be less detailed and potentially harder to debug in production environments.

fix

For enhanced stack traces with source map resolution and better readability, always prefer the asynchronous `StackTrace.get()` or `StackTrace.fromError()` methods, which return Promises. Use `getSync()` only when strict synchronous behavior is absolutely required and less detail is acceptable.

affects: >=1.3.0

breakingThe project license changed from what was implied by earlier versions (likely Apache 2.0 or similar) to MIT License in v2.0.0, following a community vote. This is a legal breaking change that might affect compliance for some organizations.

fix

Review the MIT License to ensure compliance. If your project has strict licensing requirements, confirm that the MIT License is compatible with your project's legal framework.

affects: >=2.0.0

breakingUpgrading from 0.x to 1.x required significant changes due to modularization. The API surface changed dramatically as `stacktrace.js` was split into five separate projects (`stacktrace-gps`, `error-stack-parser`, `stack-generator`, `stackframe`).

fix

Refer to the '0.x -> 1.x Migration Guide' (linked in the README) for detailed instructions on adapting your codebase to the new modularized API. This primarily involves importing `StackTrace` and its methods directly, rather than relying on a single global object with all functionalities.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'then')

Attempting to call `.then()` on the result of `StackTrace.getSync()`, which returns an Array, not a Promise.

fix

Use `StackTrace.get().then(...)` for asynchronous, Promise-based operations, or directly process the Array returned by `StackTrace.getSync()`.

ReferenceError: StackTrace is not defined

The `StackTrace` global or imported object is not available in the current scope, often due to incorrect CommonJS `require` in an ESM context or missing import statement.

fix

Ensure you have `import * as StackTrace from 'stacktrace-js';` or `import { get, fromError } from 'stacktrace-js';` at the top of your ES module, or that the UMD bundle has been correctly loaded in a non-module environment.

Error: Could not find a method to parse stack string.

This error might occur internally within `error-stack-parser` if the browser's `Error.stack` format is unusual or unrecognized, or if the `Error` object itself is malformed.

fix

Ensure the `Error` object passed to `StackTrace.fromError()` is a standard JavaScript Error instance. If the issue persists, it might indicate an environment-specific parsing limitation; consider reporting to the library's GitHub issues.

Upgrade

Version history

2.0.2latest on npm

Audit

Dependencies

error-stack-parserrequiredExtracts meaningful information from JavaScript Error objects' stack property.

stacktrace-gpsrequiredResolves partial code locations into precise code locations using source maps.

stack-generatorrequiredGenerates artificial stack traces for older browsers that lack native Error.stack support.

stackframerequiredDefines the JavaScript object representation for a single stack frame.

Agent activity

16 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/stacktracejs/stacktrace.js ↗

packagehttps://www.npmjs.com/package/stacktrace-js ↗

homepagehttps://www.stacktracejs.com ↗