Using Grunt
The topic describes how to install and configure Grunt JavaScript task runner.
Overview
You can use Grunt to automate any tasks you need, but out of the box Magento comes with pre-configured grunt tasks for compiling LESS files.
Prerequisites
Make sure that you set your Magento application to the developer or default mode.
Installing and configuring Grunt
Magento has built-in Grunt tasks configured, but there are still several steps you need to take to be able to use it:
-
Install node.js to any location on your machine.
-
Install Grunt CLI tool globally. To do this, run the following command in a command prompt:
1
npm install -g grunt-cli
-
From the
<Magento_root>
directory, copy and paste the contents of the following files:package.json.sample
intopackage.json
Gruntfile.js.sample
intoGruntfile.js
grunt-config.json.sample
intogrunt-config.json
-
Install (or refresh) the
node.js
project dependency, including Grunt, for your Magento instance. To do this, run the following commands in a command prompt:1
cd your_Magento_instance_directory
1
npm install
1
npm update
-
(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 configuration file
Copy the contents of themes.js
into local-themes.js
in the dev/tools/grunt/configs/
directory.
If installed as described above, Grunt will use the default configuration files located in the dev/tools/grunt/configs/
directory. You can define your theme in the local-themes.js
file. The following shows an example of how you can define your theme.
1
2
3
4
5
6
7
8
9
10
<theme>: {
area: '<area>',
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:
<Vendor>
: vendor name.<theme>
: your theme code, conventionally should correspond to the theme directory name.<area>
: area code, can be eitherfrontend
oradminhtml
.<language>
: specified in thecode_subtag
format, for exampleen_US
. Only one locale can be specified here. To debug the theme with another locale, create one more theme declaration, having specified another value forlanguage
.<path_to_file>
: path to the root source file, relative to theapp/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.
Once these are set correctly, run grunt to watch your changes.
- Run
grunt exec:<theme>
from the root directory to republish the symlinks. - Run
grunt watch:<theme>
so that grunt will watch for file changes.
Using custom Grunt configuration files
There are several ways to declare a custom configuration file.
How to declare custom config file: Option 1
To use a custom file for Grunt configuration:
- Copy the default configuration file to the preferred location in the Magento instance directory. Do not change the file name.
-
Open the
grunt-config.json
file in the Magento root and set configurations object as follows.- key: file alias
- value: path to your custom file
Example: If your custom configuration file
local-themes.js
is located in the<magento_root>/dev/tools/grunt/configs
directory, the following is already set in yourgrunt-config.json
:1 2 3
{ "themes": "dev/tools/grunt/configs/local-themes.js" }
This path is also added to your .gitignore by default.
How to declare custom configuration file: Option 2
You can also use the other way to declare a custom config file:
-
In your Grunt related scripts, in the file router, set the alias and path to the custom configuration file. For example, to set the custom
themes.loc.js
configuration file, this would look like the following:1
filesRouter.set('themes', 'dev/tools/grunt/configs/themes.loc.js');
It must be added earlier, than the
get()
method with this alias is called. -
In the
dev/tools/grunt/configs/
directory, create a copy of the default configuration file. Change its name by adding the “.loc” suffix. For example, your copy ofthemes.js
will bethemes.loc.js
.
How to use custom configuration file
To tell Grunt to use a custom configuration file, instead of the default one, add the following in your script:
-
Require file-router:
1
var fileRouter = require('/files-router');
-
Call the
get(%file_alias%)
method to get the configuration file.1
var themes = fileRouter.get('themes');