RubyMine 2017.3 Help

Gulp

RubyMine integrates with the Gulp.js Task Runner. RubyMine parses Gulpfile.js files, recognizing definitions of tasks, lets you build trees of tasks and navigate between a a task in the tree and its definition in the Gulpfile.js file, and supports running and debugging tasks as well as configuring the task execution mode and output.

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

Before you start

  1. Download and install the Node.js runtime environment.
  2. Install and enable the NodeJS plugin. The plugin is not bundled with RubyMine, 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 use Gulp in a RubyMine project, you need two packages:

  • A globally installed gulp-cli package (Gulp command line interface) for executing Gulp commands.
  • A gulp package installed in the project to build the project tasks tree and provide coding assistance while editing the Gulpfile.js file. Learn more about Gupfile.js from the Gulp.js Official website.

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

To install Gulp.js in a project
Open the built-in RubyMine Terminal (Alt+F12) and type npm install gulp --save-dev at the command prompt.

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, RubyMine 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.

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.

Building a tasks tree

  • If the Gulp tool window is not opened yet:
    Select the required Gulpfile.js file in the Project tool window or open it in the editor and choose Show Gulp Tasks on the context menu.

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

  • In the Gulp tool window, click add_black.png on the toolbar and choose the required Gulpfile.js file from the list. RubyMine 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.

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 Gulpfile.js (option Definition order).

If your Gulpfile.js is written in ECMA6, by default RubyMine 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.
  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 task
    Double click the required task. 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
    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.

    To navigate to the definition of a task
    Select the required task in the tree, and choose Jump to source 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.

To run tasks from Gulpfile.js, do one of the following

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

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

Running and debugging tasks according to a run configuration

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

Creating a Gulp.js run configuration

  1. Choose Run | Edit Configuration on the main menu.
  2. Click add 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.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 f or the Node.js 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 as described 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 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 Suspended Program and Stepping Through the Program.

Running a Gulp 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 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. 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 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.

Last modified: 29 November 2017

See Also