Using Grunt Task Runner

This feature is supported in the Ultimate edition only.

In this section:

Basics
Preparing to install Grunt
Installing Grunt
- Installing the Grunt command line interface
- Installing Grunt in a project
Running Grunt tasks
Running Grunt tasks automatically

Basics

IntelliJ IDEA provides integration with the Grunt JavaScript Task Runner. Grunt support involves:

Parsing Gruntfile.js files, recognizing definitions of tasks and targets.
Building trees of tasks and targets.
Navigation between a task or a target in the tree and its definition in the Gruntfile.js file.
Running and debugging tasks and targets.
Configuring the task execution mode and output.

Preparing to install Grunt

Download and install Node.js. The runtime environment is required for two reasons:
- The Grunt task runner is started through Node.js.
- NPM, which is a part of the runtime environment, is also the easiest way to download the Grunt task runner.
If you are going to use the command line mode, make sure the path to the parent folder of the Node.js executable file and the path to the npm folder are added to the PATH variable. This enables you to launch the Grunt task runner and npm from any folder.
Install and enable the NodeJS plugin. The plugin is not bundled with IntelliJ IDEA, but it can be installed from the JetBrains plugin repository as described in Installing, Updating and Uninstalling Repository Plugins and Enabling and Disabling Plugins.

Installing Grunt

To use Grunt in a IntelliJ IDEA project, you need two packages:

A globally installed grunt-cli package (Grunt command line interface) for executing Grunt commands.
A grunt package installed in the project to build the project tasks tree and provide coding assistance while editing the Gruntfile.js or Gruntfile.coffee file. Learn more about Gruntfile.json at http://gruntjs.com/getting-started#preparing-a-new-grunt-project.

These packages can be installed either in the command line mode or through the IntelliJ IDEA user interface. In either case, installation is performed via npm.

Installing the Grunt command line interface

The Grunt Command Line Interface is implemented in the grunt-cli package which should be installed globally to make the functionality available in any IntelliJ IDEA project and from any folder. Do one of the following:

Run the installation from the command line in the global mode:
1. Launch the embedded Terminal (View | Tool Windows | Terminal or by hovering your mouse pointer over in the lower left corner of IntelliJ IDEA and choosing Terminal from the menu
2. Switch to the directory where NPM is stored or define a PATH variable for it so it is available from any folder, see Installing NodeJs.
3. Type the following command at the command line prompt:
  npm install -g grunt-cli
  
  The -g key makes the task runner run in the global mode. Because the installation is performed through NPM, the Grunt task runner is installed in the npm folder. Make sure this parent folder is added to the PATH variable. This enables you to launch the task runner from any folder.
  
  For more details on the NPM operation modes, see npm documentation. For more information about installing the Grunt task runner, see https://npmjs.org/package/grunt-cli.
Run NPM from IntelliJ IDEA using the Node.js and NPM page of the Settings dialog box.
1. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or IntelliJ IDEA | Preferences for macOS, and click Node.js and NPM under Languages & Frameworks.
2. On the Node.js and NPM page that opens, the Packages area shows all the Node.js-dependent packages that are currently installed on your computer, both at the global and at the project level. Click .
3. In the Available Packages dialog box that opens, select the required package to install.
4. Select the Options check box and type -g in the text box next to it.
5. Optionally specify the product version and click Install Package to start installation.

Installing Grunt in a project

At the project level, the basic Grunt functionality is implemented in the grunt package. The package is responsible for building project trees of Grunt tasks and for coding assistance in editing the Gruntfile.js file. Do one of the following:

Run the installation from the command line:
1. Launch the embedded Terminal (View | Tool Windows | Terminal or by hovering your mouse pointer over in the lower left corner of IntelliJ IDEA and choosing Terminal from the menu
2. Switch to the project root folder and type the following command at the command line prompt:
  npm install grunt
Run NPM from IntelliJ IDEA using the Node.js and NPM page of the Settings dialog box.
1. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or IntelliJ IDEA | Preferences for macOS, and click Node.js and NPM under Languages & Frameworks.
2. On the Node.js and NPM page that opens, the Packages area shows all the Node.js-dependent packages that are currently installed on your computer, both at the global and at the project level. Click .
3. In the Available Packages dialog box that opens, select the required package.
4. Optionally specify the product version and click Install Package to start installation.

Running Grunt tasks

Grunt tasks are launched in the following ways:

From tasks trees in the dedicated Grunt Tool Window which opens when you invoke Grunt from a Gruntfile.js file. As soon as you invoke Grunt, it starts building a tree of tasks according to the Gruntfile.js on which it was invoked. If a task has targets, the task is displayed as a node and the targets are listed under it.
According to a dedicated run configuration, see Run/Debug Configuration: Grunt.js.
As a before-launch task, from another run configuration.

The result of executing a task is displayed in the Run tool window. The tool window shows the Grunt output, reports the errors occurred, lists the packages or plugins that have not been found, etc. The name of the last executed task is displayed on the title bar of the tool window.

Running Grunt tasks from the tasks tree

Running Grunt tasks right from the tasks tree is easy and fast, the only disadvantage of this approach is that such important additional options as force execution and verbose mode are not available in this mode. As a result, you cannot have IntelliJ IDEA, for example, ignore warnings or provide a detailed log.

Building a tasks tree

If the Grunt tool window is not opened yet, do one of the following:
- Select the required Gruntfile.js file in the Project tool window and choose Show Grunt Tasks on the context menu of the selection.
- Open the required Gruntfile.js file in the editor and choose Show Grunt Tasks on the context menu of the editor.
In either case, the Grunt tool window opens showing the tasks tree built according to the selected or opened Gruntfile.js file.
If the Grunt tool window is already opened, click on the toolbar and choose the required Gruntfile.js file from the list. IntelliJ IDEA adds a new node and builds a tasks tree under it. The title of the node shows the path to the Gruntfile.js file according to which the tree is built.
To re-build a tree, switch to the required node and click on the toolbar.

By default, the tasks in a tree a listed in the order in which they are defined in Gruntfile.js (option Definition order). To have them listed in the alphabetic order, click the toolbar button, then choose Sort by on the menu, and then choose Name.

Running tasks

To run a task or a target, do one of the following:
- To run the task, select the root node in the tree and choose on the context menu of the selection.
- To navigate to the definition of a task or target, select the required task or target in the tree and choose on the context menu of the selection.
The task or target execution output will be displayed in the Run tool window. The name of the target is shown in the format <task name>:<target name>. The tool window shows the Grunt output, reports the errors occurred, lists the packages or plugins that have not been found, etc. The name of the last executed task is displayed on the title bar of the tool window.
To run several tasks or targets, use the multiselect mode: hold Shift (for adjacent items) or Ctrl (for non-adjacent items) keys and select the required tasks or targets, then choose Run on the context menu of the selection.

Running and debugging tasks according to a run configuration

Besides using temporary run configurations that IntelliJ IDEA creates automatically, you can create and launch your own Grunt.js run configurations. For details about run configurations, see Run/Debug Configuration and Creating and Editing Run/Debug Configurations.

Creating a Grunt.js run/debug configuration

Choose Run | Edit Configuration on the main menu
Click the Add New Configuration button on the toolbar, and select Grunt.js from the pop-up list.
In the Run/Debug Configuration: Grunt.js dialog box that opens, specify the name of the run configuration, the tasks to run (use blank spaces as separators), the location of the Gruntfile.js file to retrieve the definitions of the tasks from, and the path to the Grunt package installed locally, under the project root.
Specify the location of the Node executable file and the NodeJS-specific options to be passed to this executable file, see Node parameters for details.

If applicable, specify the environment variables for the NodeJS executable file.

To have Grunt ignore warnings and continue executing the launched task until the task is completed successfully or an error occurs, select the --f check box. Otherwise, the task execution is stopped by the first reported warning. To have the verbose mode applied and thus have a full detailed log of a task execution displayed, select the --v check box.

Running a task according to a run configuration

Select the run configuration from the list on the main tool bar and then choose Run | Run <configuration name> on the main menu or click the Run toolbar button . The output is displayed in the Run tool window.

Debugging Grunt tasks

Create a Grunt.js run/debug configuration, see above.
Open the Gruntfile.js file in the editor and set the breakpoints in it where necessary.
To start a debugging session, select the required debug configuration from the list on the main tool bar and then choose Run | Debug <configuration name> on the main menu or click the Debug toolbar button .
In the Debug tool window that opens, analyze the suspended task execution, step through the task, etc. as described in Examining Suspended Program and Stepping Through the Program.

Running a Grunt task as a Before-Launch task

Open the Run/Debug Configurations dialog by choosing Run | Edit Configurations on the main menu, and select the required configuration from the list or create it anew by clicking and choosing the relevant run configuration type.
In the dialog box that opens, click in the Before launch area and choose Run Grunt task from the drop-down list.
In the Grunt task dialog box that opens, specify the Gruntfile.js where the required task is defined, select the task to execute, and specify the arguments to pass to the Grunt tool.
Specify the location of the Node.js interpreter, the parameters to pass to it, and the path to the grunt-cli package.

Running Grunt tasks automatically

If you have some tasks or targets that you run on a regular basis, you can add the corresponding run configurations to a list of startup tasks. The tasks will be executed automatically on the project start-up.

Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or IntelliJ IDEA | Preferences for macOS, and click Startup Tasks under Tools.
On the Startup Tasks page that opens, click on the toolbar.
From the drop-down list, choose the required Grunt run configuration. The configuration is added to the list.
If no applicable configuration is available in the project, click and choose Edit Configurations. Then define a configuration with the required settings in the Run/Debug Configuration: Grunt.js page that opens. When you save the new configuration it is automatically added to the list of startup tasks.

IntelliJ IDEA 2017.1 Help