Settings (pnpm-workspace.yaml)
pnpm gets its configuration from the command line, environment variables, and pnpm-workspace.yaml.
Only auth and registry settings are read from .npmrc files. All other settings (like hoistPattern, nodeLinker, shamefullyHoist, etc.) must be configured in pnpm-workspace.yaml or the global ~/.config/pnpm/config.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
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.
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.
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. 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
- ignoredOptionalDependencies
- minimumReleaseAge
- minimumReleaseAgeExclude
- minimumReleaseAgeExcludePrune
- minimumReleaseAgeIgnoreMissingTime
- minimumReleaseAgeStrict
- trustPolicy
- trustPolicyExclude
- trustPolicyIgnoreAfter
- trustLockfile
- blockExoticSubdeps
- registries
- namedRegistries
Node-Modules Settings
- modulesDir
- nodeLinker
- nodeExperimentalPackageMap
- nodePackageMapType
- symlink
- enableModulesDir
- virtualStoreDir
- virtualStoreDirMaxLength
- virtualStoreOnly
- packageImportMethod
- modulesCacheMaxAge
- dlxCacheMaxAge
- enableGlobalVirtualStore
Dependency Hoisting Settings
Store Settings
Lockfile Settings
- lockfile
- preferFrozenLockfile
- lockfileIncludeTarballUrl
- gitBranchLockfile
- mergeGitBranchLockfilesBranchPattern
- peersSuffixMaxLength
Network Settings
Request Settings
- gitShallowHosts
- networkConcurrency
- fetchRetries
- fetchRetryFactor
- fetchRetryMintimeout
- fetchRetryMaxtimeout
- fetchTimeout
- fetchWarnTimeoutMs
- fetchMinSpeedKiBps
Peer Dependency Settings
- autoInstallPeers
- dedupePeerDependents
- dedupePeers
- strictPeerDependencies
- resolvePeersFromWorkspaceRoot
- peerDependencyRules
CLI Settings
- [no-]color
- loglevel
- useBetaCli
- recursiveInstall
- engineStrict
- npmPath
- pmOnFail
- ignoreWorkspaceRootCheck
Node.js Settings
Build Settings
- ignoreScripts
- childConcurrency
- sideEffectsCache
- sideEffectsCacheReadonly
- 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
- failIfNoMatch
Settings documented elsewhere
- patchedDependencies
- pnpmfile, globalPnpmfile and ignorePnpmfile
- Authorization settings, which are read from
.npmrc