Universal JavaScript Stack Trace Library

Common errors

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

  cause 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

  cause 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.

  cause 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.

Warnings

• breaking Version 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.
• gotcha The `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.
• breaking The 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.
• breaking Upgrading 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.

Install

• npm install stacktrace-js npm
• yarn add stacktrace-js yarn
• pnpm add stacktrace-js pnpm

Imports

• StackTrace
  wrong:

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

  correct:

  import * as StackTrace from 'stacktrace-js';
  // or
  import { get, fromError, instrument, getSync, generateArtificially } from '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
  wrong:

  import { StackFrame } from 'stacktrace-js';

  correct:

  import { StackFrame } from 'stackframe';

  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
  wrong:

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

  correct:

  import { fromError } from 'stacktrace-js';

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

Quickstart

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();