Ember.js Octane vs Classic Cheat Sheet
This guide is a cheat sheet for using Ember.js Octane. It doesn't cover everything, but it should get you started! PRs welcome at the GitHub repository.
For in-depth information about the upgrade paths and differences introduced in Octane, see The Octane Upgrading Guide.
Generating Files
§Use an option to generate a component's JavaScript
§
In classic Ember, ember generate component
created three files: the template, a JavaScript file, and a test. In Octane, ember generate component
skips creating the JavaScript file. If you want the backing JavaScript class as well, include the -gc
option.
Classic
Octane
Component templates and JavaScript are in the same directory
§The location of component templates has changed in Octane. This is known as "template co-location."
Classic
Octane
Component Templates
§Angle brackets component invocation
§Angle brackets are a way to invoke components in a template file. There's no change in behavior. Learn more about features and using codemods to update your existing components.
Classic
Octane
Inline vs block components
§
Angle brackets components can be used as either inline or block components. There's no change in behavior. {{yield}}
looks and works the same. Learn more about features and using codemods to update your existing components.
Classic
Octane
Nesting components in your file structure
§You can nest components in your file structure, and use them in a template with angle brackets invocation. There's no change in behavior.
Classic
Octane
Using named argument
§
If a property was received from a parent component, refer to it with an @
. There's no change in behavior. (Visit the Ember Guides to learn more.)
Classic
Octane
Using own properties
§
If a property is defined in the JavaScript file for this component's template, use this
when you refer to it. There's no change in behavior. Learn more about features and using codemods to update your existing components.
Classic
Octane
Passing named arguments
§
When you pass an argument to a component, use an @
symbol on the left hand side. There's no change in behavior. Learn more about features and using codemods to update your existing components.
Classic
Octane
Passing arguments defined on "this" component
§
If a property is coming from a template's own JavaScript file, remember to put a this
before it and wrap it in curly braces. Learn more about features and using codemods to update your existing components.
Classic
Octane
All components are tagless
§
In Octane, components don't have a default wrapper anymore, so you don't need tagName
! Just put the tag right in the template.
Classic
Octane
Make your own elementId
§
Since components are tagless, there's no elementId
, but you can generate your own. This is especially helpful for creating accessible forms.
Classic
Octane
Component Properties
§Component JavaScript Syntax
§
An Octane component imports from the @glimmer
package namespace. It also uses native class syntax. Glimmer components have different API methods than classic components. If you aren't familiar with native classes, first check out the documentation on MDN. Then, learn more about Glimmer components from the Ember.js Guides and the API Reference.
Classic
Octane
Declaring a property
§Properties follow native JavaScript class syntax. No commas!
Classic
Octane
Data Down, Actions Up
§Octane components enforce "Data Down, Actions Up." When data is passed down to a component, the only way to change that data is to call an action that was passed in too. In another words, there is no two-way binding for component arguments.
Classic
Octane
Component Arguments
§
In Octane, arguments are set on the args
property, this.args
. They are not set on the class instance, this
. As a result, you can distinguish internal class values from external arguments. (Visit the Ember Guides to learn more about arguments.)
Classic
Octane
No more get and set on components
§
Octane components do not use this.get
or this.set
. Access and modify properties directly, the same as you would in a regular JavaScript class.
Classic
Octane
Use @tracked and getters instead of computed properties
§Label the properties that should be tracked. Getters will be updated automatically.
Classic
Octane
@computed decorator
§
In Octane, it is recommended to rewrite a computed property as tracked property. In case that isn't possible (maybe you need caching), the @computed
decorator is available.
Classic
Octane
Actions
§Use @action, {{on}}, and {{fn}} instead of actions
§
In the JavaScript class, use the @action
decorator to mark the function that you want to call from the template. In the template, use the {{on}}
modifier to decide when to call the function. If you need to pass an argument to the function, use {{fn}}
helper too. (Visit the Ember Guides to learn more.)
Classic
Octane
Setting the default value of an argument
§Because an argument is read-only, you cannot set its default value in the consuming class. Instead, you can create a getter to wrap the argument and provide the default value.
Classic
Octane
Mixins
§
You cannot use mixins on anything that uses native class syntax (e.g. components that import from @glimmer/component
). The migration strategy depends on your use case. If your app depends on an addon that uses mixins, it may be best to continue using classic components until the addon is Octane-ready.
Classic
Octane
See Do you need Ember Object? for alternatives to mixins, which include utility functions, services, delegates, and class decorators.
Component Lifecycle
§Use constructor instead of init
§
constructor
comes from native JavaScript class. You can use this hook to set up the component class, similarly to what you might have done in init
. (Visit the Ember Guides to learn more about constructor and super.)
Classic
Octane
Use willDestroy instead of willDestroyElement
§
willDestroy
is the only other lifecycle hook (besides constructor
) that Glimmer components have. You can use this hook to tear down the component class, similarly to what you might have done in willDestroyElement
. (Visit the Ember Guides to learn more about lifecycle of Glimmer components.)
Classic
Octane
Element Modifiers
§
If you install @ember/render-modifiers, you get {{did-insert}}
and {{did-update}}
modifiers. You may use them to replace a classic component's lifecycle hooks didInsertElement
, didRender
, and didUpdate
.
Classic
Have Ember apps at version 2.18 or higher? You can use these modifiers to start converting classic components to Glimmer ones.
Octane
Use {{did-insert}} instead of didInsertElement
§
If you used the didInsertElement
hook, consider making an action. You can call the action with the {{did-insert}}
modifier. Use the @action
decorator to bind the correct context (this
). (Visit the Ember Guides to learn more about lifecycle of Glimmer components.)
Classic
Octane