Best practices for (Luma-compatible) Magento modules

There are many things that could be mentioned when talking about best practices for third party modules: Composer requirements that following semantic versioning. Not using deprecated class. Hint: Use the Yireo ExtensionChecker to detect some of these issues. But for frontends, there seem to be much less best practices around. If it works, it works.

To make things worse, the code for Luma (and for Hyvä, because both share some parts) looks hugely different from Vue Storefront extensions or PWA Studio extensions. For the sake of the discussion, let's stick with Luma only - pretending that that frontend technology is still current (mwoahahaha).

x-magento-init / data-mage-init?

One of the best practices I heard about in the past is to prefer x-magento-init and/or data-mage-init over a simpler usage of RequireJS (require([], function() {})) or even vanilla JS. Why? Well because x-magento-init and data-mage-init is used by Magento as well. However, if you compare the frontend functionality, JS code wrapped in x-magento-init or data-mage-init is always executed later than with simple RequireJS calls, which is again executed later than vanilla JS (in general).

Maybe this is your goal: To delay the execution of code. But if you want to improve things regarding performance, it might be better to consider vanilla JS. This means that you let go of the concept of UiComponents. And if you want the flexibility of RequireJS dependencies, overrides and mixins, you can still wrap the code in a simple require() call.

I would almost say that - noawadays - it is best practice to not use x-magento-init / data-mage-init unless you really have to.

Adding a UiComponent because you can?

So when do you need to use x-magento-init / data-mage-init? When KnockoutJS comes in play. But this does not mean that you are required to use KnockoutJS everywhere. In most cases, vanilla JS or jQuery are fine. However, when there is dynamic binding of data (for instance, when using the customerData library), using KnockoutJS becomes really useful. And with that, creating a UiComponent (a RequireJS-loaded JS component that extends from uiComponent) comes in the picture.

But if you extend uiComponent, you'll get child behaviour and regions with it. Don't need that? Use uiElement instead. Don't use links and templates either? Use uiClass instead (for basic KnockoutJS usage). And don't need that? Don't build a UiComponent.

LESS instead of CSS?

Best practice for Luma is to ship LESS code with core modules. Or well, they are not shipped in the core modules at all, but only in the Blank theme and the Luma theme. In other words, if you are extending upon the Blank theme or Luma theme, then you are reusing their LESS code. And then it becomes obvious to use LESS as well. But if you are creating a blank theme of your own, not extending Luma or Blank, why bother with using LESS.

Many agencies in the past have used their own boilerplate code instead, sometimes prefering SASS over LESS. The Snowdog theme has always been a good example of this. Hyvä is yet another good example. In other words, there are plenty of agencies (thus, developers) that are not using LESS at all. So why should third party modules then ship with LESS anyway?

I'm not sure about this one: For a third party module to support the LESS system of Luma, it can simply ship with a LESS file. That LESS file will become useless for alternate themes (Snowdog, Hyvä). But for those alternate themes, alternate support is needed anyway, so the original LESS does not harm anything. Even better, it might provide clues on what kind of code to build.

Swapping out LESS source files with a new additional CSS file (that is perhaps added in the HTML document via XML layout instruction) does not add anything here. I would just stick with the old LESS (when it comes to Luma).

New best practices

These are just a couple of pointers of what best practices could mean nowadays, when it comes to Luma-compatible Magento modules. The old best practices that Magento came up with 8-10 years ago (remember that Magento 2.0 came out in November 2015) are outdated and unfortunately it makes little sense if Adobe would come up with best practices for a hugely outdated frontend like Luma. It is up to the community instead.

In general, I would say that a Magento module could still be made compatible with Luma, in such a way that a lot of the code is reusable in other frontends as well: Clean coding, separation between backend code and frontend code, preferably vanilla JS and simple LESS/CSS to guide frontenders into converting it into their own styling.

Multiple frontends requires simpler frontend code

One solid fact should also stand out: There is no longer just a single Magento frontend. If you are claiming that there is still a single Magento frontend and that frontend is Luma, then you're living in the past. Nowadays, there are numerous frontends.

And either a Magento third party module needs to support all. Or we need to embrace the fact that integrating a Magento module in a new frontend requires refactoring of the code at hand. And if that code is straightforward, it should be little work to refactor the HTML + CSS + JS towards the frontend of your likings.