Styles debugging

What's in this topic

The topic describes how the changes you make in stylesheets are applied in the client-side and server-side LESS compilation modes, and suggests the approaches and tools you can use to streamline the process of applying and debugging customizations.

Prerequisites

Make sure that you set your Magento application to the developer or default mode.

Styles debugging in client-side compilation mode

Client-side LESS compilation is implemented using the native less.js library. The default configuration is set in lib/web/less/config.less.js; you can change it as needed.

You can find the detailed information about the configuration and other options of the less.js used in a browser at http://lesscss.org/usage/#using-less-in-the-browser.

In client-side compilation mode, most of the stylesheet customizations display immediately after you reload a page in a browser.

There are certain types of changes, that require you to clear the pub/static/frontend/<Vendor>/<theme>/<locale> directory and trigger the compilation and publication processes anew.

This is required in the following cases:

• If you change the root source files that contain the @magento-import directive, or the @import directive where the imported file is specified without extension.
• If you rename, remove, or add a .less file imported with a @magento-import or @import directive but you did not correct the directives accordingly.

To clear the pub/static/frontend/<Vendor>/<theme>/<locale> directory, delete the directory in the file system, and reload the store pages in a browser to trigger compilation and publication.

Styles debugging in server-side compilation mode

In server-side LESS compilation mode, to have your changes applied, clear pub/static/frontend/<Vendor>/<theme>/<locale> by deleting the directory in the file system, and reload the store pages to trigger compilation and publication.

Alternatively, to streamline the process of applying and debugging styles customizations, in server-side compilation mode, you can use the Grunt JavaScript task runner.

The following section describes in details how to install, configure and use Grunt for styles debugging.

Installing and configuring Grunt

Magento has built-in Grunt tasks configured, but there are still several prerequisite steps you need to take to be able to use it:

1. Install node.js to any location on your machine.
2. Install Grunt CLI tool globally. To do this, run the following command in a command prompt:
   

   npm install -g grunt-cli
   

3. Install Grunt in your Magento directory. To do this, run the following commands in a command prompt:
   

   cd <your_Magento_instance_directory>
   npm install grunt --save-dev
   

4. Install (or refresh) the node.js project dependency for your Magento instance. To do this, run the following commands in a command prompt:
   

   cd <your_Magento_instance_directory>
   npm install
   npm update
   

5. Add your theme to Grunt configuration. To do this, in the dev/tools/grunt/configs/theme.js file, add your theme to module.exports like following:

   module.exports = {
       <theme>: {
           area: 'frontend',
           name: '<Vendor>/<theme>',
           locale: '<language>', 
           files: [
               '<path_to_file1>', //path to root source file
               '<path_to_file2>'
           ],
       dsl: 'less'
       },
   

   Where the following notation is used:
   • <theme>: your theme code, conventionally should correspond to the theme directory name.
   • <language>: specified in the 'code_subtag' format, for example en_US. Only one locale can be specified here. To debug the theme with another locale, create one more theme declaration, having specified another value for language
   • <path_to_file>: path to the root source file, relative to the app/design/frontend/<Vendor>/<theme/>web directory. You need to specify all root source files of the theme. If your theme inherits from a certain theme, and does not contain its own root source files, specify the root source files of the parent theme.
6. (Optional) If you want to use Grunt for "watching" changes automatically, without reloading pages in a browser each time, install the LiveReload extension in your browser.

Grunt commands

The following table describes the grunt commands you can use performing different customization tasks. Run all commands from your Magento installation directory.

grunt clean:<theme>

grunt clean:blank

grunt exec:<theme>

grunt less:<theme>

grunt watch

Use cases of tracking changes using Grunt

The following shows which Grunt tasks to use for debugging:

• After you switch the compilation mode from client-side to server-side, run the exec command.
• After you customize the content of any .less file, except the root source files, run the less task and reload the page.
• After you customize the root source files or move the files included to the root files, run the exec command and reload the page.

If you have LiveReload installed, run the grunt watch command, and the flow is even simpler:

• After you customize the content of any .less file, changes are applied and the page reloads automatically. No additional changes are required.
• After you customize the root source files or move the files included to the root files, run the clean and exec commands, and the browser page reloads automatically.