Update README.md
This commit is contained in:
Evan Wallace
parent
2d4588e209
commit
ca0094664f
157
README.md
157
README.md
@ -2,62 +2,115 @@
|
||||
|
||||
This module provides source map support for stack traces in node via the [V8 stack trace API](http://code.google.com/p/v8/wiki/JavaScriptStackTraceApi). It uses the [source-map](https://github.com/mozilla/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
|
||||
## Installation and Usage
|
||||
|
||||
npm install source-map-support
|
||||
|
||||
This module takes effect globally and should be initialized by inserting `require('source-map-support').install()` at the top of your code.
|
||||
Source maps can be generated using libraries such as [source-map-index-generator](https://github.com/twolfson/source-map-index-generator). Once you have a valid source map, insert the following two lines at the top of your compiled code:
|
||||
|
||||
### Usage
|
||||
|
||||
To use a valid source map (generated using something like [source-map-index-generator][sourceMapGenerator]), the compiled code should contain the following two extra lines:
|
||||
|
||||
[sourceMapGenerator]:[https://github.com/twolfson/source-map-index-generator]
|
||||
|
||||
//@sourceMappingURL=path/to/sourceMapFile.json
|
||||
//# sourceMappingURL=path/to/source.map
|
||||
require('source-map-support').install();
|
||||
|
||||
|
||||
### Demos
|
||||
The path should either be absolute or relative to the compiled file.
|
||||
|
||||
#### Basic Demo
|
||||
## 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](https://github.com/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;
|
||||
}
|
||||
});
|
||||
|
||||
## Demos
|
||||
|
||||
### Basic Demo
|
||||
|
||||
original.js:
|
||||
|
||||
throw new Error("test");
|
||||
throw new Error('test'); // This is the original code
|
||||
|
||||
compiled.js:
|
||||
|
||||
//#sourceMappingURL=original.sourcemap.json
|
||||
//# sourceMappingURL=compiled.js.map
|
||||
require('source-map-support').install();
|
||||
|
||||
throw new Error("test");
|
||||
throw new Error('test'); // This is the compiled code
|
||||
|
||||
original.sourcemap.json:
|
||||
compiled.js.map:
|
||||
|
||||
{"version":3,"file":"compiled.js","sources":["original.js"],"names":[],"mappings":";;;AAAA,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC"}
|
||||
{
|
||||
"version": 3,
|
||||
"file": "compiled.js",
|
||||
"sources": ["original.js"],
|
||||
"names": [],
|
||||
"mappings": ";;;AAAA,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC"
|
||||
}
|
||||
|
||||
After running compiled.js you should get the following outout:
|
||||
Run compiled.js using node (notice how the stack trace uses original.js instead of compiled.js):
|
||||
|
||||
/path/to/original.js:1
|
||||
throw new Error("test");
|
||||
$ node compiled.js
|
||||
|
||||
original.js:1
|
||||
throw new Error("test"); // This is the original code
|
||||
^
|
||||
Error: test
|
||||
at Object.<anonymous> (/path/to/original.js:1:7)
|
||||
at Module._compile (module.js:456:26)
|
||||
at Object.Module._extensions..js (module.js:474:10)
|
||||
at Object.<anonymous> (original.js:1:7)
|
||||
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 Function.Module.runMain (module.js:497:10)
|
||||
at startup (node.js:119:16)
|
||||
at node.js:901:3
|
||||
at Module.runMain (module.js:492:10)
|
||||
at process.startup.processNextTick.process._tickCallback (node.js:244:9)
|
||||
|
||||
### TypeScript Demo
|
||||
|
||||
#### CoffeeScript Demo
|
||||
demo.ts:
|
||||
|
||||
The following terminal commands show a stack trace in node with CoffeeScript filenames:
|
||||
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();
|
||||
|
||||
$ cat > demo.coffee
|
||||
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: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)
|
||||
|
||||
### CoffeeScript Demo
|
||||
|
||||
demo.coffee:
|
||||
|
||||
require('source-map-support').install()
|
||||
foo = ->
|
||||
@ -65,9 +118,11 @@ The following terminal commands show a stack trace in node with CoffeeScript fil
|
||||
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
|
||||
$ node demo.js
|
||||
|
||||
demo.coffee:4
|
||||
bar = -> throw new Error 'this is a demo'
|
||||
@ -84,46 +139,6 @@ The following terminal commands show a stack trace in node with CoffeeScript fil
|
||||
at Module.runMain (module.js:492:10)
|
||||
at process.startup.processNextTick.process._tickCallback (node.js:244:9)
|
||||
|
||||
#### TypeScript Demo
|
||||
|
||||
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').install();
|
||||
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)
|
||||
|
||||
### 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 above). 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
|
||||
});
|
||||
|
||||
### License
|
||||
## License
|
||||
|
||||
This code is available under the [MIT license](http://opensource.org/licenses/MIT).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user