Tips & Tricks

Using Gulp in WebStorm

Whether you’re using Grunt or Gulp as a build system/task runner in your project, WebStorm is here to help you with that. WebStorm 8 introduced integration with Grunt, and now WebStorm 9 brings integration with Gulp.

With Gulp you can easily automate your build process. It helps you execute various tasks, such as optimizing images, compiling the stylesheets, concatenating and minifying files. Gulp uses Node.js streams and, thus, can perform multiple operations on your assets really efficiently without creating temp files. Check Gulp website for more details.

WebStorm can help you run and debug your Gulp tasks. Moreover, since gulpfile.js (a Gulp build file) is a JavaScript code, WebStorm can also provide you with coding assistance for that. Let’s see how it all works.

Installing Gulp

Gulp can be installed via npm. It requires global installation, so you may need to use sudo (for OSX, *nix, BSD, etc.) or run your command shell as Administrator (for Windows) to do this:

npm install -g gulp

Then install Gulp in your project dev dependencies (in the package.json file):

npm install --save-dev gulp

Adding gulpfile.js

Now you need to create a gulpfile.js under your project root where you can describe your tasks.

Note: We won’t provide any recommendations in writing Gulp tasks it this post, we suggest you visiting the Gulp GitHub page where you can learn more about Gulp functions and available plugins and also search for the recipes for common Gulp use-cases.

To get proper coding assistance in gulpfile.js in WebStorm, make sure coding assistance for Node.js APIs is enabled: go to Languages & Frameworks | Node.js and npm and hit Enable.


By default that would enable completion for Node.js APIs for the whole project. To limit it to gulpfile.js only, click on the Usage scope… button that would appear, click on the project root in the Library column and select Clear. Then click on the gulpfile.js and select Node.js Core library from the drop-down list.

Running Gulp tasks

Once you have a gulpfile.js with tasks in your project, right-click this file and select Show Gulp tasks.

You’ll see a nice tool window with a list of the available tasks. You can run any of them simply by clicking it in the tree or selecting the task and hitting Enter. Once the task is started, the Run window with the task execution log will appear.


Another option is to invoke Run Gulp Task popup with Alt-F11 shortcut and then run the selected task by hitting Enter.


You can create a new Gulp Run/Debug configuration for the task.

Similar to any other JavaScript or Node.js configuration you can run a Gulp configuration  with the Run… action (menu Run – Run…, Ctrl-Alt-R shortcut on Mac/Ctrl-Shift-F10 on Windows and Linux or the Run button in the upper-right corner of the IDE window) or debug with the Debug… action.


From the task name in the tool window you can run and debug tasks, but also navigate to the task definition — just click Jump to source in the context menu.


Tip: You can run a task right from the editor while editing gulpfile.js: hit Ctrl-Alt-R on Mac or Ctrl-Shift-F10 on Windows or Linux when the caret is inside the task body or right-click the task — you’ll see the Run and Debug task actions right in the context menu.


Debugging tasks

Gulp integration also allows you to debug Gulp tasks.

Put a breakpoint in the task and then select Debug task in the context menu in the Gulp tool window. Once the debugger is opened, you can execute the code step by step, evaluate expressions, and explore the variables view.


If you’re using IntelliJ IDEA 14, PhpStorm 8, RubyMine 7 or PyCharm 4, you can also enjoy Gulp integration since it’s a part of the JavaScript Support plugin.

Your WebStorm Team

Comments below can no longer be edited.

17 Responses to Using Gulp in WebStorm

  1. Avatar

    Andrii Dieiev says:

    November 24, 2014

    Great feature. Saves a lot switches to console sometimes.

    Unfortunately “Jump to source” doesn’t work because we are splitting task across several files. It makes sense to create a ticket for this?

    And is there any way to don’t show automatically created gulp tasks in Select Run/Debug configuration dropdown?(they are grayed out in Run/Debug configuration window)
    Now it requires switch to proper debug configuration every time when you run gulp task 🙁

    • Ekaterina Prigara

      Ekaterina Prigara says:

      November 24, 2014

      Thanks, Andrii, for your comment. Both issues really deserve being reported on the issue tracker. Thanks!

  2. Avatar

    Colt McCormack says:

    November 24, 2014

    It would be really cool to be able to set tasks to run at start up.

    I have a file watcher task that watches for file changes and I sometimes forget to run it after I open up the project. If it automatically started that task whenever I opened the project then my build system would “just work” without me needing to intervene at all.

    If there was an option for that in the Run/Debug Configuration panel that would be awesome.

    • Ekaterina Prigara

      Ekaterina Prigara says:

      November 25, 2014

      As a workaround you can add a run/debug configuration for a Gulp task as a “before run” task to your JavaScript debug configuration.
      Please vote for the feature request about adding startup tasks:

  3. Avatar

    Stephan Schmidt says:

    December 1, 2014

    What would be nice, is if the output of Gulp tasks are parsed and errors are linked to lines of code.

    • Ekaterina Prigara

      Ekaterina Prigara says:

      December 1, 2014

      You can navigate to the files and lines of code from the error message:

      To parse the output messages for the executed tasks would be complicated since they don’t have any unified format and each plugin can generate its custom output.

  4. Avatar

    John Papa says:

    January 11, 2015

    How do you pass command line arguments to the gulp tasks?

  5. Avatar

    paul says:

    February 9, 2015

    I’m new to WebStorm, have the most recent update on OSX. I can’t seem to debug or use live-edit in a project that has gulp tasks. Breakpoints etc aren’t hit and in most cases the debugger button is disabled. It has to be something simple however so far I’m stumped.

    Node and NPM are setup as per this blog by John Papa:

    And I’m using this Angular project by John Papa:

  6. Avatar

    Gabe Shackle says:

    February 23, 2015

    Why is the Gulp interface different from Grunt within the IDE? It’s somewhat inconvenient to have two separate panes to operate the Gulp tasks and see the output vs the single pane used with Grunt.

    • Ekaterina Prigara

      Ekaterina Prigara says:

      February 25, 2015

      We added Gulp support after we introduced Grunt support and we’ve made some improvements based on the feedback. At the moment we’re making Grunt integration working the same way as we have it for Gulp. So stay tuned with WebStorm 10 EAP updates.

  7. Avatar

    M. Kermani says:

    January 3, 2018

    It would be perfect if we could save and share the configurations we set inside the IDE!

    • Ekaterina Prigara

      Ekaterina Prigara says:

      January 3, 2018

      All run/debug configurations created in WebStorm can be shared via version control: in the run configuration click the Share checkbox on the top right corner of the Edit configuration dialog; an xml file will be created describing this configuration in the .idea project folder; you can commit this file and then other people who are working on this project in WebStorm will see it.

  8. Avatar

    Amisi Kalonda says:

    April 18, 2018

    In my gulpfile there is a task that shows a selection list in the prompt. With the arrow keys, you can make a choice from 3 options.

    When I run the gulp task with the tree view buttons, I cannot use the selection in the prompt. The arrow keys do not change the selection given in the prompt.

    When I run the same gulp task from the terminal, everything works fine. I now can use the arrow keys on my keyboard to make a selection.

    Are the arrow keys disabled (in non-terminal settings)?
    or is this a bug in WebStorm?
    How can this be fixed?

    • Ekaterina Prigara

      Ekaterina Prigara says:

      April 18, 2018

      Hello Amisi,
      That’s a known issue and unfortunately, there’s no proper workaround we can offer. You can either use the number keys to select different options (press 1 and enter to select the first option, 2 and enter to select the second, etc) or run this task in the terminal. Here’s an issue on our tracker that you can follow: