The Right LESS File for the Right Purpose

When implementing styles for a specific module in Magento, it’s important to understand the distinction between different filenames. Both _module.less and _extend.less are available to be implemented in the context of a specific module.

The difference between these files is one of convention rather than function. The LESS compilation process simply aggregates the contents of both (or either) from all registered modules: from the modules' own directories, or from the module namespaces within applicable themes. But the whole purpose of reserving two filenames for this purpose rather than one is so that theme-specific alterations can be made in one (_extend.less) without the need for wholesale duplication of all the foundational styles in the other (_module.less).

So when styling your module features, it’s important to think strategically about which styles are theme-agnostic, providing the basics of the visual presentation - layout, or perhaps practical spacing, font sizes, etc. These styles belong in _module.less and live with the module itself. (Notwithstanding the core codebase’s predilection for placing this file within the “blank” ancestor theme!) But any styles dependent on your specific theme need to be placed within that theme, in the module’s namespace with an _extend.less.

This is particularly important when styles contain any references to LESS variables that are declared in _theme.less rather than in the lower-level library files. If such references are placed in a module’s base directory, your CSS may compile without complaint in your site’s current typical deployment scenarios, but you’ve introduced a dependency that will cause compilation to fail in the context of any other theme!

Keeping theme-agnostic styles in _module.less and theme-specific styles in _extend.less within the theme makes your modules more reliable, portable, and functional, while giving you full flexibility to custom tailor their presentation in your theme.