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. 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.
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
- 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
- cleanupUnusedCatalogs
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