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.

Feb 012015

As I’ve promised, I will start documenting my experience with Aurelia. If you haven’t read my previous introduction article, click here to get an insight of what Aurelia is.

Since I’m writing this post during Sunday night, I will keep it short and just talk about tooling.

I am not the hacker-notepad-vim kind of guy and the first thing that I need when I work with any technology/framework is a good IDE. I’m a veteran user of Visual Studio + Resharper, so obviously my first choice when starting with Aurelia was to use this.

Unfortunately, VS 2013 + Resharper does not currently have any support for ES6 so it kind of stands in your way. Of course you can still use it as a text editor, but it’s even worse than using any notepad alternative since it always highlights the whole code as having errors and the formatting just messes things up (misaligned curly brackets or parenthesis, wrong spacing etc.).

After searching a bit on the internet and almost loosing all hope to have a nice IDE for this, I found out that JetBrains Webstorm IDE actually has support for ES6, so I will be using this from now on for my experiments.

Just as a hint, if you want to set Webstorm up, check out this short video on how to use Webstorm + Traceur. The default Aurelia template already transpiles ES6 to Javascript, but if you want a more integrated experience, you can configure the IDE to do it for you:



Jan 312015

I will start this post by specifying that I’m a big fan of Durandal. If you don’t know what that is, checkout this website: http://durandaljs.com. Durandal is a single page application (SPA) framework similar to Angular (well, it’s purpose is at least similar). Anyway, I’ve been using it for the last two years for developing enterprise applications and after you get the hang of it it becomes really easy to make clean Javascript apps with a good separation of concerns (the framework is based on the Model – View – Viewmodel pattern).

If you’re into this framework, then you might know that it’s author, Rob Eisenberg has joined the Angular team at the beginning of the last year. As it seems, this collaboration didn’t come out as it was initially expected, so this year Rob has left the Angular team and has returned to developing his OSS projects.

Interestingly, he started a new SPA framework called Aurelia, that takes the best ideas from Durandal and probably his vision of where Angular should have been going to.  Aurelia starts fresh without any legacy and it provides a modern perspective of what Javascript applications should look like. Aurelia is based on a lot of conventions that should make things easy to follow, but it also allows you to override these conventions and provide explicitly the rules for different things.

The first great thing about Aurelia is that it’s very modular, built out of small pieces that can be combined together or that can be replaced with your favorite alternatives. The second great thing is that it leverages the power and clarity that the EcmaScript 6 standard will bring to the Javascript language ( hopefully ) in  the near future.

Although the ES6 is currently just a draft, the Aurelia project template comes with a built-in system that uses transpiling to convert ES6 code to ES5 which is compliant with most browsers by having polyfills for any unsupported feature. This means that if you start writing applications today based on it, it is very likely that when ES6 will become a standard, your app will work natively in the browsers without any change.

Nevertheless, as the minimal documentation states, Aurelia is not bound to the usage of ES6 language constructs and features,  but you can use regular Javascript or if you wish Typescript or Coffeescript.

At the moment I’m just at the beginning of using this framework for a personal project of mine, but I will start a series of posts describing my experience and any hints or guidance that I think it’s relevant to developers that want to use this framework as a foundation for their apps.

Meanwhile, check out the current documentation and getting started tutorial on the products website: http://aurelia.io

Also, if you want to get started with Aurelia,  a good reading is this ES6 overview: https://github.com/lukehoban/es6features

Stay tuned!