Get the Newsletter

Aurelia Release for JSPM Beta

Posted by AureliaEffect on August 5, 2015

The spec for the standard JS module loader has recently been changing. The JSPM and SystemJS teams have been working hard to align with the new specs. And as of this release, Aurelia is now aligned with the new JSPM and SystemJS Beta.

Breaking Changes

The new module loader spec treats module ids differently. As a result, you may need to update some of your import statements in your code. This mostly affects relative ids. For example System.import('./x') is no longer baseURL-relative. It is baseURI-relative instead in order to enable matching URLs, per the new spec.

Due to some of these changes, you will need to update your path config. Here's the config block from the skeleton app:

      "defaultJSExtensions": true,
      "transpiler": "babel",
      "babelOptions": {
        "optional": [
      "paths": {
        "*": "dist/*",
        "github:*": "jspm_packages/github/*",
        "npm:*": "jspm_packages/npm/*"

There are two things to notice. First, make sure you have defaultJSExtensions:true. Second, look at the paths. Make sure you do not have file extensions there. If you have “*”:”dist/*.js” as was previously required, that is going to mess a lot of things up. Just remove the ".js" part.

Another place that was affected by this is internal plugin loading. Several complexities arise due to the nature of internal vs. external plugins. In order to properly handle both scenarios with the new loader, a new API has been added: feature. Have a look at the custom startup code below:

    export function configure(aurelia) {
      aurelia.start().then(a => a.setRoot());

External, 3rd party plugins use the plugin API, in the same way as before. But, if you have an internal plugin, you now use the feature API. A "feature" is simply a folder in your app with an index.js file that exports a configure function. It works the same as a plugin. It's just directly inside your app, rather than installed from an external source.

New Features

This release also contains some new features.

  • Surrogate Behaviors - For custom elements, you can now place attributes, bindings and custom attributes directly on the <template> element itself. In this case, the template element will serve as a surrogate or stand-in for the actual custom element itself. Any behaviors you add to the template will be "copied" to the actual custom HTML element at runtime. This makes it exceedingly simple to handle common accessibility scenarios for custom elements. Here's an example of a hypothetical progress bar element that uses this technique in its view:

        <template role="progress-bar" aria-valuenow.bind="progress" aria-valuemin="0" aria-valuemax="100">
          <div class="bar">
            <div class="progress" css="width:${progress}%"></div>
  * `@processContent(false|Function)` - Previously, you could add the `@skipContentProcessing` decorator to a custom element to tell the ViewCompiler not to process the content that a consumer placed inside your custom element tag. However, we have deprecated that in place of the new, more powerful `@processContent` decorator. This decorator lets you specify `false` to skip content processing, but also enables you to supply a custom function which will run during the view compilation and allow you to perform custom transformations on the element content. This function can then return true or false to indicate whether the compiler should then continue to process the transformed content.
  * `@inlineView(markup, dependencies?)` - Components can now use a new view strategy that allows inlining of the view markup directly in the JS file. I do not recommend this to be used in a general purpose way. It is designed for specific use cases such as server loaded views and very, small templates.
  * `Aurelia.prototype.enhance(...)` and `ViewEngine.prototype.enhance(...)` - We've added progressive enhancement to Aurelia. Most apps use `aurelia.setRoot()` in their startup code to create and display the root component. But you can now use `aurelia.enhance()` to "enhance" or "turn on" custom elements, attributes and bindings which exist in the DOM prior to starting Aurelia, such as those that may have been generated on the server. This new optional startup functionality is built on the core view engine feature which can be used at will to "enhance" any DOM content. This feature is new and will probably change over the next few weeks in preparation for Beta. So, if you choose to use it now, be prepared to deal with potential changes.
  * Improved Aurelia Framework API - We have moved some of the code that was in the bootstrapper into the Aurelia Framework itself so that we can provide a better documented and more standard API. We've also extended the startup hooks as part of enabling this and in preparation for some future plugins.
  * Updated Skeleton - We've updated our navigation skeleton to demonstrate the new `aurelia-fetch-client` plugin. It also shows how to use custom attributes and ref bindings.
  ## Fixes
  As always, we are squashing bugs with each release. There's no shortage of fixes today. Here are a few notable fixes though:
  * The `delegate` binding command didn't previously work from within the ShadowDOM. We have fixed this and aligned our code with the upcoming v1 ShadowDOM spec. Our code also takes into account previous versions of the spec and non-standard implementations which some browsers have.
  * There were a number of bugs in template parts, view slots and content reprojection. Those have now been addressed.
  * Various bugs in "re binding" `ref` and `call` bindings have been resolved.
  * Some fixes to the `if` and `repeat` behaviors.
  * Better web components compatibility.
  ## Updating
  First, you need to actually update to jspm beta. To do that use `npm install -g jspm@beta`. After you do that, you will need to re-install all of your packages, since the way that jspm transforms them as part of the installation process has changed.
  ## Road Map
  We are working towards Beta, which we are planning for 6-8 weeks out. This Beta will include a couple of additional features, mostly surrounding web components and dynamic HTML enhancement. The Beta will also feature our new documentation solution, which will enable us to provide a richer documentation experience as well as enable the community to document their own plugins and libraries better.
  We've been working hard on our benchmarking, which is now almost complete. As a result, the Beta will also include a number of performance optimizations and memory usage improvements. We'll continue this work after the Beta along with additional bug fixes.
  We're trying hard to stabilize the API. If you've been following our progress, you can see that there are still some changes, but they are usually pretty easy to fix. Nothing major. Today's breaking changes are related entirely to changes in web standards. As we move forward, we want to try to provide as stable of a platform as we can. But bear in mind that several specs such as the loader and web components specs are still in flux. As they change, we will have to adapt, and this may result in some breaking changes on our end. We'll do our best to communicate those and when possible to shield you from those side effects.