Settings (pnpm-workspace.yaml)
pnpm gets its configuration from the command line, environment variables, pnpm-workspace.yaml
, and
.npmrc
files.
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:
~/.config/pnpm/rc
(an INI-formatted list ofkey = value
parameters)
Authorization-related settings are handled by npm's configuration system. So, pnpm config set registry=<value>
will actually save the setting to npm's global configuration file.
Values in the configuration files may contain env variables using the ${NAME}
syntax. また、 環境変数はデフォルト値と共に指定することもできます。 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.
Dependency Resolution
overrides
このフィールドを指定すると、依存関係グラフにおける任意の依存関係を上書きするようpnpmに指示できるようになります。 This is useful for enforcing all your packages to use a single version of a dependency, backporting a fix, replacing a dependency with a fork, or removing an unused dependency.
overrides
フィールドは、最上位のプロジェクトでしか設定できないので注意してください。
An example of the overrides
field:
overrides:
"foo": "^1.0.0"
"quux": "npm:@myorg/quux@^1.0.0"
"bar@^2.1.0": "3.0.0"
"qar@1>zoo": "2"
You may specify the package the overridden dependency belongs to by
separating the package selector from the dependency selector with a ">", for
example qar@1>zoo
will only override the zoo
dependency of qar@1
, not for
any other dependencies.
An override may be defined as a reference to a direct dependency's spec.
This is achieved by prefixing the name of the dependency with a $
:
{
"dependencies": {
"foo": "^1.0.0"
}
}
overrides:
foo: "$foo"
The referenced package does not need to match the overridden one:
overrides:
bar: "$foo"
If you find that your use of a certain package doesn't require one of its dependencies, you may use -
to remove it. For example, if package foo@1.0.0
requires a large package named bar
for a function that you don't use, removing it could reduce install time:
overrides:
"foo@1.0.0>bar": "-"
This feature is especially useful with optionalDependencies
, where most optional packages can be safely skipped.
packageExtensions
The packageExtensions
fields offer a way to extend the existing package definitions with additional information. For example, if react-redux
should have react-dom
in its peerDependencies
but it has not, it is possible to patch react-redux
using packageExtensions
:
packageExtensions:
react-redux:
peerDependencies:
react-dom: "*"
The keys in packageExtensions
are package names or package names and semver ranges, so it is possible to patch only some versions of a package:
packageExtensions:
react-redux@1:
peerDependencies:
react-dom: "*"
The following fields may be extended using packageExtensions
: dependencies
, optionalDependencies
, peerDependencies
, and peerDependenciesMeta
.
より長い例は次のとおりです。
packageExtensions:
express@1:
optionalDependencies:
typescript: "2"
fork-ts-checker-webpack-plugin:
dependencies:
"@babel/core": "1"
peerDependencies:
eslint: ">= 6"
peerDependenciesMeta:
eslint: {
optional: true
Together with Yarn, we maintain a database of packageExtensions
to patch broken packages in the ecosystem.
If you use packageExtensions
, consider sending a PR upstream and contributing your extension to the @yarnpkg/extensions
database.
allowedDeprecatedVersions
This setting allows muting deprecation warnings of specific packages.
例:
allowedDeprecatedVersions:
express: "1"
request: "*"
With the above configuration pnpm will not print deprecation warnings about any version of request
and about v1 of express
.
updateConfig
updateConfig.ignoreDependencies
Sometimes you can't update a dependency. For instance, the latest version of the dependency started to use ESM but your project is not yet in ESM. Annoyingly, such a package will be always printed out by the pnpm outdated
command and updated, when running pnpm update --latest
. However, you may list packages that you don't want to upgrade in the ignoreDependencies
field:
updateConfig: {
ignoreDependencies:
- load-json-file
Patterns are also supported, so you may ignore any packages from a scope: @babel/*
.
supportedArchitectures
You can specify architectures for which you'd like to install optional dependencies, even if they don't match the architecture of the system running the install.
For example, the following configuration tells to install optional dependencies for Windows x64:
supportedArchitectures:
os:
- win32
cpu:
- x64
Whereas this configuration will install optional dependencies for Windows, macOS, and the architecture of the system currently running the install. It includes artifacts for both x64 and arm64 CPUs:
supportedArchitectures:
os:
- win32
- darwin
- current
cpu:
- x64
- arm64
Additionally, supportedArchitectures
also supports specifying the libc
of the system.
ignoredOptionalDependencies
If an optional dependency has its name included in this array, it will be skipped. 例:
ignoredOptionalDependencies:
- fsevents
- "@esbuild/*"
依存の巻き上げ設定
hoist
- Default: true
- Type: boolean
When true
, all dependencies are hoisted to node_modules/.pnpm/node_modules
. This makes
unlisted dependencies accessible to all packages inside node_modules
.
hoistWorkspacePackages
- Default: true
- Type: boolean
When true
, packages from the workspaces are symlinked to either <workspace_root>/node_modules/.pnpm/node_modules
or to <workspace_root>/node_modules
depending on other hoisting settings (hoistPattern
and publicHoistPattern
).
hoistPattern
- Default: ['*']
- Type: string[]
Tells pnpm which packages should be hoisted to node_modules/.pnpm/node_modules
. デフォルトでは、全てのパッケージが巻き上げられます。しかし、phantom dependency を持つ、扱いに困るパッケージの存在が分かっている場合には、このオプションにより、それらを除外して巻き上げることができます (推奨)。
例:
hoistPattern:
- "*eslint*"
- "*babel*"
You may also exclude patterns from hoisting using !
.
例:
hoistPattern:
- "*types*"
- "!@types/react"
publicHoistPattern
- Default: []
- Type: string[]
Unlike hoistPattern
, which hoists dependencies to a hidden modules directory
inside the virtual store, publicHoistPattern
hoists dependencies matching
the pattern to the root modules directory. ルートのモジュールディレクトリへの巻き上げによって、アプリケーションのコードは phantom dependencies へアクセスできるようになります。たとえ依存関係の解決方法が不適切に変更されたとしてもアクセス可 能です。
この設定は、依存関係を適切に解決していなくて扱いに困る、プラグイン可能なツールを利用する場合に便利です。
例:
publicHoistPattern:
- "*plugin*"
Note: Setting shamefullyHoist
to true
is the same as setting
publicHoistPattern
to *
.
You may also exclude patterns from hoisting using !
.
例:
publicHoistPattern:
- "*types*"
- "!@types/react"
shamefullyHoist
- Default: false
- Type: Boolean
By default, pnpm creates a semistrict node_modules
, meaning dependencies have
access to undeclared dependencies but modules outside of node_modules
do not.
エコシステム内のほとんどのパッケージは、この方法で問題なく動作します。
However, if some tooling only works when the hoisted dependencies are in the
root of node_modules
, you can set this to true
to hoist them for you.
node_modules に関する設定
modulesDir
- Default: node_modules
- Type: path
The directory in which dependencies will be installed (instead of
node_modules
).
nodeLinker
- Default: isolated
- Type: isolated, hoisted, pnp
Node.js のパッケージをインストールするのに使用するリンカーを指定します。
- isolated - dependencies are symlinked from a virtual store at
node_modules/.pnpm
. - hoisted - a flat
node_modules
without symlinks is created. Same as thenode_modules
created by npm or Yarn Classic. この設定を使用すると、Yarnのライブラリーの 1 つが巻き上げに使用されます。 この設定を使用する合理的な理由は以下のとおりです:- 使っているツールはシ ンボリックリンクではうまく機能しない。 A React Native project will most probably only work if you use a hoisted
node_modules
. - プロジェクトがサーバーレスホスティングにデプロイされる。 一部のサーバーレスサービスの提供者 (AWS Lambdaなど) はシンボリックリンクをサポートしていません。 この問題を解決する代替策は、デプロイ前にアプリケーションをバンドルすることです。
- If you want to publish your package with
"bundledDependencies"
. - If you are running Node.js with the --preserve-symlinks flag.
- 使っているツールはシ ンボリックリンクではうまく機能しない。 A React Native project will most probably only work if you use a hoisted
- pnp - no
node_modules
. Plug'n'Play is an innovative strategy for Node that is used by Yarn Berry. It is recommended to also setsymlink
setting tofalse
when usingpnp
as your linker.
symlink
- Default: true
- Type: Boolean
When symlink
is set to false
, pnpm creates a virtual store directory without
any symlinks. It is a useful setting together with nodeLinker=pnp
.
enableModulesDir
- Default: true
- Type: Boolean
When false
, pnpm will not write any files to the modules directory
(node_modules
). この設定はユーザスペース上のファイルシステム (FUSE) にモジュールディレクトリがマウントされている場合に有用です。 There is an experimental CLI that allows you to
mount a modules directory with FUSE: @pnpm/mount-modules.
virtualStoreDir
- Default: node_modules/.pnpm
- Types: path
ストアにリンクするディレクトリを指定する。 すべてのプロジェクトの直接および間接的な依存はこのディレクトリへリンクされる。
Windows 上でのパスの長さ上限に関する問題を解決するのに役立ちます。 If
you have some dependencies with very long paths, you can select a virtual store
in the root of your drive (for instance C:\my-project-store
).
Or you can set the virtual store to .pnpm
and add it to .gitignore
. 依存のディレクトリをひとつ上にすることで、スタックトレース上での表示がすっきりします。
NOTE: the virtual store cannot be shared between several projects. すべてのプロジェクトはそれぞれ固有の仮想ストアを持つ必要があります。 (ルートが共通のワークスペース内のプロジェクトは除く)
virtualStoreDirMaxLength
- デフォルト:
- On Linux/macOS: 120
- On Windows: 60
- Types: number
Sets the maximum allowed length of directory names inside the virtual store directory (node_modules/.pnpm
). You may set this to a lower number if you encounter long path issues on Windows.
packageImportMethod
- Default: auto
- Type: auto, hardlink, copy, clone, clone-or-copy
Controls the way packages are imported from the store (if you want to disable symlinks inside node_modules
, then you need to change the nodeLinker setting, not this one).
- auto - try to clone packages from the store. クローンがサポートされていない場合、ストアからパッケージをハードリンクします。 クローンもリンクもできない場合は、コピーします。
- hardlink - hard link packages from the store
- clone-or-copy - try to clone packages from the store. クローンがサポートされていない場合、コピーにフォールバックします。
- copy - copy packages from the store
- clone - clone (AKA copy-on-write or reference link) packages from the store
クローンはパッケージを node_modules に書き込む最良の方法です。 最速かつ最も安全です。 クローンを使用している場合、node_modules 内のファイルを編 集可能です(編集しても中央ストア側のファイルは変更されません)。
残念ながら、すべてのファイル システムがクローン作成をサポートしているわけではありません。 pnpmで最高の経験をするためには、コピーオンライト (CoW) ファイルシステム (例えばLinuxでは Ext4 の代わりに Btrfs) を使用することをお勧めします。
modulesCacheMaxAge
- Default: 10080 (7 days in minutes)
- Type: number
孤立したパッケージを node_module
ディレクトリから削除するまでの時間を分単位で指定します。
pnpm はパッケージのキャッシュを node_module
ディレクトリに保持します。 これにより、ブランチを切り替えたり、依存のダウングレードを行う際のインストールのスピードを速くします。
dlxCacheMaxAge
- Default: 1440 (1 day in minutes)
- Type: number
The time in minutes after which dlx cache expires. After executing a dlx command, pnpm keeps a cache that omits the installation step for subsequent calls to the same dlx command.
Store Settings
storeDir
- デフォルト:
- If the $PNPM_HOME env variable is set, then $PNPM_HOME/store
- If the $XDG_DATA_HOME env variable is set, then $XDG_DATA_HOME/pnpm/store
- On Windows: ~/AppData/Local/pnpm/store
- On macOS: ~/Library/pnpm/store
- On Linux: ~/.local/share/pnpm/store
- Type: path
パッケージをディスク上のどこに保存するか指定します。
ストアはインストールを行うのと同じディスク状にある必要があります。つまり、ディスクごとに一つのストアを持つことになります。 現在のディスクにホームディレクトリがある場合は、その中にストアが作成されます。 ディスク上にホームディレクトリがない場合は、ストアはファイルシステムのルートに作られます。 For
example, if installation is happening on a filesystem mounted at /mnt
,
then the store will be created at /mnt/.pnpm-store
. Windows システムでも同様です。
異なるディスク上のストアを指定することも可能ですが、その場合 pnpm はハードリンクをせずにパッケージをコピーします。これは、ハードリンクは同一のファイルシステム上でのみ使用可能なためです。
verifyStoreIntegrity
- Default: true
- Type: Boolean
By default, if a file in the store has been modified, the content of this file is checked before linking it to a project's node_modules
. If verifyStoreIntegrity
is set to false
, files in the content-addressable store will not be checked during installation.
useRunningStoreServer
Deprecated feature
- Default: false
- Type: Boolean
Only allows installation with a store server. If no store server is running, installation will fail.
strictStorePkgContentCheck
- Default: true
- Type: Boolean
Some registries allow the exact same content to be published under different package names and/or versions. This breaks the validity checks of packages in the store. To avoid errors when verifying the names and versions of such packages in the store, you may set the strictStorePkgContentCheck
setting to false
.
ロックファイル設定
lockfile
- Default: true
- Type: Boolean
When set to false
, pnpm won't read or generate a pnpm-lock.yaml
file.
preferFrozenLockfile
- Default: true
- Type: Boolean
When set to true
and the available pnpm-lock.yaml
satisfies the
package.json
dependencies directive, a headless installation is performed. A
headless installation skips all dependency resolution as it does not need to
modify the lockfile.
lockfileIncludeTarballUrl
- Default: false
- Type: Boolean
Add the full URL to the package's tarball to every entry in pnpm-lock.yaml
.
gitBranchLockfile
- Default: false
- Type: Boolean
When set to true
, the generated lockfile name after installation will be named
based on the current branch name to completely avoid merge conflicts. For example,
if the current branch name is feature-foo
, the corresponding lockfile name will
be pnpm-lock.feature-foo.yaml
instead of pnpm-lock.yaml
. It is typically used
in conjunction with the command line argument --merge-git-branch-lockfiles
or by
setting mergeGitBranchLockfilesBranchPattern
in the pnpm-workspace.yaml
file.
mergeGitBranchLockfilesBranchPattern
- Default: null
- Type: Array or null
This configuration matches the current branch name to determine whether to merge
all git branch lockfile files. By default, you need to manually pass the
--merge-git-branch-lockfiles
command line parameter. This configuration allows
this process to be automatically completed.
例:
mergeGitBranchLockfilesBranchPattern:
- main
- release*
You may also exclude patterns using !
.
peersSuffixMaxLength
- Default: 1000
- Type: number
Max length of the peer IDs suffix added to dependency keys in the lockfile. If the suffix is longer, it is replaced with a hash.
Registry & Authentication Settings
registry
- Default: https://registry.npmjs.org/
- Type: url
The base URL of the npm package registry (trailing slash included).
<scope>:registry
The npm registry that should be used for packages of the specified scope. For
example, setting @babel:registry=https://example.com/packages/npm/
will enforce that when you use pnpm add @babel/core
, or any @babel
scoped
package, the package will be fetched from https://example.com/packages/npm
instead of the default registry.
<URL>:_authToken
Define the authentication bearer token to use when accessing the specified registry. 例:
//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
You may also use an environment variable. 例:
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
Or you may just use an environment variable directly, without changing .npmrc
at all:
npm_config_//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
<URL>:tokenHelper
A token helper is an executable which outputs an auth token. This can be used in situations where the authToken is not a constant value but is something that refreshes regularly, where a script or other tool can use an existing refresh token to obtain a new access token.
The configuration for the path to the helper must be an absolute path, with no arguments. In order to be secure, it is only permitted to set this value in the user .npmrc
. Otherwise a project could place a value in a project's local .npmrc
and run arbitrary executables.
Setting a token helper for the default registry:
tokenHelper=/home/ivan/token-generator
Setting a token helper for the specified registry:
//registry.corp.com:tokenHelper=/home/ivan/token-generator