Newbies Guide to Aurelia and TypeScript

5 minute read,

So, after about 24 hours trying to understand and establish a workflow for a new JS framework called Aurelia and TypeScript, I think I’ve finally forged a path to use both in harmony in Visual Studio 2013.

First, some important concepts

Aurelia is written in ES6/ES7. Aurelia is distributed through jspm. The Aurelia distribution through jspm is ES5 code. Aurelia ES5 via jspm is runnable inside your browser.

If you plan on writing view models in TypeScrypt then all you need to be concerned about is transpiling your App.ts (*.ts) View Models into ES5 code.

Get the Tools

To get setup, you’re going to need:

Be sure you can access git and npm from the command line before continuing.

Setup the Framework

Next, in a command prompt make sure you have the following installed:

  • npm install jspm -g
  • npm install tsd -g

At this point, you should go to your github account and create an access token for jspm because jspm will hit a lot of github repos when resolving dependencies. This means you can run up against an anonymous rate limit rather quickly. I did! Also, ensure the token you generate also has “public_repo” permission with it; otherwise you’ll run up against the same rate limit as an anonymous user and jspm requests will get 404s & projects not found. Do not skip this step.

Use the following command to configure jspm and github:

  • jspm registry config github

Create a working folder for your project, and:

  • tsd init
  • jspm install aurelia-framework
  • jspm install aurelia-bootstrapper

Copy all the *.d.ts type definitions inside “jspm_packages\github\aurelia” into a new folder “\typings\aurelia”.

Then run in the root of your project folder:

  • tsd rebundle
 >> added:  
     - aurelia/aurelia-binding.d.ts  
     - aurelia/aurelia-dependency-injection.d.ts  
     - aurelia/aurelia-event-aggregator.d.ts  
     - aurelia/aurelia-framework.d.ts  
     - aurelia/aurelia-history-browser.d.ts  
     - aurelia/aurelia-history.d.ts  
     - aurelia/aurelia-loader-default.d.ts  
     - aurelia/aurelia-loader.d.ts  
     - aurelia/aurelia-logging-console.d.ts  
     - aurelia/aurelia-logging.d.ts  
     - aurelia/aurelia-metadata.d.ts  
     - aurelia/aurelia-path.d.ts  
     - aurelia/aurelia-route-recognizer.d.ts  
     - aurelia/aurelia-router.d.ts  
     - aurelia/aurelia-task-queue.d.ts  
     - aurelia/aurelia-templating-binding.d.ts  
     - aurelia/aurelia-templating.d.ts

Your “typings\tsd.d.ts” file should have all the necessary references now. (TIP: Setup a gulp script to automate this process, You’ll need to re-do this every time you update Aurelia).

Almost there …

Get corejs.d.ts and es6.d.ts from this repo (or if using gulp/npm typescript: node_modules\typescript\bin\lib.es6.d.ts) and add both into “typings\”. You will need to reference these in your *.ts files.

At this point, you can create an empty MVC project inside your working folder at root level. Configure your routes and add a simple view with (no layout). Your .csproj file should be in the same directory with your proejct.json and config.js file.

If you’re using Visual Studio, make sure your TypeScript compiler “Module system” is set to AMD. Project > Properties > TypeScript Build: Module system


Create an app.ts file in the root project folder:

/// <reference path="typings/tsd.d.ts" /> 
/// <reference path="typings/es6.d.ts" /> 
/// <reference path="typings/core-js.d.ts" /> 

import {Router} from 'aurelia-router'; 

export class App { 
    constructor() { 
        this.message = "Hello World"; 


console.log("THIS APP RAN!");

SAVE. Your app.ts -> app.js should have AMD module layout.

Create an app.html view in the root project folder:

    <h2>My App</h2> 



Create an index.cshtml file (Razor / No Shared Layout):

<!DOCTYPE html> 

    <meta name="viewport" content="width=device-width" /> 
    <script src="~/jspm_packages/system.js"></script> 
    <script src="~/config.js"></script> 
<body aurelia-app> 


Run the app, make a request for the application index and poof!


Much success. :)


PRO TIP: Going the extra mile to get decorators working with Dependency Injection


SEE UPDATE: Using TypeScript 1.5 RTM and VS2015

If you’re using Gulp, this is really easy, use a tsconfig.json  and enable emitDecoratorMetadata CompilerOptions flag. If you’re using gulp-typescript pass a configure options object with emitDecoratorMetadata : true.

If you’re using Visual Studio 2013, unload your .csproj, and edit the configuration. Locate the following MSBuild props and add TypeScriptAdditionalFlags:

<PropertyGroup Condition="'$(Configuration)' == 'Debug'"> 
    <TypeScriptAdditionalFlags> $(TypeScriptAdditionalFlags) --emitDecoratorMetadata </TypeScriptAdditionalFlags> 

SAVE. Reload the project. Restart Visual Studio to make sure these changes really take effect. Hit the “Rebuild” on your project and you should now see your decorators working. How? You should see __metadata in the output:


Unfortunately, modifying your .csproj will only work with “MSBuild” invocations like “Build/Rebuild”. This will not work with compile-on-SAVE option inside VS. If you want a workflow of compile-on-SAVE, you’ll ultimately need to use gulp. I really tried hunting for the compiler options VS uses for compiling-on-SAVE but I couldn’t find the hook point. I suspect it’s somewhere deep inside Microsoft’s closed-source TypeScript plug-in for VS2013. TypeScriptAdditionalFlags is simply not picked up by the VS 2013 TypeScript plug-in. Hopefully, this changes in TypeScript 1.5 RTM.

If you decide to use gulp for compile-on-SAVE ensure you DISABLE compile-on-save inside Visual Studio your project options:


Otherwise, both gulp and VS will overwrite each other.

PRO TIP: Using jspm to use packages that are not “officially” in the global registry

Credits to @grofit for the tip:

jspm’s global register is rather limited compared to something like For example, toastr isn’t inside the jspm registry, but you could do this:

jspm install github:CodeSeven/toastr
     Looking up github:CodeSeven/toastr 
     Updating registry cache... 
     Downloading github:CodeSeven/[email protected] 
ok   Installed CodeSeven/toastr as github:CodeSeven/[email protected]^2.1.1 (2.1.1) 
ok   Install tree has no forks.

ok   Install complete.

PRO TIP: Understanding Aurelia Value Converters

See this: Really good tutorial on value converters.

PRO TIP: Using jQuery Plugins with Aurelia


PRO TIP: Don’t use SystemJS to load CSS

Use SystemJS for importing JavaScript that is compatible with jspm and bundled for jspm**... using SystemJS’s CSS plug-in to load CSS will get you in a world of mess. Basically, don’t use **import “bootstrap.css!“ in your ES6 modules. The reason for this is the ES6/SystemJS loader standard was recently changed so CSS ordering is not guaranteed. If you need to load CSS resources in some specified order, use Aurelia’s <require from=”…”> to load your CSS resources.

If you installed JavaScript libraries manually using “jspm github:user/somerepo” (that isn’t part of jspm’s universe nor jspm aware) there’s a good chance that jspm wont setup dependencies (ie: jQuery) required by “user/somerepo”.  Your third-party library can be loaded out of order relative to its dependency (for the exact reason above) because JSPM doesn’t know the package’s dependencies by default if they are not specified. See this blog post for more info: How to deal with dependencies with non-registry JSPM packages


PRO TIP: Careful of camelCase names in View Models


Has to do with hyphenations and DOM elements:

* Since it’s a dom attribute it’s not valid html so Aurelia will automatically hyphenate and try match an attribute.

* Simply put when you have a name that camel case you need to separate it with -


Have fun :)

Brian Chavez


Martin Herløv Andersen

Congratulation (-:

Can you share your setup? Are you using Visual Studio 2013?

I am trying to integrate Aurelia into an existing mvc 5 site and want to convert some of the page that are build with knockout to Aurelia.

How you tried that? if so how do I integrate jspm with

Leave a comment

Your email address will not be published. Required fields are marked *