`npm_install`

npm_install installs dependencies in the selected package directory. It uses managed pnpm when that directory's package.json declares pnpm 11+ through packageManager or devEngines.packageManager; otherwise it uses npm bundled in the selected Node.js distribution. Installation runs during xx run; pass the returned dependency to commands that need installed packages.

The package directory must exist inside the project when npm_install is called and is used as the command's working directory. xx selects the package manager from package.json at that time; a missing declaration selects npm. A regular, non-symlink package.json must exist after deps finish. Root-package workspaces are supported. Installation is always project-local.

Arguments

Argument	Required	Description
`frozen_lockfile`	No	Run `npm ci`, or `pnpm install --frozen-lockfile` when pnpm is declared. Defaults to `False`.
`omit`	No	Unique dependency types to omit: `"dev"`, `"optional"`, or `"peer"`. pnpm maps `"dev"` to `--prod` and `"optional"` to `--no-optional`; pnpm does not support `"peer"`. Defaults to `[]`.
`ignore_scripts`	No	Disable package lifecycle scripts. Defaults to `False`.
`audit`	No	Enable npm's audit request. Ignored when pnpm is declared because pnpm install has no audit option. Defaults to `True`.
`deps`	No	Dependencies activated before installation, in list order. Defaults to `[]`.
`dir`	No	Project-relative package directory. Defaults to `"."`.

npm ci removes existing node_modules, requires a lockfile consistent with package.json, and does not update package metadata or lockfiles. pnpm frozen mode requires pnpm-lock.yaml to exist and match package metadata. Lifecycle scripts can run package-supplied code. npm audit sends dependency information to the configured registry.

Call npm_install only once per package directory per project execution. It reserves the selected package directory or its nearest ancestor workspace inside the project because an install can update its lockfile and any workspace member. Other declared outputs inside that directory conflict until the xx execution finishes.

See nodejs for supported pnpm declarations and range resolution.

Examples

Install project dependencies

load("@[email protected]", "npm_install")

npm_install()

Reproduce a lockfile install

load("@[email protected]", "npm_install")

npm_install(
    frozen_lockfile=True,
    audit=False,
    dir="frontend",
)

Install production dependencies without lifecycle scripts

load("@[email protected]", "npm_install")

npm_install(
    frozen_lockfile=True,
    omit=["dev", "optional"],
    ignore_scripts=True,
    audit=False,
)