LogoLogo
HomeDiscourseBlogDiscord
  • Introduction
  • Introduction
    • Quick start
    • Aurelia for new developers
    • Hello world
      • Creating your first app
      • Your first component - part 1: the view model
      • Your first component - part 2: the view
      • Running our app
      • Next steps
  • Templates
    • Template Syntax
      • Attribute binding
      • Event binding
      • Text interpolation
      • Template promises
      • Template references
      • Template variables
      • Globals
    • Custom attributes
    • Value converters (pipes)
    • Binding behaviors
    • Form Inputs
    • CSS classes and styling
    • Conditional Rendering
    • List Rendering
    • Lambda Expressions
    • Local templates (inline templates)
    • SVG
  • Components
    • Component basics
    • Component lifecycles
    • Bindable properties
    • Styling components
    • Slotted content
    • Scope and context
    • CustomElement API
    • Template compilation
      • processContent
      • Extending templating syntax
      • Modifying template parsing with AttributePattern
      • Extending binding language
      • Using the template compiler
      • Attribute mapping
  • Getting to know Aurelia
    • Routing
      • @aurelia/router
        • Getting Started
        • Creating Routes
        • Routing Lifecycle
        • Viewports
        • Navigating
        • Route hooks
        • Router animation
        • Route Events
        • Router Tutorial
        • Router Recipes
      • @aurelia/router-lite
        • Getting started
        • Router configuration
        • Configuring routes
        • Viewports
        • Navigating
        • Lifecycle hooks
        • Router hooks
        • Router events
        • Navigation model
        • Transition plan
    • App configuration and startup
    • Enhance
    • Template controllers
    • Understanding synchronous binding
    • Dynamic composition
    • Portalling elements
    • Observation
      • Observing property changes with @observable
      • Effect observation
      • HTML observation
      • Using observerLocator
    • Watching data
    • Dependency injection (DI)
    • App Tasks
    • Task Queue
    • Event Aggregator
  • Developer Guides
    • Animation
    • Testing
      • Overview
      • Testing attributes
      • Testing components
      • Testing value converters
      • Working with the fluent API
      • Stubs, mocks & spies
    • Logging
    • Building plugins
    • Web Components
    • UI virtualization
    • Errors
      • 0001 to 0023
      • 0088 to 0723
      • 0901 to 0908
    • Bundlers
    • Recipes
      • Apollo GraphQL integration
      • Auth0 integration
      • Containerizing Aurelia apps with Docker
      • Cordova/Phonegap integration
      • CSS-in-JS with Emotion
      • DOM style injection
      • Firebase integration
      • Markdown integration
      • Multi root
      • Progress Web Apps (PWA's)
      • Securing an app
      • SignalR integration
      • Strongly-typed templates
      • TailwindCSS integration
      • WebSockets Integration
      • Web Workers Integration
    • Playground
      • Binding & Templating
      • Custom Attributes
        • Binding to Element Size
      • Integration
        • Microsoft FAST
        • Ionic
    • Migrating to Aurelia 2
      • For plugin authors
      • Side-by-side comparison
    • Cheat Sheet
  • Aurelia Packages
    • Validation
      • Validation Tutorial
      • Plugin Configuration
      • Defining & Customizing Rules
      • Architecture
      • Tagging Rules
      • Model Based Validation
      • Validation Controller
      • Validate Binding Behavior
      • Displaying Errors
      • I18n Internationalization
      • Migration Guide & Breaking Changes
    • i18n Internationalization
    • Fetch Client
      • Overview
      • Setup and Configuration
      • Response types
      • Working with forms
      • Intercepting responses & requests
      • Advanced
    • Event Aggregator
    • State
    • Store
      • Configuration and Setup
      • Middleware
    • Dialog
  • Tutorials
    • Building a ChatGPT inspired app
    • Building a realtime cryptocurrency price tracker
    • Building a todo application
    • Building a weather application
    • Building a widget-based dashboard
    • React inside Aurelia
    • Svelte inside Aurelia
    • Synthetic view
    • Vue inside Aurelia
  • Community Contribution
    • Joining the community
    • Code of conduct
    • Contributor guide
    • Building and testing aurelia
    • Writing documentation
    • Translating documentation
Powered by GitBook
On this page
  • COMPAT PACKAGE
  • BREAKING CHANGES
  • Event
  • Scope selection
  • Internal binding property observeProperty has been renamed to observe
  • Internal binding property sourceExpression has been renamed to ast
  • Enhance API changes:
  • View model ref binding (view-model.ref="...")
  • If attribute (if.bind="...")
  • Binding Engine
  • Binding commands
  • Compose
  • Replaceable & replaceable part
  • View decorators
  • General changes
  • Plugins:
  • Web-Components plugin

Was this helpful?

Export as PDF
  1. Developer Guides

Migrating to Aurelia 2

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

    Even though clicking default behavior is not prevented, form submission without an action will not reload the page as this default behavior is still prevented in v2, so you don't need to add :prevent to every button click, or form submit listener.

  • 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()">

Scope selection

In v2, when trying to bind with a non-existent property, the closest boundary scope (scope of the owning custom element) 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

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

    v1

    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.

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:

    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.

Replaceable & replaceable part

View decorators

For the ease of migration, the @noView and @inlineView decorators are made available from the @aurelia/compat-v1 package. FOllowing are some example usages.

  • Use the @inlineView decorator to define the template of a custom element.

    import { customElement } from 'aurelia';
    import { inlineView } from '@aurelia/compat-v1';
    
    @inlineView('foo-bar')
    @customElement('app-loader')
    export class AppLoader {
      //...
    }
  • Use the @noView decorator to define a custom element without a view.

    import { customElement } from 'aurelia';
    import { noView } from '@aurelia/compat-v1';
    
    @noView
    @customElement('loading-indicator')
    export class LoadingIndicator {
      // ...
    }

General changes

  • Custom attributes are no longer considered to have a binding to the primary bindable when their template usage is with an empty string, like the following examples:

    <div my-attr>
    <div my-attr="">

    Both of the above usages will be considered as "plain" usage, to avoid overriding the defaul value in the custom attribute component instance.

  • 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.

  • empty binding expressions are automatically inferred based on the target of the binding, like the following example:

    <input value.bind>
    <input value.bind="">

    means:

    <input value.bind="value">

    This is automatically applied to .bind/.one-time/.to-view/.from-view/.two-way/.attr binding commands.

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.

PreviousIonicNextFor plugin authors

Last updated 3 months ago

Was this helpful?

Read more about modifiers in

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

Read more about dynamic composition in v2 in this and .

If you are using replaceable/part/repaceable-part combo in your v1 applications, you'll need to replace them with <au-slot> elements and au-slot attributes. Refer to the for more information.

When migrating from v1, it is possible to encounter the @noView and @inlineView decorators. These decorators are no longer available from the core packages in v2. Instead, use the of the custom element decorator.

lambda expression
dynamic composition doc
dynamic ui composition doc
template property
event modifier doc here
au slot doc