PhpStorm 2017.3 Help

Grunt

PhpStorm integrates with the Grunt JavaScript Task Runner. PhpStorm parses Gruntfile.js files, recognizing definitions of tasks and targets, lets you build trees of tasks and targets and navigate between a a task or a target in the tree and its definition in the Gruntfile.js file, and supports running and debugging tasks as well as configuring the task execution mode and output.

With PhpStorm, you can launch Grunt tasks 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.

Before you start, download and install the Node.js runtime environment.

Installing Grunt

To use Grunt in a PhpStorm 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.js from the Grunt Official website.

To install grunt-cli globally
Open the built-in PhpStorm Terminal (Alt+F12) and type npm install -g grunt-cli at the command prompt.

To install Grunt in a project
Open the built-in PhpStorm Terminal (Alt+F12) and type npm install grunt --save-dev at the command prompt.

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 PhpStorm, for example, ignore warnings or provide a detailed log.

When you build a tree of tasks for the first time during the current PhpStorm session, the Grunt tool window is not opened yet.

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 open the Grunt tool window with a tree of tasks
Select the required Gruntfile.js file in the Project tool window or open it in the editor and choose Show Grunt Tasks on the context menu.

To build a tree of tasks from the Grunt tool window
In the Grunt tool window, click add_black.png on the toolbar and choose the required Gruntfile.js file from the list. PhpStorm 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 icon_reload_grunt.png on the toolbar.

To sort the tasks in a tree by their names
Click viewMode.png on the toolbar, choose Sort by on the menu, and then choose Name.
By default, a tree shows the tasks in the order in which they are defined in Gruntfile.js (option Definition order).

To run a task or a target
Double click the required task or target. Alternatively select it in the tree and press Enter or choose Run <task name> on the context menu.

To run the default task
Select the root node in the tree, and choose Run default on the context menu of the selection.

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.

To navigate to the definition of a task or a target
Select the required task or target in the tree, and choose Jump to source on the context menu of the selection.

Running and debugging tasks according to a run configuration

Besides using temporary run configurations that PhpStorm creates automatically, you can create and launch your own Grunt.js run configurations.

To create a Grunt.js run/debug configuration

  1. Choose Run | Edit Configuration on the main menu.
  2. Click add on the toolbar and select Grunt.js from the pop-up list.
  3. 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.js executable file and the Node.js-specific options to be passed to this executable file, see Node parameters for details.

    If applicable, specify the environment variables for the Node.js 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 checkbox. 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 checkbox.

To run the tasks
Select the newly created run configuration from the list on the main toolbar and click run.png next to the list. PhpStorm displays the task output in the Run tool window.

To debug the tasks

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

To run a Grunt task as a Before-Launch task

  1. Open the Run/Debug Configurations Dialog dialog by choosing Run | Edit Configurations on the main menu, and select the required configuration from the list or create it anew by clicking new and choosing the relevant run configuration type.
  2. In the dialog box that opens, click new in the Before launch area and choose Run Grunt task from the drop-down list.
  3. 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.

  1. In the Settings/Preferences dialog (Ctrl+Alt+S), click Startup Tasks underTools.
  2. On the Startup Tasks page that opens, click add.png on the toolbar.
  3. 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 add.png 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.

Last modified: 6 December 2017

See Also