Aurelia Project structure explained

AureliaJS

In this post, I am trying to explain the project structure created using Aurelia CLI.

Let’s first create a new Aurelia app using Aurelia CLI command

au new myapp

If we select all the default options, we will be getting the below project configuration.

Aurelia Default Project Configuration

Project structure will look like in the screenshot given below.

Aurelia Default project structure

First, lets see package.json. You will see package.json in all the JavaScript application. It is in this file that we can find all the node modules used in the project with version. Whenever we install a node module(node package) using

npm install <package_name> --save

it will be added under dependencies inside package.json and also will be downloaded to node_modules folder.

(use save-dev for saving under dev dependencies)

Also, in package.json, you can notice jest property. All the configuration for running tests with jest are added here. You can add/update the jest configuration as per your project requirement.

If you feel like lot of configurations are added inside package.json, you can always move jest configurations to a separate file .jestrc

After that, there is scripts section. You can add any commands which can be run using node under scripts section. Think of it like a shorthand.

You can run any of the scripts using

npm run <script_name>

You will see that, currently there are two scripts

What does nps means. Where are all the steps required to start the application written?

nps is a node package. It helps in adding all the npm scripts in a separate JavaScript file.

All the nps configuration is added under package-scripts.js

If you go through package-scripts.js you can see that, it is using webpack to start a server and also for building.

Lets see Webpack to understand it better.

Webpack is a module bundler. It is a build tool, same like Gradle / Maven for Java or MSBuild for .Net. It can be used to minify files, concat file, process css, JS etc.

Webpack needs loader for each transformation. For eg. in this Aurelia application, we will be using latest ES6 & ES7 features. But, it has to converted to ES5 before putting to the browser. For this purpose, Webpack uses Babel loader. Same way, for doing CSS processing, Webpack uses css-loader.

Webpack configurations are added in webpack.config.js

Under entry section, two keys are added. app and vendor.

Aurelia app webpack entry

Here the application code and library codes are separated. In the final generated output, there will be two files, app.js and vendor.js. Whenver you introduce a third party library, you can add to vendor section.

Aurelia-bootstrapper package is responsible for initializing Aurelia application. Bluebird is a promise library. This is added to support Promise for old browsers also. If your application is not supporting old browsers, you can remove this.

output section tells where the output files will be generated and with what name etc.

Under module -> rules section, all the loaders are mentioned. You can see that, there are a lot of loaders used for processing multiple type of files. You can add/update based on your project requirement.

Webpack plugins are extra functionalities you can add. That will come under plugins section.

Next file we will see is jsconfig.json.

Get Jinto Jose’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

By adding jsconfig.json, we are telling to the editor that the project is a JavaScript project. If we had selected Typescript while creating Aurelia app using Aurelia CLI, there will be tsconfig.json instead of jsconfig.json.

In jsconfig.json, target is given as es2015. It says to convert the ES7 code to es2015 format. Also, Decorators are enabled. Aurelia uses decorators heavily.

Project uses Babel transpiler tool to convert latest JavaScript to current JS version. By default, babel configuration is added in .babelrc file. Since, Aurelia wants to give different options for different environments (development, production etc..), .babelrc.js is added, which is imported in .babelrc file.

Inside .babelrc.js file, we can see two sections, plugins and presets.

transform-decorators-legacy plugin is added to enable the use of decorators.

Normally, any properties you want on an instance of an object created with a class need to be defined inside of the special constructor method.

transform-class-properties plugin is added so that, properties can be added directly under class rather than under constructor. We can add class methods also as properties for binding the context correctly. This is especially helpful in React apps. You can get more clarity here.

Under presets in .babelrc.js, targeted browsers are mentioned.

.editorconfig is Visual Studio Code editor configurations. This is useful so that, everyone in your project will be following the same style of coding. If you want a different editor, you can select that, while creating Aurelia app using Aurelia ClI au new command.

.eslintrc.json is adding the lint check for your JavaScript code. It is currenly extending from aurelia-tools. Any rules can be added/modified by adding it on .eslintrc.json.

Now, we will see the index.ejs file. Since we are creating a Single Page Application, there will be only one html file rendered. The extension is EJS instead of html because webpack needs to inject the output files dynamically to this template and generate the final html. EJS is a JavaScript templating engine.

Let’s run the application using the following command

au run --watch

This gives the following index.html.

So, this is the final format of the HTML file created out of the index.ejs file.

Lets focus now on the aurelia_project folder. It has 3 folders. environments, generators and tasks. Lets see one by one.

aurelia_projects > environments is used to specify flags/values specific to a particular environment. There are multiple environments added like dev, prod, stage. You can add more environments also. This is useful if you want different behaviour for different environments. For eg. you want logging on dev environment but not on production environment. Those flags we can put in environment files.

Under aurelia_projects > generators folder, different generators are added. Aurelia has multiple features like components, elements, attributes, binding behaviour, task, value converter etc. All these can be created easily using Aurelia CLI command au generate.

For example, to create a custom attribute, you can use the following command.

au generate attribute

This will ask few questions. Questions and answer handling logic is added in aurelia_projects > generators > attribute.js.

A new file switch.js is created under src/resources/attributes.

Under aurelia_project > tasks folder, you will find several gulp tasks. Gulp is again another build tool which is used by Aurelia CLI. There are multiple au commands like au run, au watch etc. When you execute au run, aurelia_project/tasks/run.js is being executed. We can add new gulp tasks and run it using Aurelia CLI if required.

Finally, lets go through the src folder, which contains all our Application logic.

main.js is the starting point of Aurelia application. How Aurelia knows
which file to use to bootstrap the application?

If you see index.ejs file, you can see that body has an attribute, aurelia-app=”main”, which says that, initialize the application with main.js in src folder.

In main.js, we are first doing all the configurations. All standard configurations are being used. Any plugins you want to add to the application can be added here.

At the end of the file, we can see the following line.

aurelia.start().then(() => aurelia.setRoot(PLATFORM.moduleName('app')));

It tells to Aurelia that, app is the root component. So, it will load, App component (which is app.js and its template app.html).

From here, you can start adding all your application logic by adding multiple components, features, attributes etc.

Happy coding. :-)

#Aurelia #AureliaCLI #TWBloggersClub #FrontEndConsultant