Bundling Files with Aurelia-bundler

Running Aurelia.js in a Node.js/Express Environment - Part 2

In the previous article (⇒Running Aurelia.js in a Node.js/Express Environment - Part 1), we successfully got Aurelia.js running in a local environment.

This time, before creating a server with Express, I'd like to create files for production.

Bundling Files (Aurelia Bundler)

Reference ⇒ http://aurelia.io/docs.html#/aurelia/framework/1.0.0-beta.1.0.7/doc/article/bundling-your-app-for-deploy

Aurelia.js includes a file concatenation application called Aurelia-bundler, so let's try using it.

The reason for concatenating files is to 'reduce the number of requests'.

I won't explain why it's necessary to reduce the number of requests here, but simply put, browsers have a limit on how many requests they can handle at once. While it varies by browser, common browsers typically allow up to 2 concurrent connections.

When I opened an Aurelia.js page in Chrome and inspected it, I found there were 105 requests in my environment!

By using Aurelia-bundler, I was able to reduce this to just 15 requests.

Installing aurelia-bundler

Navigate to the directory where `aurelia-skeleton-navigation` is installed and install `aurelia-bundler`.

npm install aurelia-bundler --save-dev

How to Configure bundle.js (bundles.json)

The following file is set up as a Gulp task, so let's examine its contents.

var gulp = require('gulp');
var bundler = require('aurelia-bundler');
var bundles = require('../bundles.json');

var config = {
  force: true,
  baseURL: '.',
  configPath: './config.js',
  bundles: bundles.bundles
};

gulp.task('bundle', ['unbundle', 'build'], function() {
  return bundler.bundle(config);
});

gulp.task('unbundle', function() {
  return bundler.unbundle(config);
});

The file above contains two Gulp tasks: 'bundle' and 'unbundle'. Running `gulp bundle` will read the contents of the `config` object.

{
  "bundles": {
    "dist/app-build": {
      "includes": [
        "[*]",
        "*.html!text",
        "*.css!text"
      ],
      "options": {
        "inject": true,
        "minify": true
      }
    },
    "dist/aurelia": {
      "includes": [
        "aurelia-framework",
        "aurelia-bootstrapper",
        "aurelia-fetch-client",
        "aurelia-router",
        "aurelia-animator-css",
        "aurelia-templating-binding",
        "aurelia-templating-resources",
        "aurelia-templating-router",
        "aurelia-loader-default",
        "aurelia-history-browser",
        "aurelia-logging-console",
        "bootstrap",
        "bootstrap/css/bootstrap.css!text"
      ],
      "options": {
        "inject": true,
        "minify": true,
        "rev": true
      }
    }
  }
}

To put it simply, the packages and files listed in the `includes` section for `dist/app-build` and `dist/aurelia` will be compressed. `app-build.js` and `aurelia-revision.js` will be output into the `dist` folder. The default setting creates two files, but it's also possible to bundle everything into a single file.

It's clear that `dist/aurelia` is configured for packages.

Using `[*]` as shown limits the scope to the folder specified in `./config.js`. In the example above, the `dist` folder is specified in `config.js`.

Using a single asterisk `*` as shown makes the scope encompass everything.

excludes : [
   'app',
]

About Options

Setting this to `true` writes to `config.js`. It's typically `true`.

If `true`, a revision number will be added to the filename of the generated JavaScript file.

If `true`, existing files with the same name will be overwritten. Specify `false` if you do not want to overwrite them.

Specifies the location of `package.json`. The default setting is `'.'`. It is used by Aurelia-bundler to find `config.js`, `baseURL`, and `jspm_packages` during execution.

Configuring bundles.json and Running `gulp bundle`

In `aurelia-skeleton-navigation`, there's a part that uses an API to display Git users, but the default configuration is missing that plugin, so we'll add it.

"fetch",

{
  "bundles": {
    "dist/app-build": {
      "includes": [
        "[*]",
        "*.html!text",
        "*.css!text"
      ],
      "options": {
        "inject": true,
        "minify": true
      }
    },
    "dist/aurelia": {
      "includes": [
        "aurelia-framework",
        "aurelia-bootstrapper",
        "aurelia-fetch-client",
        "aurelia-router",
        "aurelia-animator-css",
        "aurelia-templating-binding",
        "aurelia-templating-resources",
        "aurelia-templating-router",
        "aurelia-loader-default",
        "aurelia-history-browser",
        "aurelia-logging-console",
        "fetch",
        "bootstrap",
        "bootstrap/css/bootstrap.css!text"
      ],
      "options": {
        "inject": true,
        "minify": true,
        "rev": true
      }
    }
  }
}

gulp bundle

If `app-build.js` and `aurelia-revisionnum.js` are newly created in the `dist` folder, then you've succeeded so far. Rewriting to `config.js` and other operations are also done automatically.

If you inspect `config.js`, you should find a new `bundle` entry.

※Caution: Be aware that `gulp watch` or `gulp build` will unbundle your files.

Even if unbundled, the bundle information remains in `config.js`, which will cause the page to fail to launch with an error indicating that the bundled files are missing.

If you need to unbundle for development or other tasks, run the following command:

gulp unbundle

Files Required for Screen Display

The page should be displayable with just the following files:

Execution of `index.html`, `system.js`, `config.js`, `aurelia-bootstrapper`

`app-build.js` ⇒ File output by `gulp bundle`

`aurelia-revision.js` ⇒ File output by `gulp bundle`

`system.js` is called in `index.html`, and `aurelia-bootstrapper` is executed based on the settings in `config.js`.

By default, `system.js` is located within `jspm_packages`, but it can also be relocated and used elsewhere.

This allows your application to run in a production environment without needing to create the `jspm_packages` folder.

Bonus: When Imported HTML Files are Included

Here's how to bundle when you're importing HTML files using Polymer or similar tools.

jspm install aurelia-html-import-template-loader

aurelia.use.plugin('aurelia-html-import-template-loader')

import 'bootstrap';

export function configure(aurelia) {
  aurelia.use
    .standardConfiguration()
    .developmentLogging();

  aurelia.use.plugin('aurelia-html-import-template-loader')

  aurelia.start().then(a => a.setRoot());
}

"dist/view-bundle": {
  htmlimports: true,
  includes: 'dist/*.html',
  options: {
    inject: {
      indexFile : 'index.html',
      destFile : 'dest_index.html',
    }
  }
}

var gulp = require('gulp');
var bundle = require('aurelia-bundler').bundle;

var config = {
  force: true,
  packagePath: '.',
  bundles: {
    "dist/app-build": {
      includes: [
        '[*]'
      ],
      options: {
        inject: true,
        minify: true
      }
    },
    "dist/aurelia": {
      includes: [
        'aurelia-bootstrapper',
        'aurelia-fetch-client',
        'aurelia-router',
        'aurelia-animator-css',
        'github:aurelia/templating-binding',
        'github:aurelia/templating-resources',
        'github:aurelia/templating-router',
        'github:aurelia/loader-default',
        'github:aurelia/history-browser',
        'github:aurelia/logging-console'
      ],
      options: {
        inject: true,
        minify: true
      }
    },
    "dist/view-bundle": {
      htmlimport: true,
      includes: 'dist/*.html',
      options: {
        inject: {
          indexFile : 'index.html',
          destFile : 'dest_index.html'
        }
      }
    }
  }
};

Now, the HTML files are bundled separately into a new file.