JavaScript Framework - Aurelia

Now that we have our development environment all set up and ready to go it is time to create the root of the project which is the JavaScript framework. The framework is the bones of our application.

Because we want portability and the ability to run our app on a mobile device we need a framework that supports a Single Page Application or SPA. This is important in a mobile app, because the app is running in a headless browser and there is no way to navigate from page to page like a traditional web application. Our desktop application will also run the app in a headless browser. This is the core concept that gives us maximum portability.

Why Aurelia

My decision to use Aurelia as my core framework was not made easily. There are lots of other frameworks out there (and I really don't want to debate which is better in this blog) and I have used most of them in my career.

Aurelia provided me with most of my wish list, based on my concept, for this project. It has a relatively easy learning curve and it's design is very unobtrusive and flexible allowing me to manipulate it in certain areas to benefit this project. You can read about it's benefits and features here.

The CLI

Aurelia has a module called CLI or Command Line Interface. It is used to set up a basic Aurelia project and has several command lines options or choices for configuring the project. It is also used to start the development run time environment as well as a few other useful features.

NOTE: The remainder of this blog is a step by step tutorial to actually build The Smoke House Project ... All instructions are based on a new empty code repository and  it's associated working project directory. Do not perform these steps in a cloned copy of the existing Smoke House Project!

Let's create the bare bones or skeleton project in our new working directory now.

1. Open a command prompt in your project directory.
2. Run command 'nvm use 10.14.0'
3. Run command 'npm install aurelia-cli -g'

This makes sure we are using the correct version of node for our project. Then we install the Aurelia CLI using NPM with a global flag. This allows us to run Aurelia CLI to create our project and then start it in the future.

We are using the Node Package Manager (NPM) to install node packages and maintain the package.json file for our project. You can read more about it here.

NOTE: Because we used the "-g" (global) flag the NPM installed the Aurelia CLI into the root or host node folder and NOT your project folder. NVM manages this folder and installs the required version of node that you requested with the 'nvm use ...' command. This keeps all of the Node specifics out of your project but makes them available to your project folder ... hope that makes sense! So if you check your project folder now it will still be empty but you should be able to run the command 'au' and the Aurelia CLI welcome message should appear.

Now that we have the CLI installed globally (for this version of node) we can create our new project.

1. Open a command prompt in the project folder.
2. Run command 'nvm use 10.14.0'
3. Run command 'au new applewood --here'

This will start a wizard which will ask you to make project choices. "applewood" is the name of our project and the "--here" flag tells the wizard to build the project in the current directory. This is important as I will be customizing some scripts based on this choice!

Answer the questions with the following answers to get the same project structure as I am using:

Choose option 2 because Electron uses RequireJS so we want the same module loader in our project.

NOTE: You may see some different questions or they may appear in different orders based on the version of Aurelia's CLI that is installed. The questions presented here should be answered with my answers, if you see others use your best judgement!

If this question is not asked, Aurelia is automatically using the "Custom" option so just move on.

We will be using a Javascipt platform. I may build a .NET platform in the future.

We will be using Javascript ESNEXT. I may build a TypeScript project in the future.

Choose the default. It affords us maximum flexibility.

I am using LESS in this project. It is a personal choice.

I am using Karma in this project. It is a personal choice.

I am not doing any integration testing. It is a personal choice.

I am using Visual Studio Code. It is a personal choice.

The wizard is ready to create our new project. You may see a warning notice. Our directory should be empty but there is a hidden folder containing the GIT information. Go ahead and chose 1 to create the project skeleton.

Now go ahead and install the project dependencies. The wizard is using NPM in the background to download and install all the required dependencies. You can see a list of them in the package.json file after the wizard is complete. Be patient - Depending on your internet speed this process may take a bit of time!

Our skeleton project is now complete and ready to use. Please note that if you have deviated from my choices you may have to make additional modifications to your code to make this project successful!

Your project directory should now look like the following:

Take note of the "node_modules" folder. This is where all the project specific node packages are installed by NPM.

NOTE: Certain folders like the "node_modules" contain content that intentionally is not included in the source code repository. This means that when you clone a project from the repository into your working folder you must populate the folders like "node_modules" before you can use the project. This is done by opening a command prompt in the working folder and running a command to fetch and populate the folder with the required packages. For our project do the following:

1. Open command prompt in root of the project folder
2. Run command 'nvm use 10.14.0'
3. Run command 'npm install'

You must do this every time you clone a project form the repository to a working directory!