npm_global_package

npm_global_package installs Node.js command-line tools for the whole node with npm install --global, such as pm2 or Yarn 1. It runs the npm program on the node. An application's own packages, which its package-lock.json lists, are npm_project_dependencies.

What npm_global_package shares with the other language and tool installers, such as run_as_user_account, npm_program_path, env, and how a change becomes a tracked input, is in what the installers share and the design's shared installer behavior. run_as_user_account is required, including when the installer runs as root.

Inputs

  • packages (list of mappings; required): each entry requires name and version; version is an exact version; newest_when_first_installed: installs the newest version when the package is missing, then never upgrades it; newest_on_every_run: also upgrades it to the newest version on every run; with state: absent, name only
  • state (present or absent; default present): present follows each entry's version choice; absent uninstalls
  • npm_program_path (string; default found on the standard path): a written value must be absolute; the npm program to run when it is not npm on the standard path, such as one from Node.js unpacked under /opt; its directory comes first in PATH, so npm finds the node beside it
  • run_as_user_account (string; required): local account that runs npm, as shell's run_as_user_account; an ordinary account needs its own global directory, such as env NPM_CONFIG_PREFIX
  • env (mapping; optional): environment variables for npm, such as NPM_CONFIG_REGISTRY; values may be secrets

Outputs

The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.

  • status
  • change
  • value

What a dryrun reports

Lists {name, from, to}; for newest_on_every_run it asks npm outdated --global.

Retries and time limits

Bounded automatic retries by default; retry: false turns them off.

The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.

Examples

Install one version of a tool

- npm_global_package:
    packages:
      - name: pm2
        version: "5.4.3"
    run_as_user_account: root

Each packages entry states an exact version or a version keyword. The task ensures pm2 5.4.3 is installed.

Use the npm of a Node.js under /opt

- npm_global_package:
    packages:
      - name: yarn
        version: "1.22.22"
    npm_program_path: /opt/node/bin/npm
    run_as_user_account: root

npm_program_path names the npm when it is not the one on the standard system path, such as one from Node.js unpacked under /opt. Its directory comes first in PATH, so npm finds the node beside it.

Keep tools at the newest version, or uninstall them

- npm_global_package:
    packages:
      - name: pm2
        version: newest_on_every_run
    run_as_user_account: root

- npm_global_package:
    packages:
      - name: yarn
    state: absent
    run_as_user_account: root

What the version keywords do is in Package versions. state: absent uninstalls each named package; removal entries take name only.

How it works

MMX reads what is installed from npm ls --global --json and runs npm only for what differs. All changed entries share one install command, each with its own version. A dryrun lists {name, from, to}; for newest_on_every_run it asks npm outdated --global.

Tracked input: the installed versions of the named packages.

Tested on

Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.

The suite language_installers.py runs on Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10, with Node.js 22 from nodejs.org unpacked under /opt, and covers npm_global_package by installing Yarn 1 (1.22.22) for the whole node.

Why it works this way

  • The task states each package's version choice. Presence alone does not say whether future runs should upgrade. See the shared design's required-settings rule.
  • The task names the installer's account. Package installers can run package code, so running as root must be an explicit choice.

This page is docs/reference/modules/npm_global_package.md in the MMX repository.