From Aurelia in Action by Sean Hunter

With Aurelia, one of the themes that stands out is freedom of choice. This article discusses the pros and cons of three main options available to developers who want to create a new project with Aurelia.

Save 37% on Aurelia in Action. Just enter code fccshunter into the discount code box at checkout at

Building Aurelia

The web development community is varied, both in terms of the kinds of applications we build and the opinions and approaches we have in mind when building them. Because of this, the Aurelia core team always makes sure to include alternative options where available. As such, there are three main options available for developers looking to create a new Aurelia project. The appropriate approach depends on the goal you have in mind for your current project. I’ll start by outlining each of the popular choices for creating new projects with Aurelia, and mentioning some of the pros and cons of each. This should assist you in picking the most appropriate option for later projects. We’ll then dive into creating a new project via the third option listed – the Aurelia CLI.

Installing Node.js

We’re going to start with a short walkthrough on installing the things you need to make Aurelia work. If you already have the prerequisite software and frameworks installed and want to skip this part, go ahead and jump to the section titled: Option 1 – Download the quick start.


So, you might be asking yourself: if Aurelia is a client side framework, why do we need Node.js? Aurelia applications are prepared for the browser using the Node.js build tools such as Gulp and RequireJS. Even though Aurelia applications don’t require Node.js to run, we need it to build our project into a deployable package which can be loaded and run in the browser. You can think of this like a compilation step in server-side languages like C, .NET, or Java, where you need a separate set of build tools on your development machine (such as MSBUILD on the Microsoft .NET side, or Javac on the Java side), as compared with what you need to run the deployed executable. This transformation process is summarized in figure 1.

Figure 1 Node.js is required to take the ESNext source files for your application and transform them into a package which can be run in the browser.

Go ahead and download and install Node.js current LTS from the Node.js website using the installation package specific to your environment.


You can download the Node.js installation package for Macintosh from the Node.js website: If you prefer the console you can also install this with Homebrew.


You can install Node.js on windows by downloading and running the MSI from the Node.js website:, or alternatively if you prefer the console this can be achieved using Chocolatey


Node.js installation on Linux is dependent on the distribution. This page on the Node.js website can help you select the most appropriate installation method based on your Linux distribution:

Installing the Aurelia CLI tool

These are the three main pathways for creating a new project with Aurelia:

  1. The quick start ZIP download.
  2. The Aurelia skeleton projects
  3. The Aurelia CLI (selected option)

We’ll use the Aurelia CLI to create and run our project. The Aurelia CLI is a Node.js application that should be installed globally on your development machine. It allows you to do the following tasks:

Create a new project with the development time dependencies you’d prefer (for example a CSS pre-processor like SASS or plain CSS)

  • Download and install NPM packages into your project using NPM or Yarn (a package manager developed by Facebook that improves package installation speed
  • Build the project, transpiling your ESNext/Typescript source files into ES5 and bundling them for delivery to the browser
  • Host the project in a BrowserSync HTTP server that auto-reloads the page when changes are made to your source files
  • Unit and integration testing you project

After you have Node.js installed, you can install the Aurelia CLI globally using the following command:

npm install aurelia-cli –g


If you run into problems with the Aurelia CLI, it’s likely due to one of the following causes:

  • Unsupported version of Node.js (ensure you’re running 6.x).
  • Unsupported version of NPM. To use front-end dependencies such as Bootstrap, which are installed via the Aurelia CLI, you’ll need a flat directory structure for your installed packages. The flat directory structure wasn’t supported until NPM 3, and it’s recommended that you update to this version before creating new projects with the Aurelia CLI. You can check which NPM version you’ve got installed using the npm -v command. If it shows 3.x or greater then you’re good to go. If not, you can update to the latest version of NPM using the command npm install npm -g.
  • Outdated or broken installation of the Aurelia CLI (uninstall and re-install the CLI using NPM – npm uninstall aurelia-cli -g, npm install aurelia-cli -g).

Now that you’ve got Node.js and the Aurelia CLI installed and running let’s move on to our main topic: options for starting your first Aurelia project.

Option 1 – Download the quick start

The quick start option is a ZIP package you can download from the Aurelia website. This is useful if you want to download the project and get started without performing any kind of setup work installing framework dependencies. Typically, this isn’t used for real-world applications because it performs transpilation from ESNext to ES5 on the fly in the browser (a slow process). Also, this project is missing some items out of the box, which you’d need to add anyway. If you’d like to explore this option, you can download the ZIP file from

Note Aurelia is platform-agnostic but at the moment there’s only a ZIP available and no .tar.gz.

Option 2 – Skeleton application

The second option for getting started with Aurelia’s to download one of the sample Skeleton applications from GitHub. These are basic shell projects with many of the things you’ll need in a standard single-page application such as routing, a navigation menu, and framework dependencies, already created or referenced. The benefit of this option’s that there are Skeletons out there for many of the standard setups you might choose. For example, there’s a Skeleton Navigation application that uses Typescript instead of ECMAScript, and one that uses WebPack as an alternative to System JS, which are different module-loading and application-bundling options. Don’t worry if some of these terms are fuzzy; we’ll unpack them as we proceed through the article.

Option 3 – Aurelia CLI

This option’s our choice for today. Aurelia applications are built using ESNext or Typescript. Because of this, a collection of Node.js tools are required to create Aurelia applications and perform tasks such as transpilation from ESNext/Typescript to ES5, module loading, and build automation. Many alternative tooling options can be found for each of these tasks, and the tools of choice within the JavaScript community change rapidly. The Aurelia CLI streamlines the process of creating and building Aurelia applications by setting up reasonable defaults for each of these tools, and in some cases allowing you to swap out a given default for your tool of choice (e.g. TypeScript rather than Babel.js). The Aurelia CLI is also updated to incorporate new tooling options as they emerge, allowing you to easily integrate them into your development process. These tools make up a front-end build pipeline.

The build pipeline You can think of a build pipeline like the standard build process from the back-end development world. It takes your source code and translates it into something that the browser understands how to run.

It’s time to get your hands dirty creating your first Aurelia application. In the next section, you’ll create the first iteration of an application called my-books using the Aurelia CLI.

Creating the my-books project

Before continuing with this section, please ensure that you’ve the pre-requisites: Node.js and the Aurelia CLI NPM package installed. Installation instructions can be found at the beginning of the article. Let’s begin by generating a new my-books application with the Aurelia CLI.

Tip If you bear with me, I’ll get you to run a set of commands at the Aurelia CLI terminal to generate a basic hello world application. That way you’ll have a concrete running example to refer to when I describe how this project fits together.

The first step in creating an application using the Aurelia CLI is to run the new command to generate the application project structure and configure the build pipeline. Start by running the following command at the terminal/command prompt:

au new

After running this command, you’ll be asked to enter the name of your project, as shown in Figure 2.

Figure 2 The au-new command initiates a wizard that asks you a series of questions required for Aurelia to set up your build pipeline and project structure. The answers to these questions determine which utilities are used at each step of the pipeline.

At the prompt, enter the name of your project – my-books. A new folder with this name is created to host your Aurelia application as a subdirectory of your current directory.

After entering the project name, select the project setup option you want to use: press enter to select the Default ESNext option. This selects the standard build-pipeline configuration. If you want more control over the option for each step of the pipeline, you could select 3 (Custom).

Figure 3 The wizard advances you to the next setup options after you enter the project name.

As figure 4 shows, you now have the choice for whether you want to proceed with the project setup, given the displayed set of pipeline configuration options or abort and start again. This is useful if you realize at this step that you need to tweak any of the configuration settings before the project is created. If you select option 3 (abort) the wizard exits and you’ll need to start from the beginning.

Figure 4 You can see the list of selections you made, with default setup options configured as Babel for our transpiler, the Karma test runner, and Visual Studio Code for our editor.

Press enter to proceed with the default option and create the project.

The next step in the project-setup wizard (figure 5) determines whether project dependencies (such as RequireJS), should be installed as a part of the project creation process.

Figure 5 You can select Aurelia project dependencies in the wizard—for example, the NPM package required to build and run your project. At this step, you can decide whether it should go ahead and install the dependencies or if you’d like to do it later.

Installing the dependences should take a few minutes, depending on your internet connection speed. Press the enter key to go ahead with the default option.

After the project set up has completed, you should see the following output. If you run into any errors at this point, the best option is to start from scratch with a new project directory. It’s also a good idea to make sure that your versions of NPM and the Aurelia CLI are up-to-date to avoid any version mismatch related issues.

Updating nPM and Aurelia You can upgrade to the latest version of NPM using the command npm install npm@latest -g. You can get the latest version of the Aurelia CLI via NPM using the command npm update aurelia-cli -g.

When you complete the final step in the project setup wizard (figure 6) there are several other Aurelia CLI commands available now that you have the default project structure in place. You can see a full list of the Aurelia commands b running the au help command.

Figure 6 After completing the final step of the wizard, you’re shown some of the other commands that the Aurelia CLI provides such as au build which you may want to run now that you have the default project structure in place.

Your new Aurelia application includes the project structure and dependencies. To verify that everything has been set up correctly, let’s run the default project to see our obligatory hello world page in the browser.

In addition to generating the project structure, Aurelia CLI commands can be used to execute the build-pipeline steps necessary to transpile and package your code, and then get your project running on a simple HTTP server.

Definition Transpilation in the context of Aurelia is the process of taking our source files (ESNext or Typescript) and translating them to the ES5 format supported by today’s browsers. This is one of the steps in the Aurelia Build Pipeline, and is implemented using a Gulp task run by the Aurelia CLI when you execute the au run command.

To launch the my-books application, change directory to the my-books subdirectory and run the au run command at your terminal / command prompt:

cd my-books
au run

After executing the au run command, the my-books application should be hosted in a simple HTTP server on port 9000. Open a browser and navigate to http://localhost:9000 to view the default Hello World page. Figure 7 demonstrates the page that you should see in the browser.

Note For best results, use the current version of Google Chrome, Mozilla Firefox, Microsoft Edge, or Apple Safari. Older browsers such as IE9 are also supported by require polyfills. You can find more about running Aurelia in older browsers on the Aurelia Hub website

Figure  7 Default page shown when setting up a project via the au-new command. This is useful as a smoke-test to ensure that everything has been shown correctly. The default application consists of an app.html View and app.js ViewModel. One-way binding is used to render a message from the ViewModel to the View.

TroubleshootingIf you experience this error when using the au run command—SyntaxError: Block-scoped declarations (let, const, function, class) not yet supported outside strict mode—there’s a chance that you’re running an unsupported version of Node.js. At the time of writing, this error can be resolved by upgrading to Node.js LTS. It’s also worthwhile checking the Aurelia documentation at the following locations for details on the current pre-requisites:

Even though you’ll remove this default page as you continue creating your virtual bookshelf, this page’s useful as a smoke test to ensure that everything has been configured correctly.

Note The front-end build-pipeline has many moving parts and it can be difficult to keep track of them all. The project creation wizard has given us an effective shortcut, allowing us to setup all the required build-pipeline plumbing in minutes rather than hours. Additionally, because we’re now using a pipeline configured by the Aurelia core team, we can lean on their experience. You can read through the source code of some of the gulp build tasks to familiarize yourself with the latest techniques and practices.

And that’s where we’re going to stop for now. Hopefully you found this intro into getting started with Aurelia useful!

If you are hungry for more, check out the whole book on liveBook here and see this Slideshare presentation.