{"id":14052,"library":"stacktracey","title":"StackTracey: Stack Trace Parser & Pretty Printer","description":"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.","status":"active","version":"2.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/xpl/stacktracey","tags":["javascript","stack","stacktrace","stack printer","error printer","print error","print stack","print debug trace","debug","typescript"],"install":[{"cmd":"npm install stacktracey","lang":"bash","label":"npm"},{"cmd":"yarn add stacktracey","lang":"bash","label":"yarn"},{"cmd":"pnpm add stacktracey","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally by StackTracey to fetch source code for stack frame locations, enabling its full sourcemap and source text display features.","package":"get-source","optional":false}],"imports":[{"note":"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.","wrong":"const StackTracey = require('stacktracey')","symbol":"StackTracey","correct":"import StackTracey from 'stacktracey'"},{"note":"For TypeScript users, `StackTraceyItem` is the interface representing a single parsed stack frame, useful for type hints when working with `stack.items`.","symbol":"StackTraceyItem","correct":"import type { StackTraceyItem } from 'stacktracey'"},{"note":"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.","wrong":"const stackWithSources = new StackTracey(error).withSourcesAsync()","symbol":"withSourcesAsync","correct":"const stackWithSources = await new StackTracey(error).withSourcesAsync()"}],"quickstart":{"code":"import StackTracey from 'stacktracey';\n\nasync function demonstrateStackTracey() {\n  try {\n    // Simulate an error to capture its stack\n    const divideByZero = () => { throw new Error('Cannot divide by zero!'); };\n    divideByZero();\n  } catch (error) {\n    console.log('--- Original Error Stack ---');\n    console.error(error.stack);\n\n    // Create a StackTracey instance from the error\n    let stack = new StackTracey(error);\n    console.log('\\n--- Parsed StackTracey Items (first 2) ---');\n    stack.items.slice(0, 2).forEach((item, index) => {\n      console.log(`Item ${index}:`, {\n        callee: item.callee,\n        fileRelative: item.fileRelative,\n        line: item.line,\n        column: item.column,\n        thirdParty: item.thirdParty\n      });\n    });\n\n    // Fetch sources asynchronously (recommended for browsers and Node for non-blocking I/O)\n    console.log('\\n--- Fetching sources asynchronously ---');\n    const stackWithSources = await stack.withSourcesAsync();\n    const topItem = stackWithSources.items[0];\n    if (topItem.sourceFile) {\n      console.log(`\\nSource for top frame (${topItem.fileShort}:${topItem.line}):`);\n      console.log(topItem.sourceFile.text.split('\\n')[topItem.line - 1].trim());\n    } else {\n      console.log('Source not available for the top frame.');\n    }\n\n    // Pretty print the stack\n    console.log('\\n--- Pretty-printed StackTracey ---');\n    console.log(stackWithSources.pretty);\n  }\n}\n\ndemonstrateStackTracey().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Using `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Not 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`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'2.2.0':33 'abil':63 'access':105 'across':46 'ad':79 'ad-hoc':78 'also':124 'asynchron':102,109 'avoid':118 'block':119 'browser':39,115 'call':16,69,88 'clean':23 'code':20,107 'compat':45 'cross':43 'cross-platform':42 'current':30 'debug':135,158,160 'defin':92 'design':13 'develop':141 'differenti':56 'e.g':86 'enhanc':137 'environ':40,116 'error':138,151,154 'exclus':81,93 'extract':125 'fetch':65 'filter':24 'frame':85 'full':59 'generat':22 'get':73 'get-sourc':72 'hide':95 'hoc':80 'inform':127 'instanc':130 'interfac':103 'irrelev':83 'javascript':11,146 'leverag':71 'librari':12,55,87 'like':50 'locat':70 'log':144 'main':121 'make':131 'marker':96 'mechan':76 'method':113 'nix':53 'node.js':37 'oper':48 'output':29 'pars':15 'parser':4 'platform':44 'prefer':112 'pretti':5,27 'pretty-print':26 'print':28,153,155,157 'printer':6,150,152 'provid':98 'read':18 'report':139 'robust':10 'solut':145 'sourc':19,66,74,106 'sourcemap':60 'stack':2,17,84,147,149,156 'stacktrac':148 'stacktracey':1,7 'support':41,61 'synchron':100 'syntaxerror':129 'system':49 'target':35 'text':67 'thread':122 'tool':142 'trace':3,159 'typescript':161 'use':126 'user':91 'user-defin':90 'valuabl':133 'various':47 'version':32 'via':94 'window':51","created_at":"2026-04-20T01:57:41.309961+00:00","updated_at":"2026-04-20T01:57:41.309961+00:00","problems":[{"fix":"Use `const StackTracey = require('stacktracey').default;` or, preferably, migrate your code to use ESM imports: `import StackTracey from 'stacktracey';`.","cause":"Attempting to `new StackTracey()` after using `require('stacktracey')` in a CommonJS context, where `stacktracey` is primarily an ESM default export.","error":"TypeError: StackTracey is not a constructor"},{"fix":"Always `await` the result of `stack.withSourcesAsync()` to ensure the Promise resolves and errors are caught: `const stackWithSources = await stack.withSourcesAsync();`.","cause":"Forgetting to `await` the `withSourcesAsync()` method, which returns a Promise.","error":"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)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://xpl.github.io/stacktracey","github":"https://github.com/xpl/stacktracey","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/stacktracey","openapi_spec":null,"status_page":null,"smithery":null,"categories":["observability"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}