Aurelia 2 is a complete rewrite of Aurelia that shares many of the same loved and familiar features of Aurelia 1. Understandably, in the spirit of progress, not everything is the same. In this section, we are going to guide you through what has changed and how you can migrate over your Aurelia 1 applications to Aurelia 2.

COMPAT PACKAGE

An quickest way to get an application in v1 up an running in v2 is to include the compat package. It can be done via 2 steps:

1. installing the compat package via

npm install @aurelia/compat-v1

1. include the compat package into your app:

import { compatRegistration } from '@aurelia/compat-v1';

...
Aurelia
  .register(compatRegistration, ...)
  .app(...)
  .start()

BREAKING CHANGES

Event

In v2, preventDefault is no longer called by default. This breaking change could show up in unexpected places:

• click events: in v1, clicking on a button inside a form will not submit the form, while it will in v2, as the click event default behavior is no longer prevented

• drag events: in v1, implementing drag/drop will have preventDefault called automatically, but in v2, they will need to be explicitly called by the application

Sometimes, if it's desirable to call preventDefault in an event binding, use prevent modifier, like the following example:

<button click.trigger:prevent="doWork()">Submit manually</button>

<div dragstart.trigger="prepareDragdrop()" drop.trigger:prevent="onDrop()">

Read more about modifiers in event modifier doc here

Scope selection

In v2, when trying to bind with a non-existent property, the closest boundary scope will be selected, instead of the immediate scope of the binding (v1 behavior).

Internal binding property observeProperty has been renamed to observe

In v1, if you happen to use .observeProperty method from bindings in your application/library, then change it to observe instead. The parameters of the signature remain the same.

Internal binding property sourceExpression has been renamed to ast

In v1, if you happen to use .sourceExpression property from bindings in your application/library, then change it to ast instead. The type of the property remains the same.

Enhance API changes:

In v1, enhance method on an Aurelia instance has the signature:

class Aurelia {
  ...

  enhance(elementOrConfig: Element | IEnhancementConfig): View;
}

In v2, enhance method on an Aurelia instance has the signature:

interface IAurelia {
  ...

  enhance(enhancementConfig: IEnhancementConfig): IEnhancedView;
}

Parent container and resources can be specified through this config.

View model ref binding (view-model.ref="...")

In v2, in order to get a reference to the underlying component view model, use component.ref instead of view-model.ref This is to make terminologies consistent as we are moving towards component oriented terms.

If attribute (if.bind="...")

• The primary property of If has been renamed from condition to value. If you are using if.bind, you are not affected. If you are using the multi prop binding syntax, the template looks like this:

<div if="condition.bind: yes">

Change it to:

<div if="value.bind: yes">

Binding Engine

• BindingEngine has been removed in v2, but can still be imported from @aurelia/compat-v1 package for ease of migration. The collectionObserver method on the compat package of BindingEngine is not the same with v1, per the follow comparison: v2

  Copy

  collectionObserver(collection): { subscribe: (callback: (collection, indexMap)) => { dispose(): void } }

  v1

  Copy

  collectionObserver(collection): { subscribe: (callback: (collection, splices)) => { dispose(): void } }

Binding commands

• .delegate command has been removed, use .trigger instead. With shadow DOM, even though .delegate works, it doesn't feel as natural as .trigger, and the performance benefits .delegate command used to give when browsers were slow adding many event listeners is no longer as big.

• .call command has been removed, use lambda functions instead to create function that preserves the this context. Refer to lambda expression

Compose

• <compose> has been renamed to <au-compose>. The bindable properties of this component have also been changed:

  • viewModel -> component

  • view -> template

  • model remains the same

• Examples migration fix:

  Copy

  v1:
  <compose view.bind="...">
  <compose view-model.bind="...">
  
  v2:
  <au-compose template.bind="...">
  <au-compose component.bind="...">

• In Aurelia 2, all bindings are passed through to the underlying custom element composition, so component.ref (view-model.ref in v1) no longer means getting a reference to the composer, but the composed view model instead.

Read more about dynamic composition in v2 in this dynamic composition doc and dynamic ui composition doc.

General changes

• Templates no longer need to have <template> tags as the start and ending tags. Templates can be pure HTML with enhanced Aurelia markup but <template> doesn't need to be explicitly defined.

• PLATFORM.moduleName is gone. This was to address a limitation in Aurelia 1. Aurelia 2 now works well with all bundlers and does not require the addition of this code to use code splitting or tell the bundler where template code is.

• Better intellisense support for TypeScript applications. Using the new injection interfaces, you can now inject strongly typed Aurelia packages such as Fetch Client, Router or Internationalization. These packages are prefixed with an "I" such as IHttpClient, IRouter and so on.

Plugins:

Web-Components plugin

• Remove automatic au- prefix

• Remove auto-conversion of Aurelia element -> WC element. Applications need to explicitly define this. This should make mix-matching & controlling things easier.

Bootstrapping

The hosting page

The first entry point of an Aurelia application is the main HTML page-loading and hosting.

The main module

All the initial settings for starting and working with an Aurelia project are done in this file.

Components

The Root Component

The root of any Aurelia application is a single component, which contains everything within the application, actually, the root component.

The Component Life-cycle

Every component instance has a life-cycle that you can tap into. This makes it easy for you to perform various actions at particular times

Which life-cycle hooks are most used?

Such cases can be summarized.

Dependency injection

A dependency injection container is a tool that can simplify the process of decomposing such a system. Oftentimes, when developers go through the work of destructuring a system, they introduce a new complexity of "re-assembling" the smaller parts again at runtime. This is what a dependency injection container can do for you, using simple declarative hints.

Registering services

Resolving services

Registration strategies

Resolvers

Logging

Writing debug output while developing is great. This is how you can do this with Aurelia.

Router

Routing Life-cycle

Binding

String Interpolation

Binding HTML and SVG Attributes

References

| Name | Aurelia 1 | Aurelia 2 | Description | | ---- | - | - | | ref | ✓ | ✓ | | | view-model.ref | ✓ | ✓ | deprecated in v2 | | component.ref | ✗ | ✓ | Not in v1 |

Passing Function References

DOM Events

{% hint style="info" } In v2, if an expression return a function, that function will be use as the handler for the event. V1 only evaluates the expression. {% endhint }

Contextual Properties

General

Event

Repeater

@computedFrom

@computedFrom tells the binding system which expressions to observe. When those expressions change, the binding system will re-evaluate the property (execute the getter).

Observation in template

@attributePattern

This feature is totally new for Aurelia 2.

Aurelia 1 was released in 2015. In the years that have passed, an ecosystem of user-created libraries and plugins has been created. If you are a plugin author of a v1 plugin or looking to port over a plugin to v2, this is the section you are looking for.

Before proceeding, you should read through the parent section to understand the differences between v1 and v2.

In Aurelia 2, the plugin method you called in v1 is no more. Plugins in Aurelia 2 are no different to components and other resources. You pass them to the register method inside your bootstrap code to load them.

There are numerous ways you can create Aurelia 2 plugins or port over v1 plugins. However, the easiest reference point is to look at how other plugins have been ported over to Aurelia 2.

Please keep in mind these are third-party plugins, and the Aurelia team claims no responsibility for the quality and safety of the code. Use them as a reference point for your own Aurelia 2 plugins, but use precaution.

• Cardigan UI

• Aurelia 2 Table

• Aurelia 2 Auth

• Aurelia 2 Google Maps