RubyMine 2017.2 Help

Running and Debugging Node.js

Before you start

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.

Local and remote modes of running or debugging Node.js applications

Running a Node.js application in RubyMine is supported only in the local mode. This means that RubyMine itself starts the Node.js engine and the target application according to a run configuration and gets full control over the session.

Debugging can be performed in two modes:

  • Locally, with the Node.js engine started from RubyMine.
  • Remotely, when RubyMine connects to an already running Node.js application. This approach gives you the possibility to re-start a debugging session without re-starting the Node.js server.
In either case, the debugging session is initiated through a debug configuration.

You can also configure the behaviour of the browser and enable debugging the client-side code of the application. This functionality is provided through a JavaScript Debug run configuration, so technically, RubyMine creates separate run configurations for the server-side and the client-side code, but you specify all your settings in one dedicated Node.js run configuration.

Running a Node.js application

  1. Create a Node.js run configuration.
  2. To launch the application, 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 Run tool window opens.
  3. Open the browser of your choice and open the page with the URL address generated through the server.listen function based on the port and host parameters. The page shows the result of executing your Node.js application.

Debugging a Node.js application locally

  1. Set the breakpoints in the Node.js code, where necessary. If you want the debugging tool to stop at the first line of your code, set a breakpoint at the first line.
  2. Create a Node.js run/debug configuration.
  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. Open the browser of your choice and open the starting page of your application. Control over the debugging session returns to RubyMine.
  5. Switch to RubyMine, where the controls of the Debug tool window are now enabled. Proceed with the debugging session step through the breakpoints, switch between frames, change values on-the-fly, examine a suspended program, evaluate expressions, and set watches.

Debugging a Node.js application running on a Docker container

  1. Set the breakpoints in the Node.js code, where necessary. If you want the debugging tool to stop at the first line of your code, set a breakpoint at the first line.
  2. On the main menu, choose Run | Edit Configurations. In the Edit Configuration dialog box that opens, click the Add New Configuration toolbar button add.png, and choose Node.js on the context menu. In the Run/Debug Configuration: Node.js dialog that opens, choose the relevant Node.js interpreter running in a Docker container. Choose one of the existing interpreters from the Node Interpreter drp-down list or configure a new one as described in Configuring Node.js Interpreters.
  3. Specify the Docker container settings. Type the settings manually, or click /help/img/idea/2017.2/browseButton.png next to the field and specify the settings in the Edit Docker Container Settings dialog that opens, or select the Auto configure checkbox to have RubyMine do it automatically.

    To invoke the automatic configuration mode for a Docker container, select the Auto configure check box in the Run/Debug Configuration: Node.js dialog. In the Automatic Configuration mode:

    • RubyMine creates a new image and installs the npm modules in it.

      RubyMine copies package.json to the /tmp/project_modules folder in the image, runs npm install, and then copies the modules to the project folder in the container. Consequently, changing package.json in the project results in re-building the image.

    • RubyMine runs the container with the new image, binds your project folder to /opt/project folder in the container to ensure synchronization on update, and maps /opt/project/node_modules to the OS temporary directory.

    With automatic configuration, you still need to bind the port that your application is running on with the port of the container. Those exposed ports are available on the Docker host’s IP address (by default 192.168.99.100). Such binding is required when you debug the client side of a Node.js Express application so you need to open the browser from your computer and access the application at the host of the container through the port specified in the application.

    1. Click /help/img/idea/2017.2/browseButton.png next to the Docker Container Settings field.
    2. In the Edit Docker Container Settings dialog that opens, expand the Port bindings area.
    3. Click /help/img/idea/2017.2/new.png. The Port bindings dialog box opens. In this dialog box, map the ports as follows:
      • In the Container port text box, type the port specified in your application.
      • In the Host port text box, type the port through which you want to open the application in the browser from your computer.
      • In the Host IP text box, type the IP address of the Docker's host, the default IP is 192.168.99.100. The host is specified in the API URL field on the Docker page of the Settings / Preferences Dialog.
      • Click OK to return to the Edit Docker Container Settings dialog where the new port mapping is added to the list.
    4. Click OK to return to the Run/Debug Configuration: Node.js dialog.

  4. Save the run configuration.
  5. Proceed as as during a local debugging session, as described above.

Debugging a running Node.js application

With RubyMine, you can connect to an already running Node.js applications. The application can be started either on the same machine or on a physically remote host.

RubyMine supports remote Node.js debugging both using the Chrome protocol (when the application is launched with the --inspect flag) and using V8 protocol. A debugging session is initiated through a run/debug configuration of the type Chromium Remote or Node.js Remote Debug respectively.

When the application to debug is running on a physically remote host, you need to run a proxy or any other software that ensures port forwarding on the Node.js server. This is necessary because the debug port can open only on the localhost network interface. The localhost network interface cannot be accessed from another machine therefore RubyMine cannot connect to it upon initiating a debugging session.

To debug with the V8 protocol

  1. Make sure the application to debug has been launched in the target environment with the following parameters: --debug-brk=<port through which the debugger on the remote host interacts with the network interface which accepts external connections> The default port is 5858.
  2. Create a Node.js Remote Debug configuration: in the Debug port text box, type the port number through which you will interact with the remote host according to the server access configuration, see Creating a Remote Server Configuration.
  3. Launch the Node.js Remote Debug configuration (select the configuration in the list and click the Debug toolbar button debug.png).
  4. In the Run tool window, copy the URL address of the server and open the corresponding page in the browser. Control over the debugging session returns to RubyMine.
  5. Switch to RubyMine. In the Debug tool window, step through the breakpoints, switch between frames, change values on-the-fly, examine a suspended program, evaluate expressions, and set watches.

To debug with the Chrome protocol

  1. Make sure the application to debug has been launched in the target environment with the following parameters: --inspect=<port through which the debugger on the remote host interacts with the network interface which accepts external connections> --debug-brk The default port is 5858.
  2. Create a Chromium Remote configuration: in the Debug port text box, type the port number through which you will interact with the remote host according to the server access configuration, see Creating a Remote Server Configuration.
  3. Launch the Chromium Remote configuration (select the configuration in the list and click the Debug toolbar button debug.png).
  4. In the Run tool window, copy the URL address of the server and open the corresponding page in the browser. Control over the debugging session returns to RubyMine.
  5. Switch to RubyMine. In the Debug tool window, step through the breakpoints, switch between frames, change values on-the-fly, examine a suspended program, evaluate expressions, and set watches.

Creating a Node.js run/debug configuration

  1. Choose Run | Edit Configuration on the main menu
  2. In the Edit Configuration dialog box that opens, click the Add New Configuration toolbar button /help/img/idea/2017.2/add.png, and choose Node.js on the context menu.
  3. In the Run/Debug Configuration: Node.js dialog box, that opens, specify the following:
    • The name of the configuration.
    • In the Node Interpreter field, specify the Node.js installation to use. Choose the local or remote interpreter from the drop-down list, or click /help/img/idea/2017.2/browseButton.png and choose the interpreter in the dialog box that opens, or configure an interpreter as described in Configuring Node.js Interpreters.
    • In the JavaScript File field, specify the location of the file to start running the Node.js application from.
    • If the file to run references any other files, specify their location in the Working directory field.
    • If applicable, in the Application parameters text box, specify the arguments to be passed to the application on start through the process.argv array.
  4. If necessary, configure the behaviour of the browser and enable debugging the client-side code of the application. This functionality is provided through a JavaScript Debug run configuration, so technically, RubyMine creates separate run configurations for the server-side and the client-side code, but you specify all your settings in one dedicated Node.js run configuration.
  5. Click OK, when ready.

Enabling Live Editing during a Node.js debugging session

You can configure the behaviour of the browser and enable debugging the client-side code of the application. This functionality is provided through a JavaScript Debug run configuration, so technically, RubyMine creates separate run configurations for the server-side and the client-side code, but you specify all your settings in one dedicated Node.js run configuration.

  1. Choose Run | Edit Configuration on the main menu
  2. From the list, choose the Node.js run configuration to activate the Live Edit functionality in. In the dialog box that opens, switch to the Browser / Live Edit tab.
  3. Select the After launch check box to have a browser started automatically after a debugging session is launched. Specify the browser to use in the drop-down list next to the check box.
    • To use the system default browser, choose Default.
    • To use a custom browser, choose it from the list. Note that Live Edit is fully supported only in Chrome.
    • To configure browsers, click the Browse button /help/img/idea/2017.2/browseButton.png and adjust the settings in the Web Browsers dialog box that opens. For more information, see Configuring Browsers.
  4. Select the With JavaScript debugger check box to enable the JavaScript debugger in the selected browser and specify the URL address to open the application at.

Creating a remote debug configuration

  1. On the main menu, choose Run | Edit Configurations.
  2. In the Edit Configuration dialog box, that opens, click the Add New Configuration toolbar button add.png, and choose Node.js Remote Debug for debugging with the V8 protocol or Chromium Remote for debugging with the Chrome protocol.
  3. In the Run/Debug Configuration: Node.js Remote Debug or Run/Debug Configuration: Chromium Remote dialog box, that opens, specify the following:
    • The name of the configuration.
    • The host where the target application is running.
    • The port to connect to. Copy the port number from the information message in the Run tool window that controls the running application.

Node.js multiprocess debugging

RubyMine supports debugging additional Node.js processes that are launched by the child_process.fork() method or by the cluster module. Such processes are shown as threads in the Frame pane on the Debugger tab of the Debug Tool Window.

  1. Set the breakpoints in the processes to debug.
  2. Create a Node.js run/debug configuration.
  3. Choose the newly created configuration in the Select run/debug configuration drop-down list on the tool bar and click the Debug toolbar button /help/img/idea/2017.2/debug.png.

    The Debug tool window opens and the Frames drop-down list shows the additional processes as threads as soon as they are launched:

    ws_node_multiprocess.png

    To examine the data (variables, watches, etc.) for a process, select its thread in the list and view its data in the Variables and Debug Tool Window. Watches panes. When you select another process, the contents of the panes are updated accordingly.

Last modified: 26 October 2017

See Also