🔍 js-stack-symbolicator

A lightweight Node.js and browser-compatible utility for symbolication of JavaScript stack traces using source maps. It helps convert minified stack traces back into readable, unminified ones—ideal for debugging production errors from Chrome, Safari, and Firefox.

✨ Features

• ✅ Parses and symbolicates stack traces from Chrome, Safari, and Firefox
• ✅ Supports Node.js and browser environments
• ✅ Uses source-map and stacktrace-parser under the hood
• ✅ Fully async and lightweight

📦 Installation

Using npm:

npm install @convivainc/symbolicate-stacktrace

Using yarn:

yarn add @convivainc/symbolicate-stacktrace

🧠 Usage (Node.js)

// index.js (Node.js)
const fs = require('fs');
const { symbolicate } = require('@convivainc/symbolicate-stacktrace);

const stackTrace = `Error: something went wrong
    at a (app.min.js:2:1234)
    at b (app.min.js:2:4567)`;

const sourceMap = JSON.parse(fs.readFileSync('./app.min.js.map', 'utf8'));

symbolicate(stackTrace, sourceMap).then((symbolicatedStack) => {
  console.log('🛠 Symbolicated Stack Trace:\n', symbolicatedStack);
});

🧪 Example: Using in the Frontend

You can also use this package in a browser-based frontend application (e.g., React, Vue, or plain HTML/JS).

import { symbolicate } from '@convivainc/symbolicate-stacktrace';

// Your minified stack trace string (e.g., from window.onerror or try/catch)
const stackTrace = `Error: something went wrong
    at t.value (app.min.js:2:4356)
    at t.onClick (app.min.js:2:4461)`;

// Load the source map dynamically (e.g., from your server)
fetch('/path/to/app.min.js.map')
	.then((res) => res.json())
	.then(async (sourceMap) => {
		const result = await symbolicate(stackTrace, sourceMap);
		console.log('🛠 Symbolicated Stack Trace:\n', result);
	});

💡 Note: If you're loading source maps in the browser, make sure your server allows access (CORS, correct headers, etc.).

🛠 API

symbolicate(stackTrace: string, sourceMap: object): Promise<string>

• stackTrace: Minified stack trace string
• sourceMap: Parsed source map object (JSON)
• Returns: A Promise that resolves to a symbolicated stack trace string

🧰 Dependencies

• source-map
• stacktrace-parser

👨‍💻 Author

Made by Mayank Rastogi

🧾 License

MIT