Settings (pnpm-workspace.yaml)
En esta página
- packages#
- packageConfigs#
- Settings#
- Dependency Resolution#
- Node-Modules Settings#
- Dependency Hoisting Settings#
- Store Settings#
- Lockfile Settings#
- Network Settings#
- Request Settings#
- Peer Dependency Settings#
- CLI Settings#
- Node.js Settings#
- Build Settings#
- Versioning Settings#
- Other Settings#
- Workspace Settings#
- Settings documented elsewhere#
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
:::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. 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:
```yaml title="pnpm-workspace.yaml" 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_](catalogs.md) for details.
```yaml title="pnpm-workspace.yaml"
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:
```yaml title="pnpm-workspace.yaml" packages: - "packages/project-1" - "packages/project-2" packageConfigs: "project-1": saveExact: true "project-2": savePrefix: "~"
Or as an array of pattern-matched rules:
```yaml title="pnpm-workspace.yaml"
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
- Convergence overrides
- Overriding peer dependencies
- packageExtensions
- allowedDeprecatedVersions
- update
- update.ignoreDeps
- update.changeset
- update.githubActions
- update.githubActionsServer
- 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
- Version Conflicts
- Conflict Resolution
- dedupePeerDependents
- dedupePeers
- strictPeerDependencies
- resolvePeersFromWorkspaceRoot
- peerDependencyRules
- peerDependencyRules.ignoreMissing
- peerDependencyRules.allowedVersions
- peerDependencyRules.allowAny
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
- Why this is needed
- When to disable
- 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