PhpStorm 2016.2 Help

Using Gulp Task Runner

PhpStorm provides integration with the Gulp.js Task Runner. Gulp.js support involves:

  • Parsing Gulpfile.js files, recognizing definitions of tasks.
  • Building trees of tasks.
  • Navigation between a task in the tree and its definition in the Gulpfile.js file.
  • Running and debugging tasks.
  • Configuring the task execution mode and output.
  • Creating a Gulp.js run configuration automatically.

On this page:

Preparing to install Gulp.js

  1. Download and install Node.js. The runtime environment is required for two reasons:
    • The Gulp.js task runner is started through Node.js.
    • NPM, which is a part of the runtime environment, is also the easiest way to download the Gulp.js 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 Gulp.js 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 Gulp.js

To run Gulp in a PhpStorm project you need a Gulp package installed locally, under the project root.

You can additionally have a global installation of Gulp. In this case, the path to the Gulp installation will be added to the PATH environment variable. This will allow you to invoke Gulp from any folder when working in the command line mode.

The basic Gulp.js functionality is implemented in the gulp.js package. The package is responsible for building project trees of Gulp tasks and for coding assistance in editing the Gulpfile.js file. The gulp package can be installed either in the command line mode or through the PhpStorm user interface. In either case, installation is performed via npm.

Installing Gulp.js in the command line 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. Do one of the following:
    • To install Gulp.js in the current project, switch to the project root folder and type the following command at the command line prompt:
      npm install gulp
    • To install Gulp.js globally, type:
      npm install --global gulp

Installing Gulp.js through the PhpStorm interface

  1. Run NPM from PhpStorm using the Node.js and NPM page of the Settings dialog box: 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 gulp package.

    Optionally:

    • Specify the version to install.
    • To have the package installed globally, select the Options check box and type --global in the text box.

  4. Click Install Package to start installation.

Running Gulp.js tasks

Gulp.js tasks can be run either from the tasks tree in the dedicated Gulp Tool Window, from the Gulpfile.js file, by launching a Gulp.js run configuration, or as aa before-launch task from another run configuration.

Running Gulp.js tasks from the tasks tree

Gulp.js starts building a tasks tree as soon as you invoke Gulp.js by choosing Show Gulp Tasks on the context menu of a Gulpfile.js in the Project tool window or of a Gulpfile.js opened in the editor. The tree is built according to the Gulpfile.js file on which Gulp.js was invoked. If you have several Gulpfile.js files in your project, you can build a separate tasks tree for each of them and run tasks without abandoning the previously built tasks trees. Each tree is shown under a separate node.

Technically, PhpStorm invokes Gulp.js and processes Gulpfile.js according to the default Gulp.js run configuration. However this is done silently and does not require any steps from your side.

Building a tasks tree

  • If the Gulp tool window is not opened yet, do one of the following:
    • Select the required Gulpfile.js file in the Project tool window and choose Show Gulp Tasks on the context menu of the selection.
    • Open the required Gulpfile.js file in the editor and choose Show Gulp Tasks on the context menu of the editor.

    In either case, the Gulp tool window opens showing the tasks tree built according to the selected or opened Gulp.js file.

  • If the Gulp tool window is already opened, click add_black.png on the toolbar and choose the required Gulpfile.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 Gulpfile.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.

If your Gulpfile.js is written in ECMA6, by default PhpStorm does not recognize this format and fails to build a tasks tree. To solve this problem, update the default Gulp.js run 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. Under the Defaults node, click Gulp.js.
  3. In the Run/Debug Configuration: Gulp.Js dialog box that opens, type --harmony in the Node options text box and click OK.

Running a task

  • To run a Gulp.js task from a tree of tasks, 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, select the required task in the tree and choose on the context menu of the selection.

    The task execution output will be displayed in the Run tool window. The tool window shows the Gulp.js 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, use the multiselect mode: hold Shift (for adjacent items) or Ctrl (for non-adjacent items) keys and select the required tasks, then choose Run on the context menu of the selection.

Running tasks from Gulpfile.js

You can run tasks right from the Gulpfile.js file opened in the editor without previously building a tree of tasks.

  • Position the cursor at the definition of the task to run and choose Run <task name> on the context menu of the selection.

    PhpStorm creates and launches a temporary run configuration with the name of the selected task.

    The task execution output will be displayed in the Run tool window. The tool window shows the Gulp.js 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 save an automatically created temporary run configuration, position the cursor at the definition of the task for which it was created and choose Save <task name> on the context menu of the selection. Learn more in Creating and Saving Temporary Run/Debug Configurations.

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 Gulp.js run configurations. For details about run configurations, see Run/Debug Configuration and Creating and Editing Run/Debug Configurations.

Creating a Gulp.js run 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 Gulp.js from the pop-up list.
  3. In the Run/Debug Configuration: Gulp.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 Gulpfile.js file to retrieve the definitions of the tasks from, and the path to the Gulp 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.

    If applicable, in the Arguments field, specify the arguments for tasks to be executed with. Use the following format:

    --<parameter_name> <parameter_value>
    For example: --env development.

    For details about passing task arguments, see https://github.com/gulpjs/gulp/blob/master/docs/recipes/pass-arguments-from-cli.md

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 Gulp tasks

  1. Create a Gulp.js run/debug configuration, see above.
  2. Open the Gulpfile.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 Gulp 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 Gulp task from the drop-down list.
  3. In the Gulp task dialog box that opens, specify the Gulpfile.js where the required task is defined, select the task to execute, and specify the arguments to pass to the Gulp tool.

    Specify the location of the Node.js interpreter, the parameters to pass to it, and the path to the gulp package.

Running Gulp.js tasks automatically

If you have some tasks 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 Gulp.js 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: Gulp.Js page that opens. When you save the new configuration it is automatically added to the list of startup tasks.

See Also

Last modified: 24 November 2016