Zoltan Kochan
4e6351952d
Correct the v12 guides from agent-skills.md through lockfile.md against pnpm/crates, and fix the same wrong text on the v11 twins where pnpm11 confirms it. Part of pnpm/tasks#191. Wrong claims (both versions): - configuring: the global auth file is auth.ini, not rc; list the npm_config_* exceptions (workspace dir, userconfig, URL-scoped auth). - config-dependencies: the hook import used an invalid ESM specifier. - docker: Example 3 ran fetch --prod and built without an offline install or pnpm-workspace.yaml. - errors: drop MISMATCHED_RELEASE_CHANNEL, describe INVALID_NODE_VERSION through nodeVersion, PEER_DEP_ISSUES needs strictPeerDependencies. - faq: no lockfile deletion after a readPackage hook, default store order, junctions depend on symlink privilege. - filtering: `!./lib` matches one project; use `!./lib/**`. - git branch lockfiles: every non [A-Za-z0-9_.-] character becomes `!`, the name is lowercased, merging deletes branch lockfiles, "or" patterns. - git-worktrees: remove the nonexistent worktree:new and shell/wt.sh. - global-packages: orphaned dirs are cleaned by add -g (and update -g in v12), not store prune; document that add -g replaces every group that contains the package. - how-peers-are-resolved: current peer directory names. - completion: built-in completion already covers --filter and scripts. - feature-comparison: broken JSR anchor. Wrong claims (v12 only): - cargo: cargo.indexUrl fails the parse, overrides apply to adding only, merge the duplicated Cargo index section into Registries. - global-virtual-store: pnx keeps its own virtual store (dlx part only; the global-install claims are left for a separate decision). - installation: the npm package installs on Node.js 18, only get-pnpm needs 22.13; trim unverified compatibility rows. Missing facts (v12): agent-skills group filtering and naming, catalogs (catalogs.default, pnx, --save-catalog, error codes), cargo recursive add, build-std, resolution keys, completion zsh/pwsh setup, config dependency location and error codes, include error codes, CI opt-outs and pnpm ci, finders on list, filtering settings and --no-fail-if-no-match, global install refusals, trust for npm-registry package managers, Rust shims, overrides link from aliases. Stale history (v12): drop v11/v10 version markers and "since v11" narration in continuous-integration, filtering, finders, git-worktrees, global-packages, global-virtual-store, how-peers-are-resolved, lockfile, completion, configuring. Review follow-up: the Node.js compatibility table keeps the pnpm 10 column; Docker Example 3 builds with all dependencies in a build stage and ships only production dependencies, with the pnpm-workspace.yaml caveat (both versions); catalogs keep the bare-path form; v11 global packages name `pnpm update -g` as cleaning orphans too; the cargo build-std note says when rust-src must be listed. Second review: build-std needs a non-empty list; the Docker fetch layer also depends on the project settings; branch lockfile names keep only ASCII characters; the conflict merge needs both sides to parse; Rust shims and package managers are default globalShims participants; pnpm self-update also cleans orphaned global groups; v12 pnpm login writes tokens to config.yaml; legacyDirFiltering keeps the subtree wording (the v12 mismatch is pnpm/tasks#196); the v12 Docker example copies the files that `include` names before pnpm fetch.
3.4 KiB
id, title
| id | title |
|---|---|
| configuring | Configuring |
pnpm settings are divided into two categories:
- Authentication and certificate settings are stored in INI files. These contain sensitive credentials and should not be committed to your repository. See Authentication Settings for details.
- All other settings are stored in YAML files: the project
pnpm-workspace.yamland the globalconfig.yaml. Some settings are project-only and are ignored in the globalconfig.yaml(see Global configuration).
pnpm does not read settings from the pnpm field of package.json. A setting found there is ignored with a warning. Define it in pnpm-workspace.yaml.
Local project configuration
Project-level settings go in pnpm-workspace.yaml:
nodeVersion: "22.22.3"
saveExact: true
Global configuration
The global YAML config file (config.yaml) is located at one of the following paths:
- If the $XDG_CONFIG_HOME env variable is set, then $XDG_CONFIG_HOME/pnpm/config.yaml
- On Windows: %LOCALAPPDATA%\pnpm\config\config.yaml
- On macOS: ~/Library/Preferences/pnpm/config.yaml
- On Linux: ~/.config/pnpm/config.yaml
Not every setting may be set in the global config.yaml. Settings that apply to the whole machine, such as storeDir, cacheDir, packageImportMethod, minimumReleaseAge, and network settings, may be set there. Settings that define the structure of a project's node_modules or workspace, such as nodeLinker, hoistPattern, publicHoistPattern, shamefullyHoist, or linkWorkspacePackages, are project-only: they have to be set in pnpm-workspace.yaml, so that the project installs the same way on every machine. Registry routes may be set globally, but the server descriptions serverType and supportsTimeField are read only from pnpm-workspace.yaml (see Registries).
pnpm config set --global refuses project-only settings with ERR_PNPM_CONFIG_SET_UNSUPPORTED_YAML_CONFIG_KEY. If they are written to config.yaml by hand, pnpm prints a warning that names them and ignores them.
To share project-only settings across several projects, publish them as a config dependency and add it to each project.
Global registry credentials go in auth.ini in the same directory. See Auth file locations.
Environment variables
Environment variables whose names start with pnpm_config_ (or PNPM_CONFIG_) are loaded into configuration. These override settings from pnpm-workspace.yaml but not CLI arguments.
:::warning
pnpm does not read npm_config_* environment variables. Use pnpm_config_* environment variables instead (e.g., pnpm_config_registry instead of npm_config_registry). The exceptions are:
NPM_CONFIG_WORKSPACE_DIR, which sets the workspace directory.npm_config_userconfig, which points to a user.npmrcfor auth settings.- URL-scoped credentials such as
npm_config_//registry.example.com/:_authToken.
:::
For example:
pnpm_config_save_exact=true pnpm add foo
If you need pnpm to work across multiple hard drives or filesystems, read the FAQ.
See the config command for more information on managing configuration.