Registry / observability / stacktracey

stacktracey

JSON →
library2.2.0jsnpmunverified

StackTracey is a robust JavaScript library designed for parsing call stacks, reading source code, and generating clean, filtered, and pretty-printed output. Currently at version 2.2.0, it targets both Node.js and browser environments, supporting cross-platform compatibility across various operating systems like Windows and *nix. The library differentiates itself with full sourcemap support, the ability to fetch source text for call locations (leveraging `get-source`), and mechanisms for ad-hoc exclusion of irrelevant stack frames (e.g., library calls or user-defined exclusions via `// @hide` markers). It provides both synchronous and asynchronous interfaces for accessing source code, with asynchronous being the preferred method for browser environments to avoid blocking the main thread. It also extracts useful information from `SyntaxError` instances, making it valuable for debugging and enhanced error reporting in development tools and logging solutions.

npm install stacktracey
INSTALL
IMPORT
SIG · STACKTRACEY
S
stacktracey
observabilityjavascriptv2.2.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

StackTracey
import StackTracey from 'stacktracey'
const StackTracey = require('stacktracey')
StackTracey uses a default export. While CommonJS `require()` might work in some transpiled setups, `import` is the idiomatic and recommended way for modern JavaScript and TypeScript projects. Direct `require()` can lead to issues in pure ESM environments.
StackTraceyItem
import type { StackTraceyItem } from 'stacktracey'
For TypeScript users, `StackTraceyItem` is the interface representing a single parsed stack frame, useful for type hints when working with `stack.items`.
withSourcesAsync
const stackWithSources = await new StackTracey(error).withSourcesAsync()
const stackWithSources = new StackTracey(error).withSourcesAsync()
The `withSourcesAsync()` method returns a Promise, which must be `await`ed to ensure source code is fetched before processing. Forgetting `await` will result in an unresolved Promise.

This quickstart demonstrates how to capture and parse an error stack, access individual stack frame properties, asynchronously fetch source code for frames, and finally pretty-print the entire processed stack. It highlights the library's core capabilities for error introspection and rich output.

import StackTracey from 'stacktracey'; async function demonstrateStackTracey() { try { // Simulate an error to capture its stack const divideByZero = () => { throw new Error('Cannot divide by zero!'); }; divideByZero(); } catch (error) { console.log('--- Original Error Stack ---'); console.error(error.stack); // Create a StackTracey instance from the error let stack = new StackTracey(error); console.log('\n--- Parsed StackTracey Items (first 2) ---'); stack.items.slice(0, 2).forEach((item, index) => { console.log(`Item ${index}:`, { callee: item.callee, fileRelative: item.fileRelative, line: item.line, column: item.column, thirdParty: item.thirdParty }); }); // Fetch sources asynchronously (recommended for browsers and Node for non-blocking I/O) console.log('\n--- Fetching sources asynchronously ---'); const stackWithSources = await stack.withSourcesAsync(); const topItem = stackWithSources.items[0]; if (topItem.sourceFile) { console.log(`\nSource for top frame (${topItem.fileShort}:${topItem.line}):`); console.log(topItem.sourceFile.text.split('\n')[topItem.line - 1].trim()); } else { console.log('Source not available for the top frame.'); } // Pretty print the stack console.log('\n--- Pretty-printed StackTracey ---'); console.log(stackWithSources.pretty); } } demonstrateStackTracey().catch(console.error);
Debug
Known issues
gotchaUsing `stack.withSources()` synchronously in browser environments can block the main thread, leading to a unresponsive user interface. While it works in Node.js, it's generally discouraged for performance-sensitive applications.
fix
Prefer `await stack.withSourcesAsync()` for fetching source code. This method returns a Promise and performs I/O operations without blocking the event loop, making it suitable for both browser and Node.js environments.
affects: >=1.0.0
gotchaWhen `stacktracey` is used in a project that mixes CommonJS (CJS) and ES Module (ESM) syntax, especially if the consuming project is CJS and `stacktracey` is treated as ESM, direct `require('stacktracey')` can lead to import errors or unexpected behavior.
fix
Always use `import StackTracey from 'stacktracey'` for modern JavaScript and TypeScript projects. If forced to use CommonJS, dynamic import `(await import('stacktracey')).default` might be necessary, or ensure your build system correctly transpiles ESM imports.
affects: >=1.0.0
gotchaNot all stack frames will have associated source code, especially for native calls, minified production code without sourcemaps, or frames from external libraries not configured for source fetching. The `sourceFile` property on a `StackTraceyItem` might be `null` or `undefined`.
fix
Always check for the existence of `item.sourceFile` and `item.sourceFile.text` before attempting to access its properties to prevent runtime errors. Ensure sourcemaps are correctly generated and accessible for deployed code to maximize source fetching capabilities.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: StackTracey is not a constructor
Attempting to `new StackTracey()` after using `require('stacktracey')` in a CommonJS context, where `stacktracey` is primarily an ESM default export.
fix
Use `const StackTracey = require('stacktracey').default;` or, preferably, migrate your code to use ESM imports: `import StackTracey from 'stacktracey';`.
UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: X)
Forgetting to `await` the `withSourcesAsync()` method, which returns a Promise.
fix
Always `await` the result of `stack.withSourcesAsync()` to ensure the Promise resolves and errors are caught: `const stackWithSources = await stack.withSourcesAsync();`.
Upgrade
Version history
2.2.0latest on npm
Audit
Dependencies
get-sourcerequiredUsed internally by StackTracey to fetch source code for stack frame locations, enabling its full sourcemap and source text display features.
Agent activity
18 hits · last 30 days
node
16
OpenAI (training)
1
Resources
stacktracey — npm install stacktracey · libregistry