In the latest version of Discourse, using .hbs files in themes and plugins is deprecated. Support for this file format will be removed after the next ESR release.
Handlebars templates should be replaced with the more modern .gjs format, which provides a much better development experience, and will enable large performance improvements in future versions of Discourse.
For simple cases, share your code with https://ask.discourse.com/, and ask it to rewrite in the .gjs format.
For more complex cases, updates can be automated using using this codemod:
Itās most likely that we will drop support in 2026.8.0-latest. But itās possible it could be later, depending on real-world data and community feedback.
Thanks! Hopefully most people have already taken care of those, since they have been deprecated with an admin banner for almost a year. Just in case, I added this note:
I have no idea what a .gjs file is, nor time to learn about them and re-write multiple plugins. This is ridiculous.
What is the point of even having a plugin API if it is as fragile as the one in Discourse? Maintaining plugins for this forum software has been nothing but trouble.
If you donāt have the budget or bandwidth to manage customisations then I would urge you to simplify your setup.
Itās imho the (reasonable) price you pay for remaining on a cutting edge high velocity platform that keeps on innovating, improving performance, deploys frequent security patches and keeps up with evolving standards.
The Discourse team appears to put a lot of effort into ensuring there are deprecation warning messages well in advance of losing function.
Would you rather be stuck on an insecure platform with fewer features?
Think of the value you get from the well maintained core that you can download for free?
But with the help of ask.discourse.com, they reviewed my code and converted my .hbs and .js files to .gjs, so donāt hesitate to try this if the first method doesnāt work.
Iām not doing any further work on any of my Discourse plugins. It just isnāt worth it.
Given other people are using two of them, what is the process for deleting them without causing other people problems?
Iāve had enough of them being broken, usually for completely nonsense reasons, every few months and the amount of time and effort it takes just to keep my forum working.
I do not want to be āon the cutting edgeā. I just want a working, stable web forum.
āDonāt updateā isnāt an option either, since we need security updates. Itās ridiculous someone suggested that the last time I complained.
The Discourse team really need to care more about compatibility and not breaking existing forums and code. They do not seem to even think about it. They make breaking changes just to slightly tidy things up on their side. That is not how you manage a platform and API which is used by other people, and I want no further part in it.
If you do want to proceed down this path, Iād recommend adding a note to the README & Meta topic, marking it broken and then archiving the GitHub repository. That way, itās still available for others to fork (assuming the license is permissive enough).
We absolutely do care about compatibility & keeping things working. Thatās why we have these long deprecation periods with fully automated upgrade paths.
Weāre always trying to strike the balance between customizability and stability - Discourse themes and plugins are so powerful because we give them direct access to the underlying browser/framework APIs. That immense power comes with a certain amount of responsibility to keep up-to-date with underlying changes.
Indeed - keeping up-to-date is important. Over the last few months we have invested heavily in our release pipeline to things much better for ESR (previously āstableā) users. More details here. You still need to update, but there is much more flexibility around timing & urgency.
As for this specific deprecation, the solution is fully automated. If you can let us know the plugin names, weād be happy to run the codemod for you and make a PR. Weāve done it for all of the 600+ themes/plugins that we maintain, so itās a well-oiled machine at this point.
I understand that itās not easy if one comes back after a few months and finds that a lot has changed. Keeping up with the changes may not be easy, but IMO itās a price to pay for a cutting-edge forum software with an extensive API.
Then why do you keep making changes driven by tidying up minor pieces of cruft on your side at the expense of compatibility?
That legacy cruft is part of the price of maintaining a platform or API. It causes no real problems. But you insist on changing/removing it and making other people do extra work and testing as a result.
The ESRs only last for 9 months, which is hardly extended support.
And using those will just mean you have to deal with all the breaking changes at once, with a much larger list of commits to search for if youāre trying to understand why a problem happened.
ESR as it stands today will make this problem worse, not better.
The only solution is to actually care about the API and maintain it. Make breaking changes only as a last resort, not for ānice to haveā little tidy-ups. And donāt bin an entire framework people are using because you feel like using another one, or whatever the reason is.
The process here is to have production on ESR and staging on the monthly releases or on tests-passed.
If you update staging every day/week/month - you can even automate that - you will be able to iteratively update your plugins and themes and keep them in a working state.
The fact that you keep production on ESR gives you a minimum of three months leeway to fix things.
You seem unable to grasp the concept that a published API should not be a continually moving target.
Imagine if Microsoft made all Windows developers change their code every 6 months. Itās unthinkable. You can take code written for Windows 95 30 years ago and compile and run it on a modern machine today with absolutely no changes.
You cannot claim to care about compatibility when code written to your specifications will stop working due entirely to decisions you have made.
Windows controls its entire stack, Discourse is building a platform on a live ecosystem. Ember alone has broken backward compatibility repeatedly across major versions. And thatās even the norm in the frontend ecosystem, not the exception.
To me it seems very clear that the right model here isnāt Windows, itās what other API platforms do: clear versioning, deprecation notices, and a reasonable migration window.
