JavaScript Debugging with Source Maps in MyEclipse

What are source maps?

It can be difficult to debug JavaScript files loaded by a browser or Node.js runtime as a result of transpilation (TypeScript, CoffeeScript, etc.), minification (minifyJS, UglifyJS, etc.), bundling (Browserify, etc.), or some other process from source files. Usually generated files have code that is hard to understand or significantly different from the original source code. This is where source maps come into the picture. Most popular processing tools can produce them and allow the debugger to represent current code execution position in the context of the original file. Learn more 

How do I configure my tool to generate source maps?

To take advantage of source maps, you need to appropriately configure your processing tool. Each tool has its own specific way of doing configuration; therefore, we recommend using Gulp as a builder for your projects, as it allows you to configure different tools in a single place in a uniform way. However, we know that it’s not the best solution for everyone, thus we will provide example configurations for several tools.

Gulp

We recommend using Gulp for building your projects, as its support for source maps is the most flexible. Here is an example with CoffeeScript:

gulp.task('coffee', function() {
  gulp.src('./src/*.coffee')
	.pipe(sourcemaps.init())
	.pipe(coffee({bare: true}).on('error', gutil.log))
	.pipe(sourcemaps.write({sourceRoot: “workspace:my-coffee-project/”}))
	.pipe(gulp.dest('./build/'));
});

For more information on how to properly specify sourceRoot, refer to the following question. For detailed information on Gulp source map usage, please visit this link.

Browserify

command line—add `–debug` parameter; e.g. browserify main.js –debug

build script—add `debug: true` option to browserify call; e.g. browserify({standalone: “main”, debug: true})

Note that Browserify does not allow you to specify sourceRoot; it always embeds file contents and saves absolute filesystem paths for source files when generating source maps. This means that you don’t need any further configuration to get workspace linking for files, but you need to rebuild source when you move your project to a different location on the filesystem.

TypeScript

It is best to use the tsconfig.json file. If you generate JS files next to your TS files, you just need to specify sourceMap property to true, otherwise you also need to specify sourceRoot property. Below is an example:

{
  "compilerOptions": {
  	"target": "es5",
  	"outDir": "target",
  	"sourceMap": true,
  	"sourceRoot": "workspace:my-ts-project/"
  },
  "files": [
  	"main.ts",
  	"utils.ts"
  ]
}

For more information on how to properly specify sourceRoot, refer to the following question. For detailed information on source map support in TypeScript visit the following links:

https://github.com/Microsoft/TypeScript/wiki/tsconfig.json

https://github.com/Microsoft/TypeScript/wiki/Compiler-Options

How should I specify source root?

The biggest advantage of using the JavaScript Debugger is that you can put breakpoints in files from your workspace. This works with source maps as well, however, the debugger has to know where to look for appropriate files in the workspace. There are 4 ways to specify the location of sources:

1. Workspace relative—URL with schema “workspace” followed by name of project and path within the project. This is the suggested approach to use with the debugger as it is straightforward, unequivocal and most portable.
   
   Browser
   Map file location—http://localhost:8080/my-web-project/maps/generated.js.map
   Source file name—source.js
   Source root—workspace:my-web-project/src/main/js
   Source—Expected to be in src/main/js/source.js in my-web-project project
   
   Node.js
   Map file location—C:/Workspace/My Node Project/target/maps/generated.js.map
   Source file name—source.js
   Source root—workspace:My Node Project/src/
   Source—Expected to be in src/source.js in My Node Project project
   
   
2. Absolute path—specified source root path denotes a file system folder
   
   Browser
   Map file location—http://localhost:8080/my-web-project/maps/generated.js.map
   Source file name—source.js
   Source root—C:/Workspace/my-web-project/src
   Source—Expected to be in C:/Workspace/my-web-project/src/source.js
   Further location of the file in the workspace is performed
   
   Node.js
   Map file location—C:/Workspace/My Project/target/maps/generated.js.map
   Source file name—source.js
   Source root—C:/Workspace/My Project/src”
   Source—Expected to be in C:/Workspace/My Project/src/source.js
   Further location of the file in the workspace is performed
   
   
3. Relative to source map file—path is resolved against location of the source map file or the original file if you have inline source map; requires the source file to be available under the resolved location.
   
   Browser
   Map file location—http://localhost:8080/my-web-project/maps/generated.js.map
   Source file name—source.js
   Source root—../sources
   Source—Expected to be in http://localhost:8080/my-web-project/sources/source.js
   Further mapping from URL to workspace is happening according to your Web Application launch setup
   
   Node.js
   Map file location—C:/Workspace/My Project/target/maps/generated.js.map
   Source file name—source.js
   Source root—../../src
   Source—Expected to be in C:/Workspace/My Project/src/source.js
   Further location of the file in the workspace is performed
   
   
4. Host relative—path is resolved against the web page host name. This mode works only with JavaScript Web Applications and it requires the source file to be available under the resolved location.
   
   Browser
   Map file location—http://localhost:8080/my-web-project/js/maps/app/generated.js.map
   Source file name—app/source.js
   Source root—/my-web-project/sources
   Source—Expected to be in http://localhost:8080/my-web-project/sources/app/source.js
   Further mapping from URL to workspace is happening according to your Web Application launch setup
   
   

How do I know if source files are found in the workspace?

You can check which scripts are loaded by your browser or Node.js in Loaded JavaScript view. Nodes of scripts, which provide source maps, will be expandable and you will see the list of all source files. Each file that can be located in the workspace is marked with a linked icon  and each file that cannot be located is marked with a warning sign . You can still see contents of the files even if they are not located in the workspace.

The Loaded JavaScript view indicates which files are in the workspace

What if I don’t have source files in the workspace?

If you have configured your source maps to include contents, you will be able to see and use for debugging those embedded sources, even if source files cannot be located in the workspace. Moreover, those embedded sources will be used automatically when you explore your stack trace.

Can I put breakpoints in non-JavaScript/TypeScript files?

Breakpoints work with other languages, such as CoffeeScript. All you need to do is open the file with the JavaScript Editor. It is best to specify the association in the preferences from General>Editors>File Associations. Find your file extension in the list or use the Add button to add a new extension. Click on it and add JavaScript Editor or MyEclipse JavaScript Editor to the list. Make sure it is the default one. If you are using some specialized editor for your non-JS/TS files, please let us know at support@genuitec.com and we will make sure your editor is supported and you can put breakpoints in it.

How do I disable source map support?

To disable source map support, open your debugging launch configuration and clear the Enable source maps support check box.