Get the Newsletter

The New Aurelia-CLI Auto-tracing Bundler

Posted by Chunpeng Huo on October 8, 2018

Today, we're pleased to announce the Aurelia-CLI v1.0.0-beta.1 release! The official beta of our CLI now features a new built-in "auto-tracing" bundler, which greatly improves the capability, performance, and usability of the built-in bundler.

The CLI's setup for Webpack remains the same as before. This new bundler provides an alternative to Webpack by combining a new auto-tracing bundler with RequireJS or SystemJS.

The auto-tracing bundler replaces the amodro-trace based bundler. The implementation is totally new, but on the surface, we maintain maximum backward compatibility.

A couple of major improvements of the new bundler include:

  1. It removes the burden of maintaining dependencies in aurelia.json.
  2. It greatly improves compatibility with many NPM packages.
  3. It has extensive documentation.

Technically, the new bundler behaves very similar to our Webpack/aurelia-webpack-plugin setup. For example:

  1. It auto-traces JavaScript dependencies and supports NPM packages in CommonJS, AMD, UMD, and Native ES Module format.
  2. It auto-stubs core Node.js modules for running in browser, using the exact same stubs that Webpack and Browserify use.
  3. It auto-traces JS/HTML/CSS dependencies in Aurelia view templates. e.g. <require from="..."></require>.

The new bundler also provides features above and beyond Webpack:

  1. Wrapping "moduleName" with PLATFORM.moduleName("moduleName") is NOT required. The new bundler understands all Aurelia's conventions without the need for a helper.
  2. In ESNext apps (not TypeScript apps), au run --auto-install can be used to help you install NPM packages. You can keep writing code and the CLI will install missing NPM packages, bundle them, and refresh you browser automatically.

Upgrading to the New Bundler

To upgrade your existing RequireJS/SystemJS based app:

  1. Make sure you are running on Node.js v8.9.0+.
  2. Update aurelia-cli in your app's package.json and then run npm install or yarn.
  3. Most existing apps should work without any need to update the aurelia.json file. However, you could be caught with one breaking change: the way to reference a non-JS main file has changed. The non-JS main (or missing main) is used by some pure CSS NPM packages like font-awesome v4 and normalize.css. For example, if using font-awesome v4, you should remove the explicit dependency configuration {"name": "font-awesome", ... from aurelia.json. Have a look at our CLI Bundler Cookbook on how to use font-awesome v4 and normalize.css with the latest CLI bundler. It is only easier :)

Once your app works, you should start to clean up the aurelia.json vendor-bundle dependencies to take advantages of auto-tracing. The following are the minimum required dependencies:

  // note all other aurelia-* packages are gone
    "name": "aurelia-testing",
    "env": "dev"
  // for requirejs
  // or for systemjs
  // {
  //   "name": "text",
  //   "path": "../node_modules/systemjs-plugin-text",
  //   "main": "text"
  // }

For any 3rd party dependency, if it's not a shim (has "deps" or "exports" or both), not a custom local package (not in node_modules folder), and not a package alias, you can remove its config. Auto-tracing bundles NPM packages automatically without manual configuration in aurelia.json.

Enabling Caching

The new bundler also uses a cache to speed up consecutive builds. To turn it on, update the aurelia.json file. You can use "cache": true to turn it on for all environments:

  "options": {
    "minify": "stage & prod",
    "sourcemaps": "dev & stage",
    "rev": false,
    "cache": "dev & stage"

You will need the task file to enable the new command au clear-cache. To get it, use the latest CLI to create a new app, choosing the built-in bundler. Then, copy the following files from the new app to your existing app:

  aurelia_project/tasks/clear-cache.js (or .ts)

Only for ESNext apps (not TypeScript), do npm install --save-dev gulp-cache or yarn add -D gulp-cache, and copy the new aurelia_project/tasks/transpile.js file which further improves performance using gulp-cache to cache transpilation results.

Updates for Plugin Authors

For all Aurelia plugin authors, please update your installation guides to remove any dedicated CLI bundler instructions. The installation of any Aurelia plugin is now the same for Webpack and CLI bundler users: just run npm install your-plugin.

For more information, read the CLI Built-in Bundler chapter of the Aurelia guides. For any issue/bug, please ask a question on the Aurelia Discourse Forum or create an issue on the aurelia-cli GitHub repo , and we will help you out.

Happy Bundling!

Full CLI Changelog

Bug Fixes

  • fix exception on "au new" when running directly in root directory ( 8037eef )


  • bundler: auto tracing for requirejs/systemjs ( c4ce02c ), closes #831 #853 #842 #831
  • bundler: build.options.cache turn on tracing cache and transpile cache ( 15af83f )
  • bundler: fully support package.json browser field ( 5bb81d4 ), closes #579 #581
  • bundler: stub core Node.js modules just like browserify and webpack ( 19aafee )
  • bundler: support both 'json!f.json' and 'f.json' module id. ( ea005fe )
  • bundler: support Node.js direct json loading require("foo.json") ( 8fa8800 )
  • bundler: support npm package shipped in native es module ( 1669a6f ), closes #872
  • bundler: support onRequiringModule(moduleId) callback ( fd49eb1 )
  • bundler: support per package wrapShim setting on dependency config ( 3c796ac )
  • bundler: use package.json "module" (es module format) over "main" ( a3bc63a )


  • bundler: require minor user code change to support non-js main, like "main": "font-awesome.css"
  • bundler: remove support of undocumented "main": false, replace with generic "lazyMain": true. But this is handled transparently without breaking user's existing app.