Newbies Guide to Aurelia and TypeScript

5 minute read, July 03, 2015

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:

NodeJS
Git

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"; 
    } 

    message:string; 
} 

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:

<template> 
     
    <h2>My App</h2> 
     
    <span>${message}</span> 

</template>

Save.

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

<!DOCTYPE html> 

<html> 
<head> 
    <meta name="viewport" content="width=device-width" /> 
    <script src="~/jspm_packages/system.js"></script> 
    <script src="~/config.js"></script> 
    <title></title> 
</head> 
<body aurelia-app> 
     
    <script> 
        System.import("aurelia-bootstrapper"); 
    </script> 
</body> 
</html>

SAVE.

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'"> 
    <TypeScriptModuleKind>amd</TypeScriptModuleKind> 
    <TypeScriptAdditionalFlags> $(TypeScriptAdditionalFlags) --emitDecoratorMetadata </TypeScriptAdditionalFlags> 
</PropertyGroup>

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 bower.io. 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/toastr@^2.1.1 (2.1.1) 
ok   Install tree has no forks.

ok   Install complete.

PRO TIP: Understanding Aurelia Value Converters

See this: http://jdanyow.github.io/aurelia-converters-sample/. 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:

http://aurelia.io/docs.html#custom-attributes

* 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

Share on

Twitter Facebook Google+ LinkedIn

Comments

Martin Herløv Andersen

July 04, 2015 at 11:38 AM

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 asp.net?

rob

January 30, 2016 at 02:18 AM

Nice post! wondering if you could show an example of using Aurelia for SharePoint apps?

cheers

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