Feb 122015

As I’ve promised in my previous post, I am going to continue describing my experience with Aurelia.

The first thing that I’ve noticed while working with the framework is that the default template does not enable source maps. Source maps are files with the .js.map extension which “tell” the browser or debugger how to map the transpiled (JavaScript) code to the original script (ES6 or TypeScript). This means that if you have the correct sourcemaps, you are able to debug the code you’ve written using ES6 directly in the browser, even though in reality it is running pure javascript. This works in a similar way to how PDB files work in .NET when debugging C# or VB applications.

If you don’t have sourcemaps, then you’re making your life much harder because you’ll be looking at the generated (transpiled) javascript which sometimes is not the easiest to read (BTW I will come back to this subject a bit later).

Enabling source maps for your Aurelia project

In order to add support for these sourcemaps, you need to use the “gulp-sourcemaps” library. There are two steps to this:

Step 1 – edit the packages.json file located in the project root and under “devDependencies” add the following line:

"gulp-sourcemaps": "^1.3.0"

This will ensure that when you build the project, the node package manager (npm) will install this dependency and you will be able to use it in your build process. Which takes us to:

Step 2 – change the gulpfile.js in the project root to add source map generation

You need to add the following line somewhere at the beginning of the file (after all require statements is a good place):

var sourcemaps = require('gulp-sourcemaps');

Source map generation conflicts with the default compiler settings, so you will need to comment out (or delete) the sourceMapName and sourceFileName compiler options.

Search for the “build-system” task and replace it with the following:

gulp.task('build-system', function () {
    return gulp.src(path.source)
        .pipe(changed(path.output, {extension: '.js'}))
        .pipe(to5(assign({}, compilerOptions, {modules: 'system'})))

This change will actually “inject” the sourcemaps plugin in the build pipeline. The end result is that whenever the project gets built, it will generate one *.js.map file for each transpiled file (inside the dist folder). The second effect, as stated above is that you will be able to debug using FireBug or Chrome Developer Tools directly the ES6 source code and the browser will internally map the breakpoints and code lines to the transpiled code.

Get the entire gulp.js file here: https://gist.github.com/nseba/369f0184d587b7235caa


One of the things that gets annoying relatively quick is the fact that the Aurelia framework that gets installed using the official Getting Started guide will contain only the transpiled files. Together with the extremely thin documentation available right now, you will have to do a lot of digging in the Aurelia’s github repositories to figure out how some things are working. This is unfortunately not so easy all the time, but hopefully this will get better once the project is more mature.

The only thing that I would have liked more from the framework would have been to include the ES6 source of Aurelia and to build it normally together with my code. This would generate the correct source maps and debugging would be much easier.

Another caveat comes when using source maps for debugging is that even if the browser can track the application execution and match it with the ES6 source code, there are some situations in which you need to be aware that you are actually still running Javascript. An example of such a situation is when having a breakpoint inside a ES6 lambda (arrow function) body. Since in ES6 (same is in TypeScript) lambdas will capture the outer this, it means that you can  write code like this:

class A
        this.x = 1;

       this.onclick = () => {
           this.x += 1;     // "this.x" will refer to the same member field x defined in the constructor above because lambdas capture the this from the parent scope.

The trick here is that the compiled code will look something like (NOTE: this is not 100% how it gets transpiled):

class A
       this.x = 1;
       var _this = this;
       this.onclick =  function () {
           _this.x += 1;     // notice the use of the _this variable to capture the this from the outer scope

When you have the breakpoint set inside the onclick function, the developer tools (or FireBug) will show you the original code with this.x += 1. But if you add the “this” to the watch, you will notice it’s undefined or it has some unexpected value (typically it is thee value of the  window object). To be able to debug correctly, you’ll need to add the “_this” to the watch. This is one very common issue that you’ll encounter while working with any transpiled language.

In the next post I will discuss some basic aspects of running the project and writing logging information using the provided framework. This should cover the minimum required to run and debug the application.

Final notes

Based on the messages that I’ve received, I’ve also checked out various TypeScript Aurelia-based frameworks. While I am a big fan of TypeScript, I am not going to switch to that for several reasons:

  1. The type definitions are at the moment incomplete. This means that you’ll have to update them by hand which can become a rather complex task due to the early nature of the Aurelia project.
  2. I really like the string interpolation feature from ES6. I’m looking forward to the moment TypeScript will support this.
  3. The import mechanism for ES6 is way cleaner than the one in TypeScript. This is another point where I hope TypeScript will be adjusted because it results in much cleaner code.
  4. Overall the language features provided by ES6 make things much cleaner and easier to write. Looking at the TypeScript roadmap, it might become really attractive if it adopts more of the ES6 standard features.

Anyway, given the above, when the TypeScript framework is good enough, the transition can be made relatively easy from ES6 to TS.