Discourse will soon be upgrading our version of the Ember Javascript framework from version 3 to version 5. The vast majority of the preparation work is done, and many sites are already running on Ember 5 (including Meta!). 
This upgrade is available behind a feature flag right now! This is the default for self-hosted Discourse installations starting 10th January. Initially, Ember 3 support will remain available via a flag, but will be removed within the first quarter of 2024.
On our managed discourse.org hosting, weâll be doing a staged rollout of the flag over the next couple of months:
 discourse.org hosting tier |
Upgrade Date |
|---|---|
| Basic | 2023-12-07  |
| Free | 2023-12-12 |
| Standard | 2024-01-15 |
| Business | 2024-01-22 |
| Enterprise | (case-by-case basis) |
What does this mean for me and my site?
If youâre running Discourse with no extra themes, plugins, or theme components⌠youâre all set! No need to lift a finger, or worry about this at all.
Equally, if you only use official themes/plugins, weâve got you covered! We will ensure that all our official themes, theme components, and plugins are primed and ready for the upgrade.
For those who are using third-party customisations, their developers should be making the necessary changes to those so you can continue to use them seamlessly throughout this transition.
However, if you have any custom themes, theme components, or plugins that you have created or commissioned for your sites, then this post is for you! Weâll run through how to identify and resolve any issues in advance of the upgrade.
Identifying issues
All ember-5-related upgrade issues can identified in advance of the upgrade by checking for uses of deprecated APIs. In recent versions of Discourse (starting Discourse 3.2.0.beta4-dev), these critical deprecations will trigger a warning banner for admins:
You can find more information about triggered deprecations in the browser developer console. Itâs generally good practice to resolve all deprecations you see. But for this Ember version upgrade, the key ones to resolve are:
-
discourse.modal-controllers(see this topic for more info) -
all Ember deprecations (i.e. those with non
-discourse.IDs)
When printing deprecations to the console, Discourse attempts to identify the relevant theme/plugin.
For developers and hosting providers, we have made a couple of tools available for identifying deprecations in bulk:
-
When running QUnit tests, a report is printed at the end with a list of all unresolved deprecations. In GitHub actions, a markdown version of this is added to the workflow summary page
-
For hosting providers, we have the discourse-deprecation-collector plugin which increments prometheus counters whenever deprecations are hit in production
Resolving deprecations
Generally, the console message will include a description of the problem and the steps required to resolve it. In some cases, theyâll link out to external resources like the Ember deprecations website or Discourse Meta.
If anything is unclear, please feel free to post below or in a dedicated dev topic and weâll do our best to help.
Testing on Ember 5
To test things on Ember 5 in a local development environment, you can start our ember-cli helper with the EMBER_VERSION environment variable. For example:
EMBER_VERSION=5 bin/ember-cli -u
To confirm things are working as expected, check the Ember version which Discourse prints to the browser console.
In production, you can achieve the same thing by adding EMBER_VERSION: 5 to the env: section of your app.yml file.
(new sidebar, removal of category badges⌠itâs quite often - having a custom theme is costly!).
.