Configuring Remote Node.js Interpreters
In IntelliJ IDEA, you need to configure a remote Node.js interpreter when you want to run and debug your application on Node.js installed on a remote host or in a virtual environment. This is done in the Configure Node.js Remote Interpreter Dialog dialog that opens only from the Node.js run/debug configuration.
Configuring a remote Node.js interpreter on a host accessible through SSH connection
Before you start
-
Configure access to an ssh server on the target remote host and make sure this server is running.
-
Install the NodeJS and NodeJS Remote Interpreter repository plugins on the Plugins page as described in Managing plugins.
To configure a Node.js interpreter using SSH credentials
-
From the main menu, choose . In the Edit Configuration dialog that opens, click
on the toolbar and choose Node.js from the context menu. In the Run/Debug Configuration: Node.js dialog that opens, click
next to the Node interpreter field. -
In the Node.js Interpreters dialog that opens with a list of all the currently configured interpreters, click
on the toolbar. In the dialog that opens, choose Add Remote from the context menu. -
In the Configure Node.js Remote Interpreter Dialog that opens, choose the SSH Credentials method.
-
Specify the name of the remote host and the port which the SSH server listens to. The default port number is 22.
-
Specify your credentials to access the remote hostusernamedance with the credentials received during the registration on the server. Type your username and choose the authentication method:
-
Password: to access the host with a password. Specify the password, and select the Save password checkbox to save the password in IntelliJ IDEA.
-
Key pair (OpenSSH or PuTTY): to use SSH authentication with a key pair. To apply this authentication method, you must have a private key on the client machine and a public key on the remote server. IntelliJ IDEA supports private keys that are generated with the OpenSSH utility.
Specify the path to the file where your private key is stored and type the passphrase (if any) in the corresponding fields. To have IntelliJ IDEA remember the passphrase, select the Save passphrase checkbox.
-
OpenSSH config and authentication agent: to use SSH keys that are managed by a credentials helper application (for example, Pageant on Windows or ssh-agent on Mac and Linux).
-
- Specify the location of the Node.js executable file in accordance with the configuration of the selected remote development environment.
-
For remote hosts, IntelliJ IDEA by default suggests the /usr/bin/node folder.
-
For Vagrant instances, IntelliJ IDEA by default suggests the /usr/bin/node folder.
-
For Docker containers, IntelliJ IDEA by default suggests the node folder.
-
-
When you click OK, IntelliJ IDEA checks whether the Node.js executable is actually stored in the specified folder.
-
If no Node.js executable is found, IntelliJ IDEA displays an error message asking you whether to continue searching or save the interpreter configuration anyway.
-
If the Node.js executable is found, you return to the Node.js Interpreters dialog where the installation folder and the detected version of the Node.js interpreter are displayed.
-
Configuring a remote Node.js interpreter in a Vagrant environment instance
Before you start
Install the Vagrant, NodeJS, and NodeJS Remote Interpreter repository plugins on the Plugins page as described in Managing plugins.
Make sure Vagrant and Oracle's VirtualBox are downloaded, installed, and configured on your computer as described in Vagrant.
- Make sure that the parent folders of the following executable files are added to the system PATH variable:
vagrant.bat or vagrant from your Vagrant installation. This should be done automatically by the Vagrant installer.
VBoxManage.exe or VBoxManage from your Oracle's VirtualBox installation.
Configure the Node.js development environment in the Vagrant instance to be used. Learn more about using Vagrant with IntelliJ IDEA in Vagrant.
To configure a Node.js Interpreter in a Vagrant instance
-
From the main menu, choose . In the Edit Configuration dialog that opens, click
on the toolbar and choose Node.js from the context menu. In the Run/Debug Configuration: Node.js dialog that opens, click
next to the Node interpreter field. -
In the Node.js Interpreters dialog that opens with a list of all the currently configured interpreters, click
on the toolbar. In the dialog that opens, choose Add Remote from the context menu. -
In the Configure Node.js Remote Interpreter Dialog that opens, choose the Vagrant method.
-
Specify the Vagrant instance folder which points at the environment you are going to use. Technically, it is the folder where the VagrantFile configuration file for the desired environment is located. Based on this setting, IntelliJ IDEA detects the Vagrant host and shows it as a link in the Vagrant Host URL read-only field.
- Specify the location of the Node.js executable file in accordance with the configuration of the selected remote development environment.
-
For Vagrant instances, IntelliJ IDEA by default suggests the /usr/bin/node folder.
To specify a different folder, click
and choose the relevant folder in the dialog that opens. Note that the Node.js home directory must be open for editing. -
-
When you click OK, IntelliJ IDEA checks whether the Node.js executable is actually stored in the specified folder.
-
If no Node.js executable is found, IntelliJ IDEA displays an error message asking you whether to continue searching or save the interpreter configuration anyway.
-
If the Node.js executable is found, you return to the Node.js Interpreters dialog where the installation folder and the detected version of the Node.js interpreter are displayed.
-
Configuring a remote Node.js interpreter on a remote host accessible through SFTP
Before you start
Make sure a sftp server is running on the target remote host, and you have configured access to it.
Make sure you have at least one IntelliJ IDEA-wide server access configuration of the SFTP type to establish access to the target host. To make a configuration available in all IntelliJ IDEA projects, clear the Visible only for this project checkbox in the Deployment: Connection Tab. See Creating a Remote Server Configuration for details.
Install the NodeJS and NodeJS Remote Interpreter repository plugins on the Plugins page as described in Managing plugins.
To configure a remote Node.js interpreter based on an SFTP server access configuration
-
From the main menu, choose . In the Edit Configuration dialog that opens, click
on the toolbar and choose Node.js from the context menu. In the Run/Debug Configuration: Node.js dialog that opens, click
next to the Node interpreter field. -
In the Node.js Interpreters dialog that opens with a list of all the currently configured interpreters, click
on the toolbar. In the dialog that opens, choose Add Remote from the context menu. -
In the Configure Node.js Remote Interpreter Dialog that opens, choose the Deployment Configuration method.
-
From the Deployment Configuration list, choose the server access configuration of the SFTP type according to which you want IntelliJ IDEA to connect to the target host. If the settings specified in the chosen configuration ensure successful connection, IntelliJ IDEA displays the URL address of the target host as a link in the Deployment Host URL field.
To use an interpreter configuration, you need path mappings that set correspondence between the project folders, the folders on the server to copy project files to, and the URL addresses to access the copied data on the server. By default, IntelliJ IDEA retrieves path mappings from the chosen server access (deployment) configuration. If the configuration does not contain path mappings, IntelliJ IDEA displays the corresponding error message.
To fix the problem, open the Deployment page under the Build, Execution, Deployment node, select the relevant server access configuration, switch to the Mappings tab, and map the local folders to the folders on the server as described in the Map local folders to folders on the server and the URL addresses to access them section.
- Specify the location of the Node.js executable file in accordance with the configuration of the selected remote development environment.
-
For remote hosts, IntelliJ IDEA by default suggests the /usr/bin/node folder.
-
For Vagrant instances, IntelliJ IDEA by default suggests the /usr/bin/node folder.
-
For Docker containers, IntelliJ IDEA by default suggests the node folder.
-
-
When you click OK, IntelliJ IDEA checks whether the Node.js executable is actually stored in the specified folder.
-
If no Node.js executable is found, IntelliJ IDEA displays an error message asking you whether to continue searching or save the interpreter configuration anyway.
-
If the Node.js executable is found, you return to the Node.js Interpreters dialog where the installation folder and the detected version of the Node.js interpreter are displayed.
-
Configuring a remote Node.js interpreter in a Docker container
You can quickly bootstrap your Node.js application with Docker, IntelliJ IDEA will take care of the initial configuration by automatically creating a new Dockerfile, keeping your source code up-to-date and installing npm dependencies in the container. Configuring a Node.js environment running in a Docker container as a Node.js remote interpreter lets you run, debug, and profile your Node.js application from IntelliJ IDEA.
Before you start
Download, install, and configure Docker as described in Docker
Install the NodeJS, NodeJS Remote Interpreter, and Docker Integration repository plugins on the Plugins page as described in Managing plugins.
To configure a remote Node.js interpreter in a Docker container
-
From the main menu, choose . In the Edit Configuration dialog that opens, click
on the toolbar and choose Node.js from the context menu. In the Run/Debug Configuration: Node.js dialog that opens, click
next to the Node interpreter field. -
In the Node.js Interpreters dialog that opens with a list of all the currently configured interpreters, click
on the toolbar. In the dialog that opens, choose Add Remote from the context menu. In the Configure Node.js Remote Interpreter Dialog that opens, choose the Docker method.
In the Server field, specify the Docker configuration to use, see Configure the Docker daemon connection settings for details. Select a configuration from the list or click and create a new configuration in the Docker dialog that opens.
In the Image name field, specify the base Docker image to use. Choose one of the previously downloaded or your custom images from the list or type the image name manually, for example, node:argon or mhart/alpine-node. When you later launch the run configuration, Docker will search for the specified image on your machine. If the search fails, the image will be downloaded from the image repository specified on the Registry page.
Using a remote Node.js interpreter in a Docker container with a Docker Compose definition
With Docker Compose, you can run a Node.js server and your application code as separate services. Each service can be scaled by adding more containers if necessary. This enables you to perform efficient development and testing in a dynamic environment that is similar to production one.
Configuring mappings
When you debug an application with a remote Node.js interpreter, the debugger tells IntelliJ IDEA the name of the currently processed file and the number of the line to be processed. IntelliJ IDEA opens the local copy of this file and indicates the line with the provided number. This behaviour is enabled by specifying correspondence between files and folders on the server and their local copies. This correspondence is called mapping, it is set in the debug configuration.
To configure mappings
-
From the main menu, choose . In the Edit Configuration dialog that opens, click
on the toolbar and choose Node.js from the context menu. -
In the Run/Debug Configuration: Node.js dialog that opens, choose the required remote interpreter from the Node interpreter list.
-
Click
next to the Path Mappings field. -
The Edit Project Path Mappings Dialog that opens, shows the path mappings retrieved from the deployment configuration or Vagrantfile. These mappings are read-only.
-
To add a custom mapping, click
and specify the path in the project and the corresponding path on the remote runtime environment in the Local Path and Remote Path fields respectively. Type the paths manually or click 
and select the relevant files or folders in the dialog that opens. -
To remove a custom mapping, select it in the list and click
.
-