This tutorial is a little outdated however I made an updated video on how to use Aurelia CLI. Check it out here!

Aurelia is the latest JavaScript single application framework. Recently the Aurelia team release a tool called Aurelia-CLI. This is a command line tool that will help with bundling and scaffolding. We'll be going over some basic commands today.

If you want to learn more about the framework itself check out my Aurelia getting started guide and my blog example. Both go over some basic concepts on what Aurelia is and how to use it. Of course the official Aurelia getting started guide works as well.

Alpha

Before we begin, as of this writing, the CLI is at version 0.2.1 in an alpha state. You may run into bugs and issues. If you do run into issues you can report them on their official Github page. I'm sure as time goes on things will get more stable.

Installation

Since this is a command line tool you'll need to use the command line (duh). I've tested the CLI on Ubuntu and on my Mac so it should work although YMMV.

$ npm install aurelia-cli -g

After it's done installing you can double check that it's working by running this command

$ aurelia --help

This should display some helpful commands.

 Usage: aurelia [options] [command]


  Commands:

    bundle|b [options]         Create a new bundle based on the configuration in Aureliafile.js
    generate [options] <type>  scaffold elements for your project
    init [options]             Initialize a new Aurelia Project and creates an Aureliafile
    new [type]                 undefined

  Options:

    -h, --help  output usage information

Creating A New Project

Let us begin by creating a basic navigation project. In previous blog posts we had to download a zip file manually to get the navigation skeleton. Now we can use the CLI.

$ mkdir project
$ cd project
$ aurelia new project

The first thing we do is create a new folder for our project. For some reason the CLI doesn't automatically create it. Then we change directory into it. Next we simply run the new project command.

At this point we'll get an option. If you get any warnings about an Aureliafile not found you can ignore it for now

? Template?
❯ navigation
  plugin

This gives us the option to create a new project using the navigation skeleton or we can create a plugin. For now let's just create a new navigation. We can simply press enter.

If all is well it will start running the npm and jspm install. After it's done installing the navigation template should be ready to go.

$ gulp watch

This should fire up gulp. If you check out http://localhost:9000 the skeleton app should open.

Bundling

I won't get into this too much since the official Aurelia blog had a fairly good writeup on this, however let's say we want to bundle our app up instead of having a 200+ individual requests for every page load. One good reason to do this is if you were going to deploy this to production.

First we'll edit the config.js file in the root of our project and turn off buildCSS. It should look something like this.

System.config({
  "transpiler": "babel",
  "babelOptions": {
    "optional": [
      "es7.decorators",
      "es7.classProperties",
      "runtime"
    ]
  },
  "paths": {
    "*": "dist/*.js",
    "github:*": "jspm_packages/github/*.js",
    "npm:*": "jspm_packages/npm/*.js"

  },
     "buildCSS": false
});

Now we can tell Aurelia what to bundle. To do that we'll need to create an aureliafile.js file in the root of our project folder. First we'll need to make sure we have a local version of the aurelia-cli installed. Note: This is not the aurelia-cli with -g command, we are not installing it globally

$ npm install aurelia-cli --save-dev

Below is our aureliafile.js file.

// aureliafile.js
var aurelia = require('aurelia-cli');

  aurelia.command('bundle', {
    js: {
      "dist/app-bundle": {
        modules: [
          '*',
          'aurelia-bootstrapper',
          'aurelia-http-client',
          'aurelia-router',
          'aurelia-animator-css',
          'github:aurelia/templating-binding@0.12.0',
          'github:aurelia/templating-resources@0.12.1',
          'github:aurelia/templating-router@0.13.0',
          'github:aurelia/loader-default@0.8.0',
          'github:aurelia/history-browser@0.5.0'
        ],
        options: {
          inject: true,
          minify: true
        }
      }
    },
    template: {
      "dist/app-bundle": {
        pattern: 'dist/*.html',
        options: {
          inject: true
        }
      }
    }
  });

The modules section will take all our modules and minify and bundle them. It will then inject them into the config.js file so the bundle will be automatically loaded when the application requests any of the modules included in the bundle.

The template section will create a new file in the dist folder called app-bundle.html. This bundles all our templates in a way that the aurelia-loader understands. The inject command will create a link at the end of our body in our index.html file.

To create the bundle run this command.

$ aurelia bundle

FYI you may need to run aurelia bundle --force if you already have a bundle in the dist folder

Hooray! If all is well you can check out the dist folder and you should see the bundle and minified files. If you run gulp watch again you'll notice a lot fewer requests.

Next Up

There is a lot more you can do with Aurelia-CLI, like plugins. We'll cover that in our next tutorial. Hope you found this helpful.

Question? Leave a comment below.

Image Credit Aurelia