source-map-support
Advanced tools
Package description
The source-map-support package provides source map support for stack traces in Node.js. This means that when an error stack trace is printed, it can show the original source locations instead of the transpiled or bundled code locations, which is especially useful when working with TypeScript or modern JavaScript that has been transpiled to an older version for compatibility.
Error Stack Trace Remapping
By installing source-map-support, error stack traces will be remapped to the original source files. This is useful when debugging errors in transpiled or minified code.
require('source-map-support').install();
throw new Error('This is a test error');Retrieve Original Source Position
This feature allows you to manually retrieve the original source position of a specific line and column in a compiled file.
const sourceMapSupport = require('source-map-support');
const position = sourceMapSupport.mapSourcePosition({
source: 'compiled.js',
line: 1,
column: 100
});
console.log(position);Retrieve Source Content
This feature enables you to retrieve the content of the original source file given the path to the compiled file.
const sourceMapSupport = require('source-map-support');
const content = sourceMapSupport.retrieveSource('compiled.js');
console.log(content);The 'trace' package is similar to 'source-map-support' in that it also enhances stack traces. It modifies the stack trace to include the original source lines, but it does not require source maps to do so. It is less powerful for transpiled code but can be easier to use for simpler use cases.
The 'source-map' package provides utilities for generating and consuming source maps. While 'source-map-support' is focused on applying source maps to stack traces, 'source-map' is more general-purpose and can be used for a wider range of source map-related tasks, such as creating source maps during build processes.
Readme
This module provides source map support for stack traces in node via the V8 stack trace API. It uses the source-map module to replace the paths and line numbers of source-mapped files with their original paths and line numbers. The output mimics node's stack trace format with the goal of making every compile-to-JS language more of a first-class citizen. Source maps are completely general (not specific to any one language) so you can use source maps with multiple compile-to-JS languages in the same node process.
npm install source-map-support
This module takes effect globally and should be initialized by inserting a call to require('source-map-support') at the top of your code.
The following terminal commands show a stack trace in node with CoffeeScript filenames:
$ cat > demo.coffee
require 'source-map-support'
foo = ->
bar = -> throw new Error 'this is a demo'
bar()
foo()
$ npm install source-map-support
$ git clone https://github.com/michaelficarra/CoffeeScriptRedux.git
$ cd CoffeeScriptRedux && npm install && cd ..
$ CoffeeScriptRedux/bin/coffee --js -i demo.coffee > demo.js
$ echo '//@ sourceMappingURL=demo.js.map' >> demo.js
$ CoffeeScriptRedux/bin/coffee --source-map -i demo.coffee > demo.js.map
$ node demo
demo.coffee:4
bar = -> throw new Error 'this is a demo'
^
Error: this is a demo
at bar (demo.coffee:4:19)
at foo (demo.coffee:5:3)
at Object.<anonymous> (demo.coffee:6:3)
at Object.<anonymous> (demo.coffee:6:6)
at Module._compile (module.js:449:26)
at Object.Module._extensions..js (module.js:467:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Module.runMain (module.js:492:10)
at process.startup.processNextTick.process._tickCallback (node.js:244:9)
Note that the steps above are just to demonstrate this library. If you want good stack traces for your own CoffeeScript project, you can run coffee files directly with CoffeeScriptRedux (use the --eval flag) and the stack traces will have the correct CoffeeScript line numbers.
The following terminal commands show a stack trace in node with TypeScript filenames:
$ cat > demo.ts
declare function require(name: string);
require('source-map-support');
class Foo {
constructor() { this.bar(); }
bar() { throw new Error('this is a demo'); }
}
new Foo();
$ npm install source-map-support typescript
$ node_modules/typescript/bin/tsc -sourcemap demo.ts
$ node demo
demo.ts:6
bar() { throw new Error('this is a demo'); }
^
Error: this is a demo
at Foo.bar (demo.ts:6:16)
at new Foo (demo.ts:5:23)
at Object.<anonymous> (demo.ts:8)
at Module._compile (module.js:449:26)
at Object.Module._extensions..js (module.js:467:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Module.runMain (module.js:492:10)
at process.startup.processNextTick.process._tickCallback (node.js:244:9)
This code is available under the MIT license.
FAQs
Fixes stack traces for files with source maps
We found that source-map-support demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The June TC39 meeting wrapped up this week with eight proposals moving on to the next stage. Here's a quick roundup of the features that the committee approved to advance.
Security News
Cyber extortion in the US and Canada hit record levels in 2023, with ransomware attacks surging and median ransom demands skyrocketing, though fewer companies are choosing to pay ransoms.
Security News
Ecma TC39 is meeting this week and has moved key ECMAScript proposals forward, advancing Deferred Import Evaluation, Error.isError(), RegExp Escaping, and Promise.try to the next stages.