Aurelia is a next gen JavaScript client framework for mobile, desktop and web that leverages simple conventions to empower your creativity. — http://aurelia.io/

The thing that intrigued me about the Aurelia framework when I first heard about it was it’s emphasis on convention over configuration. The lead on this project Rob Eisenberg (@EisenbergEffect) has a history of creating developer friendly frameworks which tend to provide the simplest path possible for getting things done. Like with existing frameworks that Rob has developed such as Caliburn Micro, Aurelia provides simple conventions out of the box, with the ability to go in and tweak how how they work if needed.

The Aurelia website has a really good quick start guide that will allow you to get from zero to full SPA in minutes. It provides a Yeoman generator, or skeleton application template so that you can hit the ground running.

The below steps walk through the process for setting up an Aurelia project from the ground up, and should give you an idea of the basic building blocks that make up the Aurelia project structure, and provide a base that you can build from to create a rich single page application.

I’ve used NodeJS and Express for the back end web server. The first part of this guide walks through setting up these dependencies. You can skip directly to step three if you are using a different server side frameworks as the final two steps remain the same.

Steps

1. Set up the project structure
2. Set up Node, NPM, Gulp, Express
3. Set up JSPM
4. Install and configure Aurelia JSPM package

Project Structure

Create the project directory:

mkdir aurelia-hello

Move into the project directory:

cd aurelia-hello

Set up Node, NPM, Gulp, Express

npm install gulp --save-dev
npm install express --save-dev

Initialise NPM and follow the default prompts to set up the package.json

npm init

Install gulp-nodemon NPM package to allow for the express server to be automatically restarted on file changes.

npm install gulp-nodemon --save-dev

Install the browser-sync NPM package to allow for the browser to be refreshed automatically on file changes.

npm install browser-sync --save-dev

Create the gulpfile.js to watch for changes in the js, html, and css files, and initialise the Express server.

touch gulpfile.js

//open the text editor of choice 
//(in my case atom)atom .

Create the express application entry point file:

touch app.js

Initialise the server and set up live-reload to refresh the browser when the source changes.

Create the app directory and a test.html file to ensure that everything is set up correctly.

mkdir app
touch app/index.html

If everything loaded successfully you should see something like this:

Aurelia uses the JSPM package manager to allow applications to be structured a clean and future proof method using ES6 modules with SystemJS.

Install JSPM globally so that we can use it to start installing the required JSPM packages via the command line, then initialise the configuration file:

Set up JSPM

npm install jspm -g
jspm init

You will then be prompted with questions as to how JSPM should be configured. The first prompt just sets up the package.json, which we don’t need to worry about since we already have one. The second prompt should ask which directory you want to serve static files from. Our files are being served from the app directory so we’ll enter app:

Enter server baseURL (public folder path) [./]:app

We’ll select the defaults for the next few prompts. The next prompt we care about is the transpiler type. My preference is to use the babel transpiler so we’ll enter babel:

Which ES6 transpiler would you like to use, 
Babel, TypeScript or Traceur? [traceur]:babel

Create the Aurelia application entry point file within the app directory, as well as a small test file that we can use to ensure that JSPM is set up correctly:

touch app/app.js
touch app/status.js

Modify the contents of the status.js file to report that the application is all up and running:

Modify the contents of the Aurelia app directory to import the status module and use it to report the JSPM status to the console:

Modify the contents of the test.html file to use the newly created status module:

Re-run the gulp command and check the console output in the browser window. You should now see a message letting you know that JSPM has been configured correctly:

Now that we’ve confirmed that we have all of Aurelia’s dependencies set up correctly we’ll move on to setting up the Aurelia framework. We can do this by running a couple of simple JSPM commands.

Install and configure Aurelia JSPM package

jspm install aurelia-framework
jspm install aurelia-bootstrapper

Now that we’ve got Aurelia installed, there are a few steps that we need to go through to wire it up with our application. The first is to swap out our status reporter app.js file include in the test.html file for a reference to the aurelia-bootstrapper. The aurelia-bootstrapper will then take care of the Aurelia application lifecycle for us:

The Aurelia bootstrapper looks for a view-model in a file called app.js by convention on startup. Since we already have an app.js file we’ll replace its contents with the following snippet of code that reports Aurelia has been bootstrapped successfully:

We don’t yet have the app.html file, so let’s create it:

touch app/app.html

Aurelia views are defined using HTML templates. The app.js view-model that we created looks for a template file called app.html file by convention:

The last step is to specify whereabouts in the DOM the Aurelia app view should be injected. We’ll create a new DIV for the Aurelia app and inject it there:

If you re-load the browser you should now see that Aurelia has injected the status message that we set in our view-model:

This concludes our Aurelia setup, we’ve got a basic structure in place with JSPM, the Aurelia Boostrapper, and the app view-model + view. With this basic structure we’ve put in place a good foundation on which to start building richer SPA’s with Aurelia.