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.
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.
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:
- Select
1
for ECMAScript next generation language - Select
1
to create the project - 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:
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.
Note
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:
Note
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.
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 thetest
folder.
For example, the preceding command will run theapp.sec.js
file located in thetest/unit
folder:
au test --watch --env stage
The following is the output that has executed one test successfully:
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
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:
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! :)