There are two types of changes that are included in Ember Octane

• Incompatible "Octane Mode" Changes. New Ember Octane applications will be running in Octane Mode, which means that they have a number of features enabled that are not enabled by default in existing applications (which are running in "Classic Mode"). These are changes in Ember that are relatively small, but also incompatible, and could cause breakage in some apps. These changes must be enabled manually in existing applications, so updating Ember versions will not break your app. Each feature can be enabled manually, one at a time, and enabling all of them will put your application fully into Octane Mode.
• Idiom Changes. Ember has always provided idiomatic ways of doing things, such as defining classes using EmberObject.extend() or accessing the DOM from lifecycle hooks like didInsertElement. Octane introduces new idioms and APIs for many of Ember's existing features, such as @tracked properties, Glimmer Components, and element modifiers. These features are improvements and refinements on the existing APIs, and they are meant to replace the existing idioms in time. However, Classic idioms and features will continue to work alongside Octane idioms for the forseeable future, allowing you to update at your own pace.

Concretely, upgrading an existing Ember application includes:

• Updating your Ember version to 3.15+. This update should be like any other Ember update, and will not affect the behavior of your Ember application in any way.
• Enabling the optional feature flags to opt-in to incompatible changes. Each feature flag can be enabled independently of the others, and these can be done in an incremental way.
• Gradually updating from Classic idioms to Octane idioms. This is the largest step in upgrading, but can occur at your pace since old features and new features will work together, side-by-side.

Workflow

The Octane upgrade process can seem daunting. We recommend tackling the Octane upgrade in a few different phases that you can plan for individually, so you can make incremental progress:

• Phase 1 - Ember Upgrade
  1. Update to Ember Octane (3.15+)
• Phase 2 - Enable Octane Mode
  1. Enable the optional feature flags to opt-in to incompatible changes
  2. Set the Ember edition to Octane to change defaults and behaviors
• Phase 3 - Run Codemods
  1. Run a number of community codemods, one at a time, to automate much of the conversion process
• Phase 4 - Gradual Conversion
  1. All new code is written using Octane idioms
  2. Gradually convert existing code to Octane idioms

Phase 1 can be accomplished relatively quickly, and doing both of these steps early on in the upgrade process will allow your team to begin writing and learning Octane features quickly. It also means that you can enforce that all new code is written using Octane idioms, which is a great way to get everyone up to speed with the newest features and best practices.

Phase 2 can progress at a comfortable pace for your team. You can require all code that is touched be converted, or tackle the conversion process all at once, but if you need to ship features or address critical bugs, nothing is preventing you from getting back to normal work during this phase. This is one of the best features of Ember at work - you can keep shipping as you continue upgrading!

Octane Mode Overview

The following table covers the differences in behavior between Octane Mode and Classic Mode, along with a quick CLI snippet for how to opt-in to the new behavior. For more details, on how to enable each feature, see the Enabling Octane Mode Features guide.

Octane Mode

Octane Idioms Overview

Octane also comes with a number of new features that change some of the idioms of Ember applications. You can use these new idioms alongside existing code. You can also use codemods to migrate existing code to the new idioms.