PhpStorm 2023.3 Help

Node.js with Vagrant

With Vagrant, you can quickly bootstrap your Node.js application to run, debug, and profile it from PhpStorm.

Before you start

  1. Make sure the JavaScript and TypeScript, JavaScript Debugger, Node.js, and Node.js Remote Interpreter required plugins are enabled on the Settings | Plugins page, tab Installed. For more information, refer to Managing plugins.

  2. Install and enable the Vagrant plugin on the Settings | Plugins page, tab Marketplace, as described in Installing plugins from JetBrains Marketplace.

  3. Make sure Vagrant and Oracle's VirtualBox are downloaded, installed, and configured on your computer. For more information, refer to Vagrant: Working with Reproducible Development Environments.

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

  5. To have Node.js executable in your Vagrant environment, you can start with a ready-to-use Vagrant box, for example, jandir/nodejs.

    Open the embedded Terminal (Alt+F12) and run the following commands:

    vagrant init jandir/nodejs vagrant up

Configure a Node.js interpreter in a Vagrant environment

Node.js interpreters in Vagrant environments are configured in the Configure Node.js Remote Interpreter dialog. You can open this dialog from the Node.js page of the Settings dialog or later, when you create or edit a Node.js run/debug configuration for running or debugging your application on Vagrant.

The recommended way is to configure a remote Node.js interpreter in the Settings dialog. In this case you can set the interpreter and the associated package manager as default for your project.

A remote Node.js interpreter that you configure right in the Node.js run/debug configuration can be used only with this run/debug configuration.

  1. Open the Settings dialog (Ctrl+Alt+S) and go to Languages & Frameworks | Node.js.

  2. Click the Browse button next to the Node interpreter field.

  3. In the Node.js Interpreters dialog with a list of all the currently configured interpreters, click the Add button on the toolbar and select Add Remote from the context menu .

    Configure Node.js remote interpreter in  Vagrant environment: Add Remote
  4. In the Configure Node.js Remote Interpreter dialog that opens, select Vagrant.

  5. Specify the Vagrant instance folder that 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, PhpStorm detects the Vagrant host and shows it as a link in the Vagrant Host URL read-only field.

    By default, the field shows the current project folder.

  6. In the Node.js interpreter path field, specify the location of the Node.js executable file.

    Configure remote Node.js interpreter in Vagrant environment: specify instance folder and location of Node executable

    To locate the Node.js executable, open the embedded Terminal (Alt+F12) and type:

    vagrant ssh whereis node exit
    Locate Node.js executable in a Vagrant environment
  7. Click OK to return to the Node.js Interpreters dialog where the new interpreter is added to the list.

  8. To set the newly configured interpreter as project default, select it in the list and click OK to return to the Node.js dialog.

    Remote Interpreters dialog: the new Node.js interpreter in a Vagrant environment added to the list

    PhpStorm automatically uses this interpreter every time you select the Project alias from Node Interpreter lists, for example, when creating run/debug configurations.

  9. Specify the path to the package manager to use.

    Configure remote Node.js interpreter: package manager specified

    To locate the package manager, open the embedded Terminal (Alt+F12) and type:

    vagrant ssh whereis <package manager> exit
    Locate a package manager in a Vagrant environment

Create a Node.js run/debug configuration

  1. Go to Run | Edit Configurations. In the Edit Configuration dialog that opens, click the Add New Configuration button on the toolbar and select Node.js from the context menu. The Run/Debug Configuration: Node.js dialog opens.

    In the JavaScript File field, specify the path to the file that starts the application.

    Node.js run/debug configuration: JavaScript file specified
  2. If necessary, specify some optional settings as described in Running and debugging Node.js applications.

  3. From the Node interpreter list, select the relevant remote Node.js interpreter in a Vagrant environment.

    Node.js with Vagrant: run/debug configuration, select interpreter

    Alternatively, click the Browse button next to the Node interpreter field . The Node.js Interpreters dialog opens.

    Click the Add button on the toolbar and select Add Remote from the context menu.

    Remote Interpreters dialog

    Configure a remote Node.js interpreter in a Vagrant environment as described above.

  4. Click OK to save the run/debug configuration.

Run a Node.js application in a Vagrant environment

  • From the Run/Debug Configurations list on the toolbar, select the newly created Node.js configuration and click the Run button next to it.

    Run an app in a Vagrant environment
  • Alternatively, create a Node.js run/debug configuration with a Node.js interpreter in a Vagrant environment as described above or modify an existing one and click Run in the dialog.

Check the application output

To make sure the application works as expected, you can run a HTTP request from the PhpStorm built-in HTTP Client.

Node.js with Vagrant: connect to a running app with a HTTP Request
  1. Create a HTTP Request file.

  2. Write the following request:

    GET http://<host IP>:<application port>/

    By default, the host IP is 192.168.33.10. For example:

    GET http://192.168.33.10:3000/
  3. Click the Run HTTP Request button in the gutter and click the Run HTTP Request button next to Run http://<host IP>:<application port>/.

    Launch a HTTP Request

    The application output is shown in a separate tab of the Run tool window.

Debug a Node.js application in a Vagrant environment

  1. Put breakpoints in your code as necessary.

  2. Create a Node.js run/debug configuration with a Node.js interpreter in a Vagrant environment as described above.

  3. From the Select run/debug configuration list on the toolbar, select the newly created Node.js configuration and click the Debug button next to it.

  4. In the Debug tool window that opens, 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.

    Debug a Node.js app in a Vagrant environment
Last modified: 25 March 2024