Zoltan Kochan
3f6516caeb
Part of pnpm/tasks#191. Wrong claims: - npmrc: `ca` defaults to the system trust store (v12) or the Node.js CA set (v11), not "the npm CA certificate". - pnpm-cli: `--config.<key>` does not populate `npm_config_*` for scripts (v11 and v12). - pnpm-vs-npm, package-sources: `file:` directories are copied into the virtual store and installed; only `link:` is a symlink. - pnpmfile: `importPackage` is removed in v12; changing the pnpmfile re-resolves, so the lockfile need not be deleted (v11 and v12). - scripts: list every environment variable a script receives (v11 and v12), and the full set of built-ins a script can shadow. - supply-chain-security: build scripts are blocked by `allowBuilds` and `strictDepBuilds`, and `blockExoticSubdeps` is on by default. - workspaces: pnpm has built-in release management (v11 and v12). Missing: - npmrc: `NODE_EXTRA_CA_CERTS`. - pnpm-cli: `--workspace-packages`, `-y`, and the `NO_COLOR`, `pnpm_config_*`, `PNPM_HOME`, `PNPM_SHIM_BYPASS` variables. - package_json: a `packageManager` section, `@<scope>:registry` in the `publishConfig` list, the built-in injected-deps sync. - pnpmfile: `beforePacking(pkg, dir, context)`, TL;DR rows for `updateConfig`, `preResolution`, `finders`, the `.cjs` fallback. - typescript: `addMissingPeerTypes`; uninstall: cache, state, and config directories; scripts: project lifecycle stages; workspaces: a minimal `packages` example and live sync while a script runs. - sidebar: `only-allow-pnpm`, `production`, and `cli/cache`. Clarity and duplication: - One home for git-dependency preparation (package-managers), Python index rules (registries), finders (finders.md). - motivation, symlinked-node-modules-structure: files are hard-linked or cloned; package directories are real directories; Node resolves symlinks to real paths. - podman copies the lockfile and workspace manifest; webcontainers leads with `pmOnFail: ignore`; task priority applies within a concurrency group; logos get alt text; store-loader spells out CAS. - using-changesets workflow uses the same action versions and Node.js 24 as the CI guide (v11 and v12). Stale history on v12 pages: - Removed "Added in" markers for v11 and older, and rewrote "Since v11..." and pnpm 10/11 narration as current behavior. Review follow-up: the script environment notes say which npm_config_* keys are filtered (auth, scope registry, per-registry) and that pnpm sets npm_config_user_agent and npm_config_node_gyp; a string `bin` sets npm_package_bin; NODE_EXTRA_CA_CERTS adds to whichever CA set applies; the v10 codemod command notes pnpx; motivation notes that pnpm copies files when neither hard links nor clones work; production says `pnpm fetch` reads the lockfile, not the package manifests.
3.7 KiB
id, title
| id | title |
|---|---|
| scripts | Scripts |
How pnpm handles the scripts field of package.json.
Hidden scripts
Added in: v11.0.0
Scripts with names starting with . are hidden. They cannot be run directly via pnpm run and are omitted from the pnpm run listing. Hidden scripts can only be called from other scripts.
{
"scripts": {
".helper": "echo 'I am hidden'",
"build": "pnpm run .helper && tsc"
}
}
In this example, pnpm run .helper would fail, but pnpm run build would succeed because .helper is called from another script.
Environment variables
pnpm sets the following environment variables during lifecycle script execution:
npm_package_name: the package namenpm_package_version: the package versionnpm_package_config_*,npm_package_engines_*,npm_package_bin_*: theconfig,engines, andbinfields of the manifest, one variable per entry (for example,npm_package_config_port). A stringbinsetsnpm_package_bin.npm_package_json: the path to the package'spackage.jsonnpm_lifecycle_event: the name of the running script (e.g.,postinstall)npm_lifecycle_script: the command of the running scriptnpm_node_execpathandNODE: the path to the Node.js executablenpm_execpath: the path to the running pnpmnpm_config_user_agent: pnpm's user agent stringnpm_config_node_gyp: the path to the bundlednode-gyp, unless the environment already sets itINIT_CWD: the directory where pnpm was startedPNPM_SCRIPT_SRC_DIR: the directory of the package whose script runsTMPDIR:node_modules/.tmpin the package, unlessunsafePermistrue
:::note
Apart from the variables above, pnpm does not set npm_config_* variables from
its configuration. Other npm_config_* variables in the environment reach the
script unchanged, except auth, scope-registry, and per-registry settings (names
starting with _, /, or @, or containing :_).
:::
Built-in command and script name conflicts
Added in: v11.0.0
The following built-in commands prefer user scripts: clean, setup, deploy, and rebuild. If your package.json defines a script with one of these names, pnpm <name> will execute the script instead of the built-in command.
To force the built-in command, use pnpm pm <name>.
Lifecycle scripts
pnpm:devPreinstall
Runs when pnpm install runs in the project itself, including in CI. It does not run when the package is installed as a dependency of another project.
Runs before any dependency is installed.
This script is executed only when set in the root project's package.json.
Since v11.28.0, installs that skip devDependencies, such as pnpm install --prod, do not run it.
preinstall of the root project
Since v11.28.0, the root project's preinstall script runs before dependencies are resolved and linked. A guard such as npx only-allow pnpm can therefore stop the install before pnpm populates node_modules.
prepare
The root project's prepare script runs after pnpm install. It is skipped, since v11.28.0, by installs that skip devDependencies (such as pnpm install --prod), by pnpm install given package arguments, and for the project that pnpm deploy deploys.
Uninstall scripts
Added in: v11.28.0
pnpm remove runs the project's own preuninstall, uninstall, and postuninstall scripts. preuninstall and uninstall run before dependencies are unlinked, and a failure in either aborts the removal. postuninstall runs after unlinking completes. The ignoreScripts setting and --lockfile-only skip all three.