PhpStorm 2016.2 Help

Using Grunt Task Runner

PhpStorm 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.

On this page:

Preparing to install Grunt

  1. 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.

  2. Install and enable the NodeJS plugin. The plugin is not bundled with PhpStorm, 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 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.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 PhpStorm 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 PhpStorm 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 by hovering your mouse pointer over show_tool_window_bars in the lower left corner of PhpStorm and choosing Terminal from the menu (see Working with Embedded Local Terminal for details).
    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 PhpStorm 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 PhpStorm | Preferences for OS X, 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 add.
    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 by hovering your mouse pointer over show_tool_window_bars in the lower left corner of PhpStorm and choosing Terminal from the menu (see Working with Embedded Local Terminal for details).
    2. Switch to the project root folder and type the following command at the command line prompt:
      npm install grunt
  • Run NPM from PhpStorm 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 PhpStorm | Preferences for OS X, 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 add.
    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 three 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 PhpStorm, 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 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.

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 PhpStorm 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

  1. Choose Run | Edit Configuration on the main menu. Alternatively, click Shift+Alt+F10 and select Edit Configuration from the pop-up menu.
  2. Click the Add New Configuration button add.png 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 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 run.png. The output is displayed in the Run tool window.

Debugging Grunt tasks

  1. Create a Grunt.js run/debug configuration, see 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 then choose Run | Debug <configuration name> on the main menu or click the Debug toolbar button debug.png.
  4. 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

  1. 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 add and choosing the relevant run configuration type.
  2. In the dialog box that opens, click add 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. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or PhpStorm | Preferences for OS X, and click Startup Tasks under Tools.
  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.

See Also

Last modified: 2 September 2016