artemgurzhii Ember 3.28 → 4.12 LTS Migration
3 → 4 is the enforcement major: Octane is no longer optional, jQuery is removed, classic components and observers are gone for good. If you finished ember-3-octane-adoption, this jump is mostly mechanical — you're trading deprecations for build errors.
If you didn't finish Octane on 3.x, stop and finish it first. Bumping to 4.x with classic code remaining will make every screen break at once.
3.28 LTS → 4.4 LTS → 4.8 LTS → 4.12 LTS
↓
(continue with the ember-4-migrator agent)
Pre-flight checklist
Before bumping ember-source to 4.x, verify on 3.28:
- No
Ember.Component.extend(...)anywhere. - No
actions: { ... }hashes. - No
(mut ...)in templates. - No
this.$()(jQuery) in product code or tests. - No
Ember.Xglobal imports (use@ember/...modules). - No mixins.
- No observers (or all silenced via deprecation workflow with explicit ownership).
- All ember-data relationships have explicit
inverseandasyncflags. - All addons have a known-4-compatible version.
- Tests on modern API (no
moduleForXxx). - CI green; deprecation workflow file empty or owner-tagged.
If any of these are unchecked, fix them on 3.28 before bumping.
What 4.x removes
A non-exhaustive list. Each line is something that will fail at build or runtime in 4.x:
| Removal | What to do |
|---|---|
| jQuery integration (final removal, not just deprecation) | Replace any remaining this.$() with native DOM; remove @ember/optional-features flag. |
Ember.Component (classic) |
Convert to @glimmer/component. |
Ember.Object.extend({...}) |
Convert to native classes. |
Ember.Mixin |
Service-ify or extract. |
actions: {...} hash on classic components |
Already gone if Octane finished. |
Ember.computed (the global) |
Use import { computed } from '@ember/object' if absolutely needed; prefer getters with @tracked reads. |
Observers via Ember.observer |
Convert to actions, derived state, or modifiers. |
Ember.run (the global) |
Use import { run, scheduleOnce, ... } from '@ember/runloop'. |
Ember.RSVP (the global) |
Use import RSVP from 'rsvp' directly, or native promises. |
Ember.String.htmlSafe etc. |
Use htmlSafe from @ember/template. |
Ember.copy, Ember.merge, Ember.assign |
Native structuredClone / spread / Object.assign. |
Ember.testing |
Use import { isTesting } from '@embroider/macros' if needed. |
partial template helper |
Inline the template or extract to a component. |
with template helper |
Use let instead. |
Classic test API (moduleForComponent, etc.) |
Already gone if migrated. |
Hop-by-hop
3.28 → 4.4 LTS
This is the biggest hop. Most removals land here.
pnpm exec ember-cli-update --to 4.4
pnpm exec ember-cli-update --run-codemods
Expect:
- Build errors for any remaining classic patterns.
- Errors for any addon that hasn't published a 4-compat release.
- ember-data 4.x: the
Modeltyping changed. Manyattr/belongsTo/hasManydeclarations want explicit options.
Specific to ember-data 4:
import DS from 'ember-data'is gone. Useimport Model, { attr, belongsTo, hasMany } from '@ember-data/model';.import Adapter from 'ember-data/adapter';becomesimport Adapter from '@ember-data/adapter';.import Serializer from 'ember-data/serializer';becomesimport Serializer from '@ember-data/serializer';.relationship.asyncandrelationship.inversemust be explicit on everybelongsTo/hasMany(warnings in 3.x, errors in 4.x).
4.4 → 4.8 LTS
Quieter hop. Mostly cleanup of new deprecations introduced in 4.4 around:
ember-datarequest-internals refactor (preparation for the request manager).RouterServiceAPI tightening.- Implicit injection deprecation (
@servicemust name the property explicitly in some setups).
4.8 → 4.12 LTS
The final 4.x. Embroider becomes much easier to adopt here.
What lands here for many teams:
- Embroider opt-in. If you didn't adopt it before, 4.8-4.12 is the smoothest moment. Enables tree-shaking, ES modules, and prepares the way for
.gjs/.gtsin 5.x. - TypeScript becomes officially supported (without needing
ember-cli-typescriptas a separate addon). @ember/test-waitersbecomes the canonical way to register async work for the test runtime.
The Embroider question
Embroider is a different build pipeline. You can adopt it in 3.x, 4.x, or 5.x — it's orthogonal to the Ember version. But:
- Polaris (
<template>tag,.gjs/.gts) requires Embroider. - TypeScript with Glint works best on Embroider.
- Many newer addons assume Embroider compatibility.
Recommended sequence:
- Get to 4.4 on the classic build pipeline.
- Stabilize.
- Switch to
@embroider/core+@embroider/compat(the "compat" mode mimics classic resolver behavior). - Stabilize again.
- Move to 4.8 / 4.12.
- Then transition
compat→optimizedmode (real ES modules) at your own pace.
Adopting Embroider is a separate week of work. Don't bundle it with the version bump.
Addon survival list (3 → 4)
| Addon | Status at 4.x | Notes |
|---|---|---|
ember-cli-mirage |
Alive. | Bump to 2.x or 3.x; API is largely stable. |
ember-power-select |
Alive. | Bump major. |
ember-cli-page-object |
Alive. | Keep. |
ember-test-selectors |
Alive. | Keep. |
ember-modifier |
Alive. | API rewrite around 4.x — re-author custom modifiers if you have many. |
@ember/render-modifiers |
Alive. | Keep. |
ember-truth-helpers |
Alive. | Eventually replaced by @ember/truth-helpers. |
ember-svg-jar |
Alive. | Keep. |
ember-intl |
Alive. | Bump major; the API became more closely aligned with Intl. |
ember-simple-auth |
Alive (Mainmatter). | Bump major. |
ember-concurrency |
Alive. | Bump major; signature types added. |
liquid-fire |
Likely abandoned. | Replace with ember-animated or hand-rolled. |
| Any addon < 1k installs and last release > 3y | Replace or fork. | Migrating an abandoned addon is rarely worth it. |
Tests during the jump
- Run the suite at every hop. Smoke-test the top user flows manually after each.
- Component test infrastructure changes:
@ember/test-helpersmajor bump can shift behavior ofsettled()andwaitFor. Check the changelog. - Mirage 2 → 3: small API differences, mostly around model/serializer relationships. Run all integration tests.
Time estimates (rough, mid-size app, Octane finished)
| Hop | Calendar days |
|---|---|
| 3.28 → 4.4 | 5–10 |
| 4.4 → 4.8 | 1–3 |
| 4.8 → 4.12 | 2–5 (more if adopting Embroider/TS) |
| Total | ~2–3 weeks |
If Octane wasn't finished on 3.x, add 2–4 weeks for the cleanup that should have happened before the bump.
Common 3 → 4 surprises
| Surprise | Cause | Fix |
|---|---|---|
| Whole pages render blank after the bump | Classic component still in the layout — its wrapper element disappeared. | Convert the layout component to @glimmer/component and use ...attributes. |
belongsTo/hasMany returns null unexpectedly |
Missing inverse. |
Specify inverse: 'fieldName' on both sides. |
| Test suite hangs after bump | A custom waiter wasn't re-registered for the new @ember/test-helpers major. |
Re-register or migrate to @ember/test-waiters. |
Cannot read properties of undefined (reading 'extend') in an addon |
Addon imports Ember.Component. |
Bump the addon, or fork it. |
| Build is much slower after Embroider | @embroider/compat mode in dev, full reanalysis on every change. |
Tune staticAddonTrees: true once stable; consider optimized mode in CI. |
htmlSafe undefined |
Imported from Ember.String. |
import { htmlSafe } from '@ember/template'; |
Verification — at the 4.12 finish line
-
ember-sourceis~4.12.x. -
ember-datais on the matching 4.x major. - No
@ember/optional-featuresflag forjquery-integration(it's not a real flag anymore). - Build passes without warnings.
- All addons reported by
ember-cli-update --addonsare on 4-compatible versions. - Tests green; deprecation workflow file empty or near-empty.
- (Optional) Embroider in compat or optimized mode.
- (Optional) TypeScript via the official setup.
- CI is green.
When the box is checked, switch to the ember-4-to-5-migration skill.
See also
ember-3-octane-adoption— the prerequisite.ember-4-to-5-migration— the next hop.- Official: emberjs.com/releases/, Deprecations app, Embroider docs.