0xdarkmatter/claude-mods/package-manager-ops

Package Manager Operations

Day-to-day use of npm, Yarn, pnpm, Bun and Composer: which one a repo uses, which install command belongs in dev, CI and deploy, how to pin Node and PHP so every machine agrees, how to run packages without fetching strangers' code, and how to get off the legacy tools. Written for server-rendered sites (Craft CMS, Laravel, WordPress) on DDEV with a Vite or Laravel Mix build, where these mistakes are common: two lockfiles, unpinned Node, no require.php, end-of-life PHP and npx in READMEs.

Facts verified as of 2026-10-06 against docs.npmjs.com, yarnpkg.com, pnpm.io, bun.com,

getcomposer.org (checked against the 2.10.3 tag), nodejs.org, php.net and

docs.ddev.com. Current majors: npm 12 (since 2026-07-08; Node 24 and 26 still bundle

npm 11), pnpm 12, Yarn 4, Composer 2 (2.10.3), Bun 1. Each reference cites its sources.

For a version-sensitive answer, read assets/package-manager-facts.json and re-check

upstream when this date is stale; keeping it current (scripts/check-pm-facts.py) is in

version-pinning.md.

Start here

Hard rules

1. One JS manager and one JS lockfile per package root, committed. The lockfile is the

contract; the manifest only says what an update may move to. A composer.lock beside it is normal, and committed too.

1. Frozen installs everywhere but a dev machine. CI and deploy run npm ci,

yarn install --immutable, pnpm install --frozen-lockfile or composer install. Never npm install or composer update on a server; if a frozen install fails, the fix happens on a dev machine and is committed.

1. Never switch managers by deleting the lockfile. Import it (pnpm import, npm reading

yarn.lock, Yarn 4 migrating a v1 lock) so resolved versions survive.

1. Pin the runtimes and make every pin agree. Node: .nvmrc, engines.node with

engine-strict=true in .npmrc (pnpm: engineStrict in pnpm-workspace.yaml), DDEV nodejs_version (or auto). PHP: require.php (range), config.platform.php (production's exact version) and DDEV php_version (same major.minor). Production pins name supported releases.

1. Run package managers where the code runs. In a DDEV project that is

ddev composer ... and ddev npm ...; never install node_modules from both the host and the container.

1. No `npx` in package.json scripts; exact pins everywhere else. In CI npx installs

without asking. Never route a native CLI (rg, fd, sd, jq) through npx: its npm name is not its official channel.

1. Credentials live in the environment. Committed .npmrc/.yarnrc.yml hold

${NPM_TOKEN} for npm and Yarn. pnpm 11.5.3+ ignores that placeholder in a project .npmrc, so a pnpm token goes in user config or the environment. Composer uses global auth.json or COMPOSER_AUTH. A committed token is revoked first, removed second.

1. Read the error before the flag. --legacy-peer-deps, --force and

--no-scripts hide the problem from everyone except you; if one is truly needed, it goes in project config with a comment, so every machine resolves the same tree.

1. Upgrade one layer at a time: runtime, manager, build tooling, frameworks, leaf

libraries; one major per commit.

The install table

Two facts that changed recently and break old habits: Corepack has not shipped with Node since 25.0.0 (install it standalone where you still rely on packageManager through it), and npm 12, pnpm 10+, Yarn 4.14+ and Bun (outside its built-in trusted list) all block dependency install scripts by default.

Audit a repo: pm-audit

A read-only scan of one repo root. It finds conflicting lockfiles, lockfiles that disagree with their manifests, Node and PHP pins that are missing, disagree with each other or with DDEV, or name end-of-life releases, unpinned npx/dlx use in scripts, docs and CI, native CLIs routed through npx, Bower and node-sass, committed registry credentials (reported by file and line, never by value), and .npmrc placeholders pnpm ignores. From CI configs, Dockerfiles and appspec hook scripts it reports unfrozen installs, Yarn flags on npm, unpinned global installs, deploys without --no-dev, Composer 1, and credentials written into a Docker build context; it follows a CI build into the subfolder it runs in. It lists nested package roots and flags them when they use another manager, or when CI installs in one that has no lockfile.

Paths are relative to this skill's folder; in Claude Code use ${CLAUDE_SKILL_DIR}/scripts/....

bash scripts/run-python.sh scripts/pm-audit.py path/to/repo
bash scripts/run-python.sh scripts/pm-audit.py --json path/to/repo | jq -r '.data[] | "\(.id)\t\(.file)"'
bash scripts/run-python.sh scripts/pm-audit.py --no-docs --as-of 2027-01-01 path/to/repo

• Exit 0 clean, 10 findings, 2 usage, 3 path missing. Plain output is one TSV

row per finding: severity, id, file, message, fix. Advisory notes go to stderr.

• --as-of moves the end-of-life line (PHP 8.2 dies on 2026-12-31: ask before you

ship). --no-docs skips the npx walk of docs; package.json scripts and the CI and deploy checks still run.

• It audits root manifests; run it again on each nested root it lists. Every finding id, its meaning and its fix are in

diagnostics.md. DDEV's own .ddev/ config is ddev-ops' auditor; pm-audit only checks that DDEV agrees.

• Sweeping many repos: read-only sparse clones, the branch that deploys, and the

findings to check by hand are in diagnostics.md.

• scripts/run-python.sh picks the first real Python 3.8+ (python3, python, py),

stepping over the Windows Store python3 stub. The skill folder runs copied alone.

Boundaries

This skill covers running build scripts, not configuring bundlers, and day-to-day dependency use, not deciding whether a package is safe.

References