Deprecating .hbs file extension in themes and plugins

[david (David Taylor)]

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:

Automatically updating themes and plugins to .gjs file format

In the latest version of Discourse’s standard linting config, we’ve enabled the require-strict-mode ember-template-lint rule. This will raise a linting error for any .hbs files. To resolve the warnings, you should convert all your component, route, and connector templates to .gjs files. To make this easy, we’ve built the discourse-gjs-codemod, which builds on top of Ember’s @embroider/template-tag-codemod. To use the codemod, first ensure that your linting dependencies are up-to-date by copyin…

[RGJ (Richard - Communiteq)]

@david

after the next ESR release

Do I understand correctly that 2026.7 will still support hbs files and 2027.1 will be the first ESR release that doesn’t?

[david (David Taylor)]

Yes, exactly.

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.

[RGJ (Richard - Communiteq)]

Just came across this one, guess it needs to be updated

@david

Templates introduced using this method should be moved to dedicated .hbs files, or refactored into gjs files.

To keep as HBS, connector templates can be placed in:

{theme}/javascripts/discourse/connectors/{outlet-name}/{connector-name}.hbs

and component templates can be placed in:

{theme}/javascripts/discourse/components/{component-name}.hbs

[david (David Taylor)]

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:

@david

Since March 2026, .hbs files are also deprecated. After making this conversion, move on to the instructions in Deprecating .hbs file extension in themes and plugins

[gilles]

For my part, I tried it for my small personal plugin and succeeded with the help of ask Discourse, which merged my hbs and js files into a gjs file.

I highly recommend using ask Discourse to solve this problem for those like me who have development difficulties

[david (David Taylor)]

That’s great! I’ve added a note about ask.discourse.com in the OP as well. If you only have a few files, it can work very well