Aurelia command-line tool

There are many ways to create an Aurelia project. For this book, we will use the official Aurelia command-line tool, which is supported by the Aurelia team. Although there are other options to configure your Aurelia application, such as Webpack and JSPM, we consider that the CLI is powerful and will help us save valuable time configuring our application skeleton and build tools.

In this section, we will explore in detail the CLI capabilities, and you will convince yourself that this is the best option for our adventure. After this section, you will be a master in using the Aurelia CLI.

Installation

Installing the CLI is not a big deal if you have installed Node.js in the previous section. We just need to open your favorite Terminal and execute the following command, and if you are using a Unix-based operating system, remember to add sudo before the command if you have permission issues:

npm install -g aurelia-cli

The preceding command will install the Aurelia CLI as a global executable command-line tool. This allows us to use the CLI with the au command as any other command of our operative system Terminal, for example, the dir command.

After the installation is complete, execute the following command:

au help

This should return the following output that displays the CLI help. As you can see, this command has two main options:

Now that we are sure that it is working as we expected, let's learn how to get the most out of it.

Creating a new application

This is one of the most important options. As its name says, it will create a new Aurelia application with a well-defined application folder structure and all the initial configuration files in just three steps.

Execute the following command and replace my-app with your application's name:

au new my-app

When the Aurelia CLI wizard is running, we will select the following options to create our application:

1. Select 1 for ECMAScript next generation language
2. Select 1 to create the project
3. Select 1 to install the dependencies

Once you answer the last question, the CLI will install all the dependencies and once everything is complete, you will see the following output in your Terminal window:

Running our Application

Next, we will look into the run option. This option allows us to run our application, and it provides us with an option to create a productive development environment by specifying the --watch option, which configures a watcher to detect changes in our source code and update our browser automatically. This cool feature is known as browser-sync or auto-refresh.

The run command also allows us to specify the environment where we want to execute our application; these are the default environments: dev, stage, and prod. By default, the CLI will run our application using the dev environment. Use the --env flag to change it.

What means exactly each environment? Well, in software development, commonly when you are writing your application you test your code on you local development environment (dev). Once you think its complete, you send it to a Quality Assurance area to test your application, this tests won't be performed on your machine so you need to export your application and deploy it on another server, it will be called the test environment. Finally, once the QA people gives his approval, you code will be deployed in the real world environment (prod). Of course, this is a very basic scope, you will find many more environments in other companies such UAT (User Acceptance Test).

For example, let's get into our application (cd command) and execute the following command:

cd my-app
au run --watch --env prod

The following is the output that has two URLs where we can see our application up and running:

Open the http://localhost:9000 URL in your favorite web browser, and you should see the following:

Pay attention to the last two lines in the console. Those tell you in which port is running your application, it could be different depending on your operating system and which port you have available.

Now, let's test how auto-refresh works, remember that this feature is enabled by adding the --watch option in the au run command.

Open the app.js file located in the src folder and change the 'Hello World!' string to 'Hola Mundo!':

export class App {
  constructor() {
    this.message = 'Hola Mundo!';
  }
}

Save it and go back to your browser; the CLI will detect the change you made in the app.js file and will refresh your browser automatically.

To be more productive, you can use two displays—the first with your application running in the browser and the second with your source code editor.

Testing our application

Of course, testing is an important skill all developers need to have. We have a complete chapter to talk about testing and discuss TDD, unit testing, and end-to-end testing.

The test command comes with the --watch and the --env flags. Use the watch option to tell the CLI to detect changes in the test folder and execute the tests again.

In order to run tests, the CLI uses Karma, which is a test runner technology that is configured to use Jasmine testing framework to write all our testing files that should be saved into the test folder.

For example, the preceding command will run the app.sec.js file located in the test/unit folder:

au test --watch --env stage

The following is the output that has executed one test successfully:

Building our application

Now is the time to deploy our application, but before we do this, we need to compress and minify our Aurelia code. Aurelia CLI provides us with the build option to generate these ready-to-deploy files that contain all our application code.

As you might want to build your application for different environments (dev, stage, or prod), this build option comes along with the --env flag. For example, execute the following command in your project:

au build --env prod

The following is a sample output of my-app project:

As the output shows, there are two main files generated: app-bundle.js, which contains our application logic and vendor-bundle.js, which contains third-party dependencies. These two files are generated into the scripts folder in our root application folder.

If you want to run your application and check whether everything is okay with the bundles you recently created, let's install the http-server module using npm. Run the following command in your Terminal:

npm install -g http-server

Now, create a dist folder in your application root folder and copy the index.html page and the scripts folder that contain our bundles.

For the last step, get into the dist folder in your Terminal and run the following command:

cd dist
http-server

Use the cd command to navigate across your folders in your Terminal.

This command will expose some four URLs where the web server is running; copy the first URL and open it on your web browser, and you should see your application up and running:

Generating custom resources

Aurelia, like many JavaScript frameworks, allows you to create reusable components that help you avoid writing duplicated code, reuse your component in multiple parts of your app, and also export them as plugins to reuse them in other projects.

Aurelia allows you to generate the reusable pieces of code utilizing the following templates:

• Components
• Custom elements
• Custom attributes
• Binding-behaviors
• Value-converters

These templates are all located in our project root folder in the aurelia_project/generators folder. For example, the following command generates a custom Aurelia element:

au generate element my-reusable-element

The source code will be generated in the src/resources/{type} folder depending on the type you selected.

Each type will be discussed in the following chapters, so don't feel bad if you don't understand the differences between them. Keep reading my friend! :)