Security News
NIST Misses 2024 Deadline to Clear NVD Backlog
NIST has failed to meet its self-imposed deadline of clearing the NVD's backlog by the end of the fiscal year. Meanwhile, CVE's awaiting analysis have increased by 33% since June.
source-map-support
Advanced tools
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.
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
Source maps can be generated using libraries such as source-map-index-generator. Once you have a valid source map, insert the following two lines at the top of your compiled code:
//# sourceMappingURL=path/to/source.map
require('source-map-support').install();
The path should either be absolute or relative to the compiled file.
This library also works in Chrome. While the DevTools console already supports source maps, the V8 engine doesn't and Error.prototype.stack
will be incorrect without this library. Everything will just work if you deploy your source files using browserify. Just make sure to pass the --debug
flag to the browserify command so your source maps are included in the bundled code.
This library also works if you use another build process or just include the source files directly. In this case, include the file browser-source-map-support.js
in your page and call sourceMapSupport.install()
. It contains the whole library already bundled for the browser using browserify.
<script src="browser-source-map-support.js"></script>
<script>sourceMapSupport.install();</script>
This library also works if you use AMD (Asynchronous Module Definition), which is used in tools like RequireJS. Just list browser-source-map-support
as a dependency:
<script>
define(['browser-source-map-support'], function(sourceMapSupport) {
sourceMapSupport.install();
});
</script>
This module installs two things: a change to the stack
property on Error
objects and a handler for uncaught exceptions that mimics node's default exception handler (the handler can be seen in the demos below). You may want to disable the handler if you have your own uncaught exception handler. This can be done by passing an argument to the installer:
require('source-map-support').install({
handleUncaughtExceptions: false
});
This module loads source maps from the filesystem by default. You can provide alternate loading behavior through a callback as shown below. For example, Meteor keeps all source maps cached in memory to avoid disk access.
require('source-map-support').install({
retrieveSourceMap: function(source) {
if (source === 'compiled.js') {
return {
url: 'original.js',
map: fs.readFileSync('compiled.js.map', 'utf8')
};
}
return null;
}
});
original.js:
throw new Error('test'); // This is the original code
compiled.js:
//# sourceMappingURL=compiled.js.map
require('source-map-support').install();
throw new Error('test'); // This is the compiled code
compiled.js.map:
{
"version": 3,
"file": "compiled.js",
"sources": ["original.js"],
"names": [],
"mappings": ";;;AAAA,MAAM,IAAI"
}
Run compiled.js using node (notice how the stack trace uses original.js instead of compiled.js):
$ node compiled.js
original.js:1
throw new Error('test'); // This is the original code
^
Error: test
at Object.<anonymous> (original.js:1:7)
at Module._compile (module.js:456:26)
at Object.Module._extensions..js (module.js:474:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Function.Module.runMain (module.js:497:10)
at startup (node.js:119:16)
at node.js:901:3
demo.ts:
declare function require(name: string);
require('source-map-support').install();
class Foo {
constructor() { this.bar(); }
bar() { throw new Error('this is a demo'); }
}
new Foo();
Compile and run the file using the TypeScript compiler from the terminal:
$ npm install source-map-support typescript
$ node_modules/typescript/bin/tsc -sourcemap demo.ts
$ node demo.js
demo.ts:5
bar() { throw new Error('this is a demo'); }
^
Error: this is a demo
at Foo.bar (demo.ts:5:17)
at new Foo (demo.ts:4:24)
at Object.<anonymous> (demo.ts:7:1)
at Module._compile (module.js:456:26)
at Object.Module._extensions..js (module.js:474:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Function.Module.runMain (module.js:497:10)
at startup (node.js:119:16)
at node.js:901:3
demo.coffee:
require('source-map-support').install()
foo = ->
bar = -> throw new Error 'this is a demo'
bar()
foo()
Compile and run the file using the CoffeeScript compiler from the terminal:
$ npm install source-map-support coffee-script
$ node_modules/coffee-script/bin/coffee --map --compile demo.coffee
$ node demo.js
demo.coffee:3
bar = -> throw new Error 'this is a demo'
^
Error: this is a demo
at bar (demo.coffee:3:22)
at foo (demo.coffee:4:3)
at Object.<anonymous> (demo.coffee:5:1)
at Object.<anonymous> (demo.coffee:1:1)
at Module._compile (module.js:456:26)
at Object.Module._extensions..js (module.js:474:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Function.Module.runMain (module.js:497:10)
at startup (node.js:119:16)
This code is available under the MIT license.
FAQs
Fixes stack traces for files with source maps
The npm package source-map-support receives a total of 32,729,576 weekly downloads. As such, source-map-support popularity was classified as popular.
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
NIST has failed to meet its self-imposed deadline of clearing the NVD's backlog by the end of the fiscal year. Meanwhile, CVE's awaiting analysis have increased by 33% since June.
Security News
Cloudflare has launched a setup wizard allowing users to easily create and manage a security.txt file for vulnerability disclosure on their websites.
Security News
The Socket Research team breaks down a malicious npm package targeting the legitimate DOMPurify library. It uses obfuscated code to hide that it is exfiltrating browser and crypto wallet data.