Aurelia

Bundling an Aurelia Application

Introduction

Aurelia

Aurelia


Bundling an Aurelia Application

Posted by Aurelia on .
Featured

Bundling an Aurelia Application

Posted by Aurelia on .

Aurelia is a next generation framework that promotes good design patterns and practices. The next version of HTTP, HTTP/2, may very well obsolete the necessity of creating bundles in the future, but we are not there just yet. Nobody likes to see a production application making 256 requests when loading. That's why Aurelia takes bundling very seriously. Read on to find out how to get your app bundled up for deploy using our new CLI.

Note: We've drastically improved our bundling technology. Please disregard this article and see the most up to date resources, found here.

Getting Started

Let's begin by creating some bundles. We will use our skeleton-navigation project as the basis of our work. First, we will run it as is and then we will bundle it to see the difference.

Note: We assume you have downloaded and set up the navigation skeleton, per these instructions.

Once the project is set up, run the following gulp task to view the application in the browser.

 gulp serve

Up until now, we have not done any bundling. Let's say we decided to put our app into production as is. If we open the browser's dev tools we can see how many requests are being made by the application:

No of requests made my the application

258! Yep, that's a scary picture for a production scenario. We want to minimize the number of requests. So, let's call Aurelia-CLI to the rescue.

Before we bundle our app, we need to change the config.js file a little bit to switch off building css. Add buildCSS: false in the config.js, so that the file looks 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
});

Note: We have discovered a possible bug in JSPM related to bundling CSS at the moment. We will investigate further and let you know as soon as we find a solution.

Installing Aurelia CLI

Bundling apps with the Aurelia CLI is a breeze. Let's begin by installing the CLI tool:

 npm install -g aurelia-cli

For bundling, we need to install the tool locally to our project too. To do so cd into the skeleton-navigation project's root and run:

 npm install aurelia-cli --save-dev

Bundling JavaScript

Now we are all set to create our first bundle. Before running our bundle command we will tell the cli what to bundle. Let's add an aureliafile.js in the root of our project and use the configuration bellow:

  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
        }
      }
    }
  });

Next, let's run the command below from the shell:

aurelia bundle  

Everything should go well and we now should have a file named app-bundle.js in the dist folder. As per the configuration in aureliafile, we have inject set to true. This injects the bundle into config.js. As a result, the bundle will be automatically loaded when the application requests any of the modules included in the bundle. We also have minify set to true to reduce the size of our bundle.

Let's refresh our browser, keeping the dev tool open and see what happens.

Note: Make sure you clear the browser cache to see the result.

No of requests after bundling

15 requests! That's a significant improvement over 256. But, we can make it even better. As we can see in the picture, we have some requests for templates like app.html, nav-bar.html etc. In skeleton-navigation we have only 5 templates. But, a non trivial application may have 100s or even more. So, we need a way to bundle them as well. Fortunately, Aurelia CLI does have an answer to that too!

Bundling Templates

Let's teach the cli which templates to bundle. We will add a template configuration section in aureliafile.js. It should now look like this:

  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
        }
      }
    }
  });

Let's run aurelia bundle again. This time a new file named app-bundle.html should be created in the dist folder. This bundle contains all our templates in a way that aurelia-loader understands. Since we have set inject to true, a link tag has been injected at the end of the body in our index.html.

Note: You may have to run aurelia bundle --force since we already have a JS bundle at this point in the dist folder. The cli will not overwrite a created bundle normally.

Now, let's reload the application and see the request count again:

No of requests after bundling templates

10 requests! That's better, isn't it?

That's how easy it is to create bundles with Aurelia CLI. Once the aureliafile.js is in place with proper configuration, all we need to do is run aurelia bundle.

Important Notes When Bundling Templates

  • Glob patterns execute relative to baseURL
  • You can use patterns like ['dist/**/*.html', '!dist/about/*.html'] as well.
  • Bundle files gets created relative to baseURL. So, according to the aurelifile config dist/app-bundle will be created as baseURL/dist/app-bundle.js

Important Notes When Bundling JS

  • Unlike template bundling patterns, it does not glob files. Rather, it globs system.js paths like */** or *.
  • Bundle config should include proper module names instead of file names.
  • Like templates in the bundle file, the JS bundle file also gets created relative to the baseURL.

More to Come...

Apart from bundling, the Aurelia CLI has some other really cool tricks up its sleave. It can make your development time more pleasing and interesting. The CLI team is working really hard to create a tool that everyone loves. Tell us what you want, what you like or even dislike on our gitter channel and please raise CLI related issues here.

Thanks to the CLI team and especially Core Team Member Shuhel Ahmed for putting together this post!

View Comments...