• Stars
    star
    2,162
  • Rank 21,326 (Top 0.5 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created almost 12 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Adds source map support to node.js (for stack traces)

Source Map Support

Build Status

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.

Installation and Usage

Node support

Node >=12.12.0

This package is no longer required as Node 12.12.0 introduced the --enable-source-maps flag. (unless you're using the vm module, as --enable-source-maps does not work with vm.runInThisContext).

Node <12.12.0
$ 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, place a source mapping comment somewhere in the file (usually done automatically or with an option by your transpiler):

//# sourceMappingURL=path/to/source.map

If multiple sourceMappingURL comments exist in one file, the last sourceMappingURL comment will be respected (e.g. if a file mentions the comment in code, or went through multiple transpilers). The path should either be absolute or relative to the compiled file.

From here you have two options.

CLI Usage
node -r source-map-support/register compiled.js
Programmatic Usage

Put the following line at the top of the compiled file.

require('source-map-support').install();

It is also possible to install the source map support directly by requiring the register module which can be handy with ES6:

import 'source-map-support/register'

// Instead of:
import sourceMapSupport from 'source-map-support'
sourceMapSupport.install()

Note: if you're using babel-register, it includes source-map-support already.

It is also very useful with Mocha:

$ mocha --require source-map-support/register tests/

Browser support

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>

Options

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;
  }
});

The module will by default assume a browser environment if XMLHttpRequest and window are defined. If either of these do not exist it will instead assume a node environment. In some rare cases, e.g. when running a browser emulation and where both variables are also set, you can explictly specify the environment to be either 'browser' or 'node'.

require('source-map-support').install({
  environment: 'node'
});

To support files with inline source maps, the hookRequire options can be specified, which will monitor all source files for inline source maps.

require('source-map-support').install({
  hookRequire: true
});

This monkey patches the require module loading chain, so is not enabled by default and is not recommended for any sort of production usage.

Demos

Basic Demo

original.js:

throw new Error('test'); // This is the original code

compiled.js:

require('source-map-support').install();

throw new Error('test'); // This is the compiled code
// The next line defines the sourceMapping.
//# sourceMappingURL=compiled.js.map

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

TypeScript Demo

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

There is also the option to use -r source-map-support/register with typescript, without the need add the require('source-map-support').install() in the code base:

$ npm install source-map-support typescript
$ node_modules/typescript/bin/tsc  -sourcemap demo.ts
$ node -r source-map-support/register 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

CoffeeScript Demo

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 coffeescript
$ node_modules/.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)

Tests

This repo contains both automated tests for node and manual tests for the browser. The automated tests can be run using mocha (type mocha in the root directory). To run the manual tests:

License

This code is available under the MIT license.

More Repositories

1

esbuild

An extremely fast bundler for the web
Go
38,106
star
2

thumbhash

A very compact representation of an image placeholder
Swift
3,564
star
3

glfx.js

An image effects library for JavaScript using WebGL
JavaScript
3,288
star
4

csg.js

Constructive solid geometry on meshes using BSP trees in JavaScript
JavaScript
1,791
star
5

lightgl.js

A lightweight WebGL library
JavaScript
1,517
star
6

thinscript

A low-level programming language inspired by TypeScript
C
1,360
star
7

webgl-filter

An image editor in WebGL
JavaScript
1,047
star
8

webgl-water

WebGL Water Demo
JavaScript
1,016
star
9

theta

JavaScript
751
star
10

kiwi

A schema-based binary format for efficiently encoding trees of data
C++
673
star
11

polywasm

A JavaScript polyfill for WebAssembly
JavaScript
669
star
12

source-map-visualization

A simple visualization of source map data
JavaScript
506
star
13

skew

A web-first, cross-platform programming language with an optimizing compiler
JavaScript
411
star
14

glslx

A GLSL type checker, code formatter, and minifier for WebGL
HTML
409
star
15

webgl-path-tracing

Path tracing in GLSL using WebGL
JavaScript
345
star
16

fsm

Finite State Machine Designer
JavaScript
294
star
17

rapt

Robots Are People Too, a platformer in HTML5
C++
209
star
18

float-toy

Use this to build intuition for the IEEE floating-point format
JavaScript
155
star
19

sky

A text editor written in the Skew programming language
Objective-C++
136
star
20

indirectbuffer

A small library for out-of-heap memory in emscripten
C++
129
star
21

font-texture-generator

HTML
122
star
22

buddy-malloc

An implementation of buddy memory allocation
C
100
star
23

pbjs

A minimal implementation of Google Protocol Buffers for JavaScript
JavaScript
95
star
24

packer

Simple port of /packer/ by Dean Edwards to node.js
JavaScript
86
star
25

webgl-recorder

Record all WebGL calls from any app for playback later
JavaScript
81
star
26

socket.io-python

A socket.io bridge for Python
Python
67
star
27

glslx-vscode

GLSLX support in Visual Studio Code
TypeScript
65
star
28

tla-fuzzer

A fuzzer for various top-level await bundling strategies
JavaScript
56
star
29

unwind

Universal disassembler for Python bytecode (supports Python 2 and 3)
Python
49
star
30

node-flatbuffers

An implementation of FlatBuffers in pure JavaScript
JavaScript
48
star
31

figma-fill-rule-editor

A Figma plugin for editing fill rules
HTML
43
star
32

polyfrag

Geometry library that splits polyhedra using 3D planes
C++
38
star
33

esbuild-plugin-glslx

A plugin for esbuild that enables importing *.glslx files.
JavaScript
37
star
34

emscripten-library-generator

A library generator for the emscripten compiler
JavaScript
37
star
35

gl4

A small library for working with OpenGL 4
C++
34
star
36

cs224final

Final project for CS 224: Interactive Computer Graphics
C++
34
star
37

bitscript

An experimental language that compiles to JavaScript and C++
JavaScript
32
star
38

silvermath.js

A high-quality equation editor for JavaScript
JavaScript
32
star
39

decorator-tests

JavaScript
32
star
40

package-json-browser-tests

JavaScript
26
star
41

banner

A python scraper for Banner, Brown University's course catalog
Python
26
star
42

bundler-esm-cjs-tests

JavaScript
23
star
43

gl

A small C++ library for working with OpenGL
C++
23
star
44

bend

A statically-typed programming language for the web
JavaScript
20
star
45

esoptimize

A JavaScript AST optimizer
JavaScript
18
star
46

wasm-lang

A hobby language that compiles to WebAssembly
TypeScript
18
star
47

soda

A course browser for Brown University
JavaScript
18
star
48

OES_texture_float_linear-polyfill

A polyfill for OES_texture_float_linear (a WebGL extension)
JavaScript
17
star
49

node-terminal-notifier

A node API for notifications on Mac OS X Lion
JavaScript
17
star
50

node-spacemouse

An OS X driver for the 3dconnexion SpaceMouse in JavaScript
JavaScript
17
star
51

mineverse

A little experiment, please ignore
JavaScript
17
star
52

cppcodegen

Generates C++ code from a JSON AST
TypeScript
15
star
53

simple_svg_parser

A small library for getting geometry out of an svg file
Python
15
star
54

ride

A web-based IDE for ROS
JavaScript
15
star
55

mobile-touchpads

Use one or more iPhones as remote touchpads in an HTML page
JavaScript
14
star
56

easyxml

Concise XML generation in Python
Python
14
star
57

jest-esbuild-demo

JavaScript
13
star
58

fast-closure-compiler

Make the Google Closure Compiler start faster
JavaScript
13
star
59

webgl-vr-flight

Needs an iPhone 6 and Google Cardboard
HTML
10
star
60

uint8array-json-parser

JSON.parse() for Uint8Array to get around the maximum string size in V8
JavaScript
9
star
61

webgl-vr-editor

Makefile
9
star
62

rand.js

Super simple pseudo-random number generator in JavaScript
JavaScript
8
star
63

oculus-rift-webgl

Oculus Rift experiments with WebGL
8
star
64

skew-nanojpeg

A port of the NanoJPEG library
HTML
7
star
65

minisharp

An optimizing compiler from a subset of C# to JavaScript
C#
6
star
66

mdi-material-ui-inline

Makefile
5
star
67

glvr

GLUT-style bindings for the Oculus Rift
C
5
star
68

gccjs

A simple build tool that uses Google Closure Compiler
Java
5
star
69

skew-lang.org

HTML
5
star
70

skew-vscode

Skew support in Visual Studio Code
TypeScript
5
star
71

skew-imports

4
star
72

css-import-tests

CSS
4
star
73

js-destructuring-fuzzer

JavaScript
4
star
74

section_testing

A Rust library for section-style testing
Rust
4
star
75

dlmax

Python
3
star
76

head-tracker-window

HTML
3
star
77

browser-source-map-bugs

JavaScript
3
star
78

skew-atom

Syntax highlighting for Skew in the Atom editor
CoffeeScript
2
star
79

entry-point-resolve-test

Testing what happens when you bundle a package name
Shell
2
star
80

clang-initializer-list-plugin

A plugin for clang that checks if a constructor is missing a POD field in its initializer list
C++
2
star
81

dome-calibration

Ignore this. I'm only using a public repository because I need a quick HTTPS website.
HTML
2
star
82

SimpleLibOVR

Simple C API for Oculus Rift orientation info
C++
2
star
83

skew-rapt

Makefile
1
star
84

thin-ir

TypeScript
1
star