Running and Debugging Node.js
IntelliJ IDEA helps you run and debug your Node.js applications. You can debug applications that are started from IntelliJ IDEA as well as attach to already running applications.
Before you start
Running a Node.js application
IntelliJ IDEA runs Node.js applications according to a run configuration of the type Node.js. IntelliJ IDEA also uses this configuration for debugging Node.js applications locally.
To create a Node.js run/debug configuration
From the main menu, choose Edit Configurations dialog, click on the toolbar and select Node.js from the pop-up list. The Run/Debug Configuration: Node.js dialog opens., then in the
Specify the Node Parameters that customize the start of Node.js. For example, to make your application accessible for remote debugging, type one of the debugging flags depending on your Node.js version:
--inspect=<debugger port>for Node.js versions 6.5 and higher or
--debug=<debugger port>for any Node.js version earlier than 8. The default debugger port is
In the Application parameters text box, specify the Node.js-specific arguments to be passed to the application on start through the process.argv array.
To run an application
Choose the newly created Node.js configuration in the Select run/debug configuration drop-down list on the toolbar and click next to it. The application starts, and the Run Tool Window opens showing the application output.
If you are using a logging tool like morgan in your application and this tool writes logs to a file, you can see these logs in the Console tab of the Run tool window.
To manage logs when running a Node.js application
Create a Node.js run/debug configuration as described above and go to the Logs tab.
Click next to the Log files to be shown in console field which lists the available log files (if any).
In the Edit Log Files Aliases dialog that opens, type the alias name to show in the list of log entries and specify the location of the log file. Select whether you want to show all files that this pattern covers or only the last one.
Click OK to return to Node.js Run/Debug Configuration dialog, where the new log file is added to the list. Select the Is Active checkbox next to it. To skip the previous content, select the Skip Content checkbox.
To enable saving the console output to a log file, select the Save console output to file checkbox and specify the file location.
Choose when you want the Console shown.
Debugging a Node.js application
console.log() statements. You can do many things that will help you explore the code and understand where the bug is. In the Debug tool window, you can view the call stack and the variables in their current state, evaluate expressions in the editor, and step through the code.
Local and Remote debugging
IntelliJ IDEA supports two debugging modes:
Local debugging: in this mode, your application is started from IntelliJ IDEA and is running locally on your computer. To debug it, use a Node.js configuration.
Debugging a remote application: in this mode, your application is running in a remote environment in the debug mode and IntelliJ IDEA attaches to a running process. IntelliJ IDEA recognizes
--debugflags so you can make any application accessible for remote debugging. IntelliJ IDEA supports remote debugging with the Chrome Debugging Protocol and the V8 Debugging Protocol (also known as Legacy Protocol). In either case, a debugging session is initiated through a run/debug configuration of the type Attach to Node.js/Chrome.
Debugging a Node.js application locally
Set the breakpoints in the Node.js code where necessary.
Choose the newly created Node.js configuration in the Select run/debug configuration drop-down list on the toolbar and click next to it. The Debug Tool Window opens.
Perform the steps that will trigger the execution of the code with the breakpoints.
Switch to IntelliJ IDEA, 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.
Using interactive Debugger Console
When you are debugging a Node.js application, IntelliJ IDEA shows two console tabs in the Debug tool window - Console and Debugger Console.
console.logwas called, and use other console features provided by the Chrome Debugging Protocol.
Debugging a running Node.js application
With IntelliJ IDEA, you can debug an application that is running in a remote environment. IntelliJ IDEA supports remote debugging with the Chrome Debugging Protocol and the V8 Debugging Protocol (also known as Legacy Protocol). In either case, a debugging session is initiated through an Attach to Node.js/Chrome configuration.
To debug with Chrome Debugging Protocol
Set the breakpoints as necessary.
Choose Edit Configuration dialog box that opens, and choose Attach to Node.js/Chrome from the list. The Run/Debug Configuration: Attach to Node.js/Chrome dialog box opens.from the main menu, then click in the
Specify the host where the target application is running and the port passed to
--inspectwhen starting the Node.js process to connect to. Copy the port number from the information message
Debugger listening <host>:<port>in the Terminal tool window or in the Run tool window that controls the running application. The default port is 9229.
In the Attach to area, choose Chrome or Node.js > 6.3 started with --inspect.
Choose the newly created Attach to Node.js/Chrome configuration in the Select run/debug configuration drop-down list on the toolbar and click next to it. The Debug Tool Window opens.
Perform the actions that will trigger the code at the breakpoint. Control over the debugging session returns to IntelliJ IDEA.
To debug with V8 Debugging Protocol
Create an Attach to Node.js/Chrome run/debug configuration as described above and specify the host and the port passed to
--debug. The default port is 9229.
Make sure the application to debug has been launched in the remote environment with the following parameters:
--debug=<debugger port>. The default port is
Debugging a Node.js application that uses nodemon
The IntelliJ IDEA built-in debugger can automatically reconnect to running Node.js processes. This lets you debug Node.js applications that use the nodemon utility, which automatically reloads your Node.js process when the code is updated. To debug such application, you need to start it in the debug mode (with the
--inspect flag) and then connect to it using the Attach to a Node.js/Chrome debug configuration with the Reconnect Automatically option on.
To install nodemon
Open the embedded Terminal (Alt+F12) and type
npm install --save-dev nodemonor
yarn add nodemon --devat the command prompt to install nodemon as a development dependency.
To start an application with nodemon in the debug mode
Create and run the following
debug": "nodemon --inspect <path_to_the_file_that_starts_your_application>
Alternatively, pass the
inspectflag through a Node.js run/debug configuration as described above.
To debug an application
Set the breakpoints in your code as necessary.
Create a new Attach to a Node.js/Chrome configuration as described in Debugging a running Node.js application and select the Reconnect automatically checkbox. Usually, you don’t need to change the port in the configuration (
9229) because it’s the default port the debugger is listening on. But you can double-check what port is used in the message logged when you run the app in the debug mode.
- Choose the newly created Attach to Node.js/Chrome configuration in the Select run/debug configuration drop-down list on the toolbar and click next to it. The debugger stops at the breakpoints that you put in your code in IntelliJ IDEA.
Now, every time you make any changes to the code and save them (Ctrl+S), nodemon will automatically reload the application and the debugger will automatically re-attach to the restarted process.
Separately, using single-run configurations.
Chooseon the main menu.
Select After launch to start a browser automatically when you launch a debugging session.
In the text box below, type the URL address to open the application at.
- Choose the browser to use from the drop-down list next to the After launch checkbox.
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 Browse and adjust the settings in the Web Browsers dialog box that opens. For more information, see Configuring Browsers.
To enable Live Edit in a Node.js application
In the Settings/Preferences dialog (Ctrl+Alt+S), click Debugger under Build, Execution, Deployment, and then click Live Edit. The Live Edit page opens.
Select Update Node.js application on changes. Specify the time-delay between changing the code in the editor and showing this change in the browser: accept the default value
300 msor specify a custom value using the spin box next to the corresponding field.
Debugging a Node.js application running in a remote environment
Debugging a Node.js application in a Docker container
IntelliJ IDEA supports debugging of Node.js applications in Docker containers through run/debug configurations of the type Node.js.
Before you start debugging a Node.js application on Docker
Make sure Docker is installed, configured, and running.
To choose the Node.js interpreter on Docker
To specify the Docker container settings
Click next to the Edit Docker Container Settings field and specify the settings in the Edit Docker Container Settings dialog that opens.
Alternatively, select the Auto configure checkbox to do it automatically. Learn more about the Auto configure mode at Quick Tour of WebStorm and Docker: What Happens On Each Run.
To configure port bindings
Click in theDocker Container Settings field and expand the Port bindings area in the Edit Docker Container Settings dialog that opens.
- Click and in the Port bindings dialog that opens, 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.
Click OK to return to the Run/Debug Configuration: Node.js dialog.
To start debugging
Set the breakpoints in the Node.js code as necessary.
Choose the newly created Node.js configuration in the Select run/debug configuration drop-down list on the toolbar and click next to it.
Proceed as during a local debugging session, as described above.
Node.js multiprocess debugging
IntelliJ IDEA 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.
Set the breakpoints in the processes to debug.
Create a Node.js run/debug configuration.
- Choose the newly created configuration in the Select run/debug configuration drop-down list on the tool bar and click Debug .
The Debug Tool Window opens and the Frames drop-down list shows the additional processes as threads as soon as they are launched:
To examine the data (variables, watches, etc.) for a process, select its thread in the list and view its data in the Variables and Watches panes. When you select another process, the contents of the panes are updated accordingly.