Zoltan Kochan
52dce0f4dc
Wrong claims (v12 and the v11 twin where the v11 source agrees): - proxy precedence: a configured httpsProxy/httpProxy/noProxy wins and the environment is only a fallback; HTTPS never falls back to HTTP_PROXY - proxy opt-out: false or null in httpsProxy, httpProxy, or noProxy reads as unset; only proxy: false turns proxying off - networkConcurrency auto value is clamped to 64-96, not 16-64 - maxsockets default: unset in v12, 50 in v11 - stateDir on macOS is ~/.local/state/pnpm - unsafePerm only moves TMPDIR to node_modules/.tmp - ignoreWorkspaceRootCheck affects pnpm add only; the duplicate CLI section is removed in favor of the workspaces page - useRunningStoreServer has no effect and is removed - .npmrc also supplies TLS, proxy, and local-address settings - the list of keys a project pnpm-workspace.yaml cannot set now names scope (both) and macosBackup, ci, tools, globalShims (v12) - v12: the GVS CI auto-disable sentence, the frozenStore Node.js requirement, the JavaScript shell emulator, and the dlx global virtual store claim are corrected Missing settings (v12): saveExact, embedReadme, scriptsPrependNodePath, userAgent, lockfileDir, excludeLinksFromLockfile, globalVirtualStoreDir, externalDependencies, autoInstallPeersFromHighestMatch; loglevel silent; PNPM_HOME defaults for globalDir/globalBinDir; childConcurrency negative values; what ci changes and where updateNotifier is skipped. Index (v12): lists every section on the group pages, including progress, saveTypes, autoDedupe, maxTarballUnpackedSize, and macosBackup. Stale history (v12): removed pre-v12 "Added in" markers and rewrote "Since v10/v11" and "Before v11" sentences as current behavior. Part of pnpm/tasks#191.
16 KiB
id, title
| id | title |
|---|---|
| settings | Settings (pnpm-workspace.yaml) |
import SettingsAnchorRedirect from '@site/src/components/SettingsAnchorRedirect'
pnpm gets its configuration from the command line, environment variables, and pnpm-workspace.yaml.
Only auth, registry, TLS, proxy, and local-address settings are read from .npmrc files. All other settings are configured in pnpm-workspace.yaml or the global config.yaml. Some settings are limited to one of them: settings that define the structure of node_modules (like hoistPattern, publicHoistPattern, nodeLinker, or shamefullyHoist) can only be set in pnpm-workspace.yaml, while settings that name machine-level state (like stateDir or pnpmHomeDir) are not read from pnpm-workspace.yaml.
The pnpm config command can be used to read and edit the contents of the project and global configuration files.
The relevant configuration files are:
- Per-project configuration file:
/path/to/my/project/pnpm-workspace.yaml - Global configuration file
:::note
Authorization-related settings are handled via .npmrc.
:::
Values in the configuration files may contain env variables using the ${NAME} syntax. The env variables may also be specified with default values. Using ${NAME-fallback} will return fallback if NAME isn't set. ${NAME:-fallback} will return fallback if NAME isn't set, or is an empty string.
:::warning
Since v11.5.3, env variables are not expanded in settings of pnpm-workspace.yaml that define registry URLs: registry and the URL values of registries and namedRegistries. Values containing a ${...} placeholder in these settings are ignored. In the registry declaration shape of registries (since v11.23.0), the URL is the key rather than the value, and the same rule applies to the keys. Because pnpm-workspace.yaml is committed to the repository, expanding env variables in registry URLs could be exploited by a malicious repository to leak secrets from the environment to an attacker-controlled registry. Configure dynamic registry URLs in a trusted location instead: the global configuration file or CLI options.
:::
:::note
Since v11.22.0, a project's pnpm-workspace.yaml cannot choose where pnpm keeps its credentials, its own installation, or other machine-level state: bin, configDir, dir, globalBinDir, globalDir, npmrcAuthFile, pnpmHomeDir, stateDir, userconfig, and workspaceDir are ignored there, with a warning. Since v11.25.0, scope is ignored there too. Set them in the global configuration file or on the command line instead. cacheDir and storeDir are unaffected.
:::
packages
Besides settings, pnpm-workspace.yaml defines the root of the workspace and
enables you to include / exclude directories from the workspace. If the
packages field is omitted, only the root package is included in the workspace.
For example:
packages:
# specify a package in a direct subdir of the root
- 'my-app'
# all packages in direct subdirs of packages/
- 'packages/*'
# all packages in subdirs of components/
- 'components/**'
# exclude packages that are inside test directories
- '!**/test/**'
The root package is always included, even when custom location wildcards are used.
Catalogs are also defined in the pnpm-workspace.yaml file. See Catalogs for details.
packages:
- 'packages/*'
catalog:
chalk: ^4.1.2
catalogs:
react16:
react: ^16.7.0
react-dom: ^16.7.0
react17:
react: ^17.10.0
react-dom: ^17.10.0
packageConfigs
Added in: v11.0.0
Allows setting project-specific configuration for individual workspace packages. This replaces workspace project-specific .npmrc files.
packageConfigs can be specified as a map of package names to config objects:
packages:
- "packages/project-1"
- "packages/project-2"
packageConfigs:
"project-1":
saveExact: true
"project-2":
savePrefix: "~"
Or as an array of pattern-matched rules:
packages:
- "packages/project-1"
- "packages/project-2"
packageConfigs:
- match: ["project-1", "project-2"]
modulesDir: "node_modules"
saveExact: true
Settings
Every setting is listed below, grouped by topic. Follow a setting to read its documentation, or open the full reference of a group.
Dependency resolution
- overrides
- packageExtensions
- allowedDeprecatedVersions
- update
- supportedArchitectures
- optional
- ignoredOptionalDependencies
- forceIgnoresPlatform
- minimumReleaseAge
- minimumReleaseAgeExclude
- minimumReleaseAgeExcludePrune
- minimumReleaseAgeIgnoreMissingTime
- minimumReleaseAgeStrict
- trustPolicy
- trustPolicyExclude
- trustPolicyIgnoreAfter
- trustPolicyExcludePrune
- trustLockfile
- blockExoticSubdeps
- registries
- namedRegistries
- pnprServer
node_modules settings
- modulesDir
- nodeLinker
- nodeExperimentalPackageMap
- nodePackageMapType
- symlink
- enableModulesDir
- confirmModulesPurge
- virtualStoreDir
- virtualStoreDirMaxLength
- virtualStoreOnly
- packageImportMethod
- modulesCacheMaxAge
- dlxCacheMaxAge
- virtualStoreType
- enableGlobalVirtualStore
Dependency hoisting settings
Store settings
Lockfile settings
- lockfile
- frozenLockfile
- preferFrozenLockfile
- lockfileIncludeTarballUrl
- gitBranchLockfile
- mergeGitBranchLockfilesBranchPattern
- peersSuffixMaxLength
Network settings
Request settings
- gitShallowHosts
- networkConcurrency
- fetchRetries
- fetchRetryFactor
- fetchRetryMintimeout
- fetchRetryMaxtimeout
- fetchTimeout
- fetchWarnTimeoutMs
- fetchMinSpeedKiBps
- maxTarballUnpackedSize
Peer dependency settings
- autoInstallPeers
- dedupePeerDependents
- dedupePeers
- strictPeerDependencies
- resolvePeersFromWorkspaceRoot
- peerDependencyRules
CLI Settings
Node.js settings
Build settings
- ignoreScripts
- childConcurrency
- sideEffectsCache
- sideEffectsCacheReadonly
- sideEffectsCache.remote
- unsafePerm
- nodeOptions
- verifyDepsBeforeRun
- strictDepBuilds
- allowBuilds
- dangerouslyAllowAllBuilds
Versioning settings
- versioning.fixed
- versioning.ignore
- versioning.maxBump
- versioning.lanes
- versioning.epics
- versioning.changelog.storage
Other settings
- savePrefix
- tag
- globalDir
- globalBinDir
- npmrcAuthFile
- stateDir
- cacheDir
- useStderr
- updateNotifier
- preferSymlinkedExecutables
- ignoreCompatibilityDb
- resolutionMode
- registrySupportsTimeField
- extendNodePath
- deployAllFiles
- dedupeDirectDeps
- optimisticRepeatInstall
- requiredScripts
- enablePrePostScripts
- scriptShell
- shellEmulator
- catalogMode
- ci
- catalogPrune
Workspace settings
These settings are configured in pnpm-workspace.yaml as well, but are documented together with the workspace feature they belong to.
- linkWorkspacePackages
- injectWorkspacePackages
- dedupeInjectedDeps
- syncInjectedDepsAfterScripts
- preferWorkspacePackages
- sharedWorkspaceLockfile
- saveWorkspaceProtocol
- includeWorkspaceRoot
- ignoreWorkspaceCycles
- disallowWorkspaceCycles
- workspaceConcurrency
- ignoreWorkspaceRootCheck
- failIfNoMatch
Settings documented elsewhere
- patchedDependencies
- pnpmfile, globalPnpmfile and ignorePnpmfile
- audit.level, audit.ignore and audit.ignorePrune
- initVersion, initLicense and initAuthorName / initAuthorEmail / initAuthorUrl
- legacyDirFiltering
- Authorization settings, which are read from
.npmrc