What's in this topic
The topic describes how stylesheets are preprocessed and compiled to CSS in the Magento application. It provides the theoretical background a frontend developer needs to debug stylesheets effectively.
Terms used
Term | Description |
---|---|
Root source files |
The <head> <css src="css/styles-m.css" /> <css src="css/styles-l.css" media="screen and (min-width: 768px)"/> <css src="css/print.css" media="print" /> </head>The root source files for the Blank theme: |
LESS compilation modes
In the Magento application, the following modes of compiling .less
files to CSS are implemented:
- Server-side LESS compilation.
This is the default compilation mode, and is the only option in production application mode. In this case the compilation is performed on the server, using the LESS PHP library. - Client-side LESS compilation.
When your application is not in the production mode, you can set Magento to compile.less
files in a browser, using the nativeless.js
library
To set the compilation mode, do the following:
- In the Magento Admin, navigate to Stores > Configuration > ADVANCED > Developer.
- In the Store View drop-down field, select Default Config.
- Under Front-end development workflow, in the Workflow type field, select the compilation mode.
- To save the settings, click Save Config.
- Make sure that the same compilation mode is set for each configuration scope. That is, check the Front-end development workflow option having switched the Store View drop-down field to the website scope first, and then to the store view. Change the option to match the default config if it is different.
Server-side LESS compilation
The following paragraph describes how the LESS preprocessor works in server-side compilation mode. For each CSS file included in the layouts, LESS preprocessor does the following:
- Checks if the requested
.css
file is found. If it is found, the preprocessor stops its execution. Otherwise, it proceeds to the next step. - Changes the extension of the requested file to
.less
and tries to find the file using the Magento fallback mechanism. If the.less
file is not found, LESS preprocessor stops its execution. Otherwise, it proceeds to the next step. - Reads
.less
file contents and resolves@magento_import
and default LESS@import
directives. - Resolves all paths in
.less
files to relative paths in the system using the Magento fallback mechanism. All files resolved by the LESS preprocessor are copied tovar/view_preprocessed/less
. Imported files are processed recursively. - All source files are passed to the PHP LESS compiler. The resulting compiled
.css
files are published topub/static/frontend/<Vendor>/<theme>/<locale>
.
Client-side LESS compilation
The client-side compilation flow is similar to server-side. The difference is in the set of files, published to pub/static
on the last step. In the client-side mode, the following files are published to the pub/static/frontend/<Vendor>/<theme>/<locale>
directory:
- root source (.less) files with resolved
@magento-import
directive - symlinks to the root source file that do not contain
@magento-import
- symlinks to the
.less
files included to the root source files using the imported by@magento-import
and@import
directives
The @magento_import directive
@magento_import
is a Magento-specific LESS directive that allows including multiple files by a name pattern. It is used to include files with the same name from the different locations, for example, different modules.
The standard @import
directive includes a single file, which is found according to the static files fallback.
@magento_import
can be used in the root source files of a theme only.
@magento_import rules of usage
To include a .less
file using the @magento_import
directive:
To avoid any conflicts with the original LESS syntax,
@magento_import
must be commented out with two slashes. Otherwise, the LESS preprocessor ignores it.Example:
// Comment in a LESS document // Standard LESS import directive // --------------------------------------------- @import 'source/_reset'; @import '_styles'; // // Custom Magento LESS import directives // --------------------------------------------- //@magento_import 'source/_module.less'; // Theme modules //@magento_import 'source/_widgets.less'; // Theme widgets //@magento_import 'source/_extend.less'; // Extend for minor customization
The best practice is to specify the file extension in the path, though technically you can omit this.@magento_import
must contain the file path. The path is specified relatively to the file, where the directive is called and put in either single ('') or double quotes ("").
@magento_import processing
In the scope of static resources preprocessing, the built-in LESS preprocessor does the following:
- Searches for all
@magento_import
directives. - Replaces the original
@magento_import
directives with the standard@import
directives. The latter specify the paths to the particular files that correspond to the pattern specified in@magento_import
.
Example of how @magento-import
is used and processed in <Magento_Blank_theme_dir>/web/css/styles-l.less
:
Before | After |
---|---|
In <Magento_Blank_theme_dir>/web/css/styles-l.less there's a following directive:
.. //@magento_import 'source/_widgets.less'; // Theme widgets .. |
In the processed file, this results in the following:
@import '../Magento_Catalog/css/source/_widgets.less'; @import '../Magento_Cms/css/source/_widgets.less'; @import '../Magento_Reports/css/source/_widgets.less'; @import '../Magento_Sales/css/source/_widgets.less'; // Theme widgets |
Find us on