PhpStorm 2019.3 Help

npm and Yarn

PhpStorm integrates with the npm and Yarn package managers so you can install, locate, upgrade, and remove packages of reusable code from inside the IDE. The Node.js and NPM page provides a dedicated UI for managing packages. Of course, you can also do that from the command line in the built-in Terminal.

PhpStorm also lets you run and debug npm scripts. PhpStorm parses package.json files, recognizing definitions of scripts, shows scripts in a tree view, and lets you navigate between a script in the tree and its definition in the package.json file.

PhpStorm detects projects with Yarn workspaces and indexes all the dependencies that are listed in the package.json files of the workspaces but are located in the root node_modules folder.

PhpStorm indexes all the dependencies listed in different package.json file but stored in the root node_modules folder

Before you start

  1. Download and install Node.js. Note that npm is also installed, so if you are going to use it, you are through with the preliminary steps.

  2. To use Yarn, install it as described on the Yarn official website.

Choosing a project package manager

With PhpStorm, you can choose whether to use npm or Yarn in a project. By default, PhpStorm suggests npm. However if you open a project with a yarn.lock file and Yarn is installed on your machine, PhpStorm automatically changes the package manager for this project to Yarn. You can also set Yarn as default PhpStorm package manager.

  1. In the Settings/Preferences dialog Ctrl+Alt+S, go to Languages and Frameworks | Node.js and NPM. The Node.js and NPM page opens.

  2. In the Package manager field, specify the package manager for your project.

    • Select npm or yarn to use the system default installation.

    • To use a custom installation of a package manager, click Select, and select the installation folder of the relevant package manager.

      ws_package_manager_configuration.png

    PhpStorm automatically uses the chosen package manager when you select the Project alias from the Package manager list in the Run/Debug Configuration: NPM dialog. PhpStorm also uses the path to the chosen package manager every time you invoke the Run 'npm install'/ Run 'yarn install' command or run an npm/Yarn script, see Running and debugging scripts for details.

To set Yarn as the default PhpStorm package manager

  1. Open the Settings for New Projects dialog (File | Settings for New Projects) and go to Languages and Frameworks | Node.js and NPM.

  2. On the Node.js and NPM page that opens, choose yarn from the Package manager list. After that, PhpStorm will suggest Yarn as default every time you create a new project.

Installing packages using the built-in Terminal

As you may know, npm can install packages both globally or as project dependencies or development dependencies, learn more from the npm official website. With Yarn, you can also install packages globally or as project dependencies, see Yarn official website for details.

To install a package

  • In the embedded Terminal (Alt+F12), type one of the following commands:

    • npm install --global <package_name> or yarn global add <package_name> for global installation.

    • npm install --save <package_name>, npm install --save-dev <package_name>, or yarn add <package_name> --dev to install the package as a project dependency or a development dependency.

To install all dependencies from a package.json file

  • In the embedded Terminal (Alt+F12), type one of the following commands:

    • npm install

    • yarn install

    As a result you get all the dependencies listed in the package.json from the current folder. Learn more from Editing package.json.

Installing and upgrading packages on the Node.js and NPM page

PhpStorm shows all the currently installed packages on the Node.js and NPM page. To open the page, in the Settings/Preferences dialog Ctrl+Alt+S, click Node.js and NPM under Languages and Frameworks. Globally installed packages are listed on top. For each package, PhpStorm shows its currently installed version and the latest available version.

To install a package

  1. Click the Add button and in the Available Packages dialog that opens, select the required package.

  2. By default, the latest package version is installed. To install another one, select the Specify version checkbox and choose the required version from the list.

  3. The default installation is local. To use another installation type, select the Options checkbox and type -g for global installation or --save/--save-dev to install the package as a dependency/development dependency. Learn more from the npm and Yarn official websites.

To view the location of a package

  • Hover the mouse pointer over the package name. PhpStorm shows the path to the package in a tooltip.

To upgrade a package to the latest version

  • Select the package in the list and click the Upgrade button.

To remove a package

  • Select the package in the list and click the Uninstall (Delete) button.

Editing package.json

PhpStorm helps you handle your project dependencies in package.json files providing extensive coding assistance:

  • Code completion for package names.

    Code completion for package names
  • Information on the latest available package version.

    Showing the latest available package version
  • Information about the range of versions that can be installed through npm install <package>@<version> or yarn add <package>@<version>. `Note that running npm install or yarn install will install the latest available version from this range.

    Press Ctrl and hover over the version to see the information in a tooltip. See the npm Official documentation for details about semantic versioning.

    Showing the range of available package versions
  • Code completion for previous package versions. When you press Ctrl+Space or start typing a version different from the latest one, PhpStorm displays a suggestion list with all the previous versions of the package.

    Code completion for previous package versions
  • Quick documentation look-up for packages.

    Quick documentation look-up for packages

To install the dependencies from a package.json file

  • Open the relevant package.json file in the editor or select it in the Project tool window and choose Run 'npm install' from the context menu.

  • Click Run 'npm install' in the popup:

    ws_npm_yarn_package_run_npm_install_package_json_dependent.png

    PhpStorm shows this popup when the dependencies are not installed yet or when they have changed. If you close the popup or turn it off by choosing Don't ask again, you can still install the dependencies using the Run 'npm install' action or in the built-in terminal.

    If you have accidentally dismissed this notification and now want to get it back, press Ctrl+Shift+A, start typing Enable notifications, and select Enable Notifications about Installing Dependencies from package.json from the list.

To update your project dependencies

  • Click Run 'npm install' in the popup.

    ws_npm_yarn_package_run_npm_update.png

    PhpStorm shows this popup every time you open a project, update it from the version control, or edit a package.json.

    PhpStorm also runs an inspection that checks whether the packages from dependencies or devDependencies are installed and their versions match the specified range.

    ws_node_inspect_that_package_up_to_date.png

    If the inspection detects any mismatch, it suggests a quick-fix. To apply it, press Alt+Enter and choose Run 'npm install' from the list:

    ws_node_inspect_that_package_up_to_date_quick_fix.png

Running and debugging scripts

You can launch npm or Yarn scripts from a package.json file in the editor, from a tree of scripts in the dedicated npm tool window, according to a dedicated run configuration, or automatically, as a start-up or a before-launch task.

The results of script execution are displayed in the Run Tool Window. The tool window shows the npm or Yarn script output, reports the errors occurred, lists the packages or plugins that have not been found, etc. The name of the last executed script is displayed on the title bar of the tool window.

During a script debugging session, PhpStorm opens the Debug Tool Window where you can step through the program, stop and resume the program execution, examine it when suspended, view actual HTML DOM, and so on

To enable debugging a script

  • Add the $NODE_DEBUG_OPTION to its definition in the package.json file, for example:

    { "name": "application-name", "version": "0.0.1", "scripts": { "main": "node $NODE_DEBUG_OPTION ./app-compiled.js" } }

Running and debugging scripts from package.json

PhpStorm lets you quickly launch single scripts from package.json files. To run or debug several scripts, use a run configuration or the npm tool window.

  • Open the package.json file in the editor, click Run in the gutter next to the script, and choose Run <script_name> or Debug <script_name> from the context menu.

    ws_run_npm_task.png
  • You can also run a script by pressing Ctrl+Shift+F10.

Running and debugging scripts from the npm tool window

The tool window opens when you select a package.json file in the Project tool window or open it in the editor and choose Show npm Scripts from the context menu. As soon as you invoke npm or Yarn, it starts building a tree of scripts defined within the scripts property of the package.json file on which it was invoked. If you have several package.json files in your project, you can build a separate script tree for each of them and run scripts without dropping the previously built trees. Each tree is shown under a separate node.

To open the npm tool window if it is not opened yet

  • Select the required package.json file in the Project tool window or open it in the editor and choose Show npm Scripts from the context menu. The npm tool window opens showing the scripts tree built according to the selected or opened package.json file.

To build a tree of scripts in an already opened npm tool window

  • In the npm tool window, click the Add button on the toolbar and choose the required package.json file from the list. By default, PhpStorm shows the package.json file in the root of your project.

  • If you have another package.json file, click Choose package.json and select the package.json file you need in the dialog that opens. PhpStorm adds a new node with the path to the chosen package.json file on its title and builds a scripts tree under the new node.

To re-build a tree

  • Switch to the required node and click Reload on the toolbar.

To sort the scripts in a tree by their names

  • Click Settings on the toolbar, choose Sort by from the menu, and then choose Name.
    By default, a tree shows the scripts in the order in which they are defined in package.json (option Definition order).

To run one script

  • Double-click the script.

  • Select the script in the tree and press Enter or choose Run <script name> from the context menu.

To debug one script

  • Select the script in the tree and choose Debug <script_name> from the context menu.

To run or debug several scripts

  • Use the multiselect mode: hold Shift (for adjacent items) or Ctrl (for non-adjacent items) keys and select the required scripts, then choose Run or Debug from the context menu of the selection.

Running scripts by a run configuration

When you run or debug scripts from the editor or from the npm tool window, PhpStorm automatically creates temporary run configurations. Besides using them, you can create and launch your own npm run configurations.

  1. From the main menu, select Run | Edit Configuration.

  2. Click the Add button on the toolbar and select npm from the list. The Run/Debug Configuration: npm dialog opens.

  3. Specify the CLI command to execute, the scripts to run (use blank spaces as separators), and the location of the package.json file where these scripts are defined. Optionally, type the command line arguments for executing the scripts.

  4. Specify the Node.js interpreter to use. This can be a local Node.js interpreter or a Node.js on Windows Subsystem for Linux.

    Optionally, specify the Node.js-specific option parameters and the environment variables to be passed to Node.js.

  5. Specify the package manager to use. If you choose the Project alias, PhpStorm will use the default project package manager from the Node.js page. You can also choose the relevant package alias (npm or yarn) or specify an explicit path to a custom installation of a package manager.

  6. Select the newly created run configuration from the list on the toolbar and then click Run. The output is displayed in the Run tool window.

Running scripts with Run Anything

Run Anything is a quick way to start npm and yarn scripts.

  1. Press Ctrl twice or click the Run Anything button on the Navigation bar. The Run Anything popup opens.

  2. Type npm run or yarn run in the search field. As you type, PhpStorm shows the matching scripts. Select the required one from the list and press Enter.

Running scripts automatically on start-up

If you have some scripts 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, go to Tools | Startup Tasks.

  2. On the Startup Tasks page that opens, click the Add button on the toolbar.

  3. From the list, choose the required npm run configuration. The configuration is added to the list.

    If no applicable configuration is available in the project, click the Add button` and choose Edit Configurations. Then define a configuration with the required settings on the Run/Debug Configuration: NPM page that opens. When you save the new configuration it is automatically added to the list of startup tasks.

Running scripts as before-launch tasks

  1. Open the Run/Debug Configurations Dialog dialog by choosing Run | Edit Configurations from the main menu, and select the required configuration from the list or create it anew by clicking Add New Configuration and choosing the relevant run configuration type.

  2. In the dialog that opens, click Add in the Before launch area and choose Run npm script from the list.

  3. In the NPM Script dialog that opens, specify the npm run/debug configuration settings.

Last modified: 19 June 2020