{"id":12068,"library":"stacktrace-js","title":"Universal JavaScript Stack Trace Library","description":"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.","status":"active","version":"2.0.2","language":"javascript","source_language":"en","source_url":"git://github.com/stacktracejs/stacktrace.js","tags":["javascript","stacktrace","error","debugger","client","browser","typescript"],"install":[{"cmd":"npm install stacktrace-js","lang":"bash","label":"npm"},{"cmd":"yarn add stacktrace-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add stacktrace-js","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Extracts meaningful information from JavaScript Error objects' stack property.","package":"error-stack-parser","optional":false},{"reason":"Resolves partial code locations into precise code locations using source maps.","package":"stacktrace-gps","optional":false},{"reason":"Generates artificial stack traces for older browsers that lack native Error.stack support.","package":"stack-generator","optional":false},{"reason":"Defines the JavaScript object representation for a single stack frame.","package":"stackframe","optional":false}],"imports":[{"note":"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.","wrong":"const StackTrace = require('stacktrace-js');","symbol":"StackTrace","correct":"import * as StackTrace from 'stacktrace-js';\n// or\nimport { get, fromError, instrument, getSync, generateArtificially } from 'stacktrace-js';"},{"note":"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.","wrong":"import { StackFrame } from 'stacktrace-js';","symbol":"StackFrame","correct":"import { StackFrame } from 'stackframe';"},{"note":"Preferred way to get a stack trace from an existing Error object. Returns a Promise resolving to an array of StackFrame objects.","wrong":"StackTrace.fromError(error); // This works after a namespace import, but direct named import is preferred.","symbol":"fromError","correct":"import { fromError } from 'stacktrace-js';"}],"quickstart":{"code":"import { get, fromError } from 'stacktrace-js';\n\nasync function captureAndLogStackTraces() {\n  try {\n    // Simulate an error to capture its stack\n    let simulatedError = new Error('This is a simulated error for demonstration.');\n    const stackframesFromError = await fromError(simulatedError);\n    console.log('--- Stack trace from Error object ---');\n    console.log(stackframesFromError.map(sf => sf.toString()).join('\\n'));\n\n    // Get the stack trace from the current execution point\n    const stackframesCurrent = await get();\n    console.log('\\n--- Stack trace from current location ---');\n    console.log(stackframesCurrent.map(sf => sf.toString()).join('\\n'));\n\n  } catch (err: any) {\n    console.error('Failed to get stack trace:', err.message);\n  }\n}\n\ncaptureAndLogStackTraces();\n\n// Example of synchronous usage (without source map resolution)\nimport { getSync } from 'stacktrace-js';\nfunction callSynchronousTrace() {\n  console.log('\\n--- Synchronous Stack trace (no source maps) ---');\n  const syncStackframes = getSync();\n  console.log(syncStackframes.map(sf => sf.toString()).join('\\n'));\n}\ncallSynchronousTrace();","lang":"typescript","description":"Demonstrates asynchronous stack trace capture from a new Error object and the current execution context, as well as a synchronous trace."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.3.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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`).","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use `StackTrace.get().then(...)` for asynchronous, Promise-based operations, or directly process the Array returned by `StackTrace.getSync()`.","cause":"Attempting to call `.then()` on the result of `StackTrace.getSync()`, which returns an Array, not a Promise.","error":"TypeError: Cannot read properties of undefined (reading 'then')"},{"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.","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.","error":"ReferenceError: StackTrace is not defined"},{"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.","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.","error":"Error: Could not find a method to parse stack string."}],"ecosystem":"npm"}