Setting up ASP.NET 5 and Aurelia from scratch

Aurelia is Rob Eisenberg's new framework for SPA's (single page applications), and I wanted to set it up in combination with ASP.NET.

I'm a fan of Angular, but I've been watching Aurelia closely too.

Angular has a large following, which I find very important, because it guarantees you will have quick and easy support when you encounter a problem.

But I dabbled with Durandal and like Rob Eisenberg's approach. It feels like there has gone a little more thought into it, API-wise. But you can't deny it had a smaller community than Angular. And after Rob's move to the Angular team, I more or less left it behind.

But now that Rob has left Angular and launched Aurelia, effectively Durandal's successor, I've taken a renewed interest in his framework. Especially since it allows me to use ES6, which is something Angular 2.x is promising, but hasn't delivered on yet.

To get up and running with Aurelia quickly, have a look at the skeleton-navigation app. And if you need the combination with ASP.NET, there's a project by Ashley Grant.

I was interested in getting ASP.NET and Aurelia running but starting from a new ASP.NET MVC project, without Aurelia already integrated. So these are the steps necessary.

In my case, I chose the ASP.NET vNext (version 5). This means these are fairly specific steps for that platform, as there are quite some changes between ASP.NET 4.x and ASP.NET 5. But it makes it easier to integrate Gulp, JSPM, NPM, etc.

Update: make sure you have NodeJs, npm and jspm installed.

  1. First, create a new ASP.NET project.

  2. Initialize jspm by opening a command-line window, navigating to the folder one level above your wwwroot folder and executing jspm init.

  3. Answer all questions with the default answer (just press enter), except for the server base URL (./wwwroot). The default transpiler should be Babel, which is ok. (A transpiler will convert ES6 to ES5).

  4. This is optional, but the Aurelia samples (like the skeleton-navigation app) uses ES7 features (like annotations), so if you want to use those features too, we need to tell Babel to use Experimental features. Open config.js (in the wwwroot folder) and in the babelOptions property, add "stage" : 0. This allows us to use ES7 features too.

  5. Next, install Aurelia, by running jspm install aurelia-framework and jspm install aurelia-bootstrapper.

  6. In Index.cshtml, tell Aurelia where the application is to take place by adding aurelia-app to your body tag or any other tag where you want the Aurelia app to run.

  7. Add the jspm_packages/system.js, config.js scripts to your _Layout.cshtml file (you could do this in your Index.cshtml too).

  8. Import the Aurelia bootstrapper by adding:
    <script>System.import('aurelia-bootstrapper');</script>

    Together, this will tell SystemJS to load the bootstrapper. Also we're transpiling ES6 to ES5 on the fly, without the need for build tasks.

  9. Now, add an app.js file to your wwwroot folder. The easiest thing to do is to take the contents of the App class from the skeleton-navigation app and change it as per your needs.

  10. Add an app.html file to the wwwroot folder, just like in the the skeleton-navigation app. It should contain at least a <router-view> element. Your templates will be loaded into this tag.

  11. Now you're all set!

Pages in Aurelia are usually just a combination of a template (HTML file) and a class (javascript file). The convention is to give both files the same name (for example, users.html and users.js). Then, you just need to add the path to your route (check out the docs). This part is no different from other Aurelia apps.

Update I've posted an update on these steps, explaining how to transpile the javascript when building, instead of having it done at runtime.