.npmrc
pnpm は、コマンド行、環境変数、および .npmrc
ファイルから設定を取得します。
pnpm config
コマンドを使用して、ユーザーおよびグローバルの .npmrc
ファイルの内容を更新および編集することができます。
関連する4つのファイルは次のとおりです。
- プロジェクトごとの設定ファイル(
/path/to/my/project/.npmrc
) - ワークスペースごとの設定ファイル (
pnpm-workspace.yaml
ファイルが含まれているディレクトリー) - ユーザーごとの設定ファイル(
~/.npmrc
) - グローバルな設定ファイル (
/etc/npmrc
)
.npmrc
ファイルはすべて key = value
という INI形式 のパラメータのリストです。
依存の巻き上げ設定
hoist
追加されたバージョン:v4.0.0
- デフォルト: true
- タイプ: boolean
true
の場合、すべての依存関係は node_modules/.pnpm
に巻き上げられます。 これにより、リストされていない依存に、 node_modules
内のすべてのパッケージからアクセスできるようになります。
hoist-pattern
追加されたバージョン:v4.0.0
- デフォルト: ['*']
- タイプ: string[]
どのパッケージを node_modules/.pnpm
に巻き上げるかを指定します。 デフォルトでは、全てのパッケージが巻き上げられます。しかし、非常に多くの依存を持つ、扱いに困るパッケージについてわかっている場合には、このオプションにより、それらを省いて巻き上げするように指定することができます。 (推奨)
例:
hoist-pattern[]=*eslint*
hoist-pattern[]=*babel*
public-hoist-pattern
追加されたバージョン:v5.2.0
- デフォルト: ['*types*', '*eslint*', '@prettier/plugin-*', '*prettier-plugin-*']
- タイプ: string[]
hoist-pattern
が仮想ストア内の隠し node_modules
ディレクトリに依存を巻き上げるのに対し、public-hoist-pattern
はパターンにマッチする依存をルートの node_modules
ディレクトリへと巻き上げます。 ルートの node_modules
ディレクトリに巻き上げると、アプリケーションのコードは、たとえ依存解決方法を不適切なものに変更されていたとしても、それらの巻き上げられた非常に大量の依存へアクセスできることになります。
この設定は、いくつかのプラグイン機構を持った、依存を適切に解決しない、扱いに困るツールを扱う際に役立ちます。
例:
public-hoist-pattern[]=*plugin*
注意: shamefully-hoist
を true
に設定するのと public-hoist-pattern
を *
に設定するのは同じ効果があります。
shamefully-hoist
追加されたバージョン: v1.34.0 で shamefully-flatten
として追加され、v4.0.0 で名前が変更されました。
- デフォルト: false
- タイプ: Boolean
デフォルトでは、pnpm はそれなりに厳格な node_modules
を作成します。依存パッケージは定義されない依存へのアクセスをすることが可能なまま、node_modules
の外からはアクセスできないようになっています。 この方式では、ほとんどのパッケージがそのエコシステムの中で問題なく機能します。 ただし、いくつかのツールが、依存がルートの node_modules
に 巻き上げられている場合にのみ機能する場合には、この設定を true
にすることでそのように巻き上げることができます。
node_modules に関する設定
store-dir
追加されたバージョン: v4.2.0 で store
として追加されました
- デフォルト: ~/.pnpm-store
- タイプ: path
パッケージをディスク上のどこに保存するか指定します。
ストアはインストールを行うのと同じディスク状にある必要があります。つまり、ディスクごとに一つのストアを持つことになります。 現在のディスク状にホームディレクトリがある場合は、ストアは<home dir>/.pnpm-store
に作られます。 もしディスク状にホームディレクトリがない場合は、ストアはファイルシステムのルートに作られます。 例えば、/mnt
にマウントされたファイルシステム状でインストールを行なった場合、ストアは /mnt/.pnpm-store
に作られます。 Windows システムでも同様です。
異なるディスク状のストアを指定することも可能ですが、その場合 pnpm はハードリンクをせずにパッケージをコピーします。これは、ハードリンクは同一のファイルシステム状でのみ可能なためです。
modules-dir
追加されたバージョン:v4.14.0
- デフォルト: node_modules
- タイプ: path
node_modules
の代わりに依存をインストールする場所を指定します。
node-linker
追加されたバージョン:v5.9.0
- デフォルト: isolated
- タイプ: isolated, hoisted, pnp
Node.js のパッケージをインストールするのに使用するリンカーを指定します。
- isolated - 依存関係は
node_modules/.pnpm
の仮想ストアからシンボリックリンクでインストールされます。 - hoisted - シンボリックリンクは作成されず、フラットな
node_modules
が作成されます。 npm や Yarn Classic によって作成されるnode_modules
と同じです。 この設定を使用する合理的な理由は以下のとおりです:- 使っているツールはシンボリックリンクではうまく機能しない。 React Native のプロジェクトは、おそらく、巻き上げられた(hoisted)
node_modules
を使用する場合にのみ機能します。 - プロジェクトがサーバーレスホスティングにデプロイされる。 一部のサーバーレスサービスの提供者 (AWS Lambdaなど) はシンボリックリンクをサポートしていません。 この問題を解決する代替策は、デプロイ前にアプリケーションをバンドルすることです。
"bundledDependencies"
としてパッケージを公開したい場合- --preserve-symlinks フラグを指定して Node.js を実行している場合。
- 使っているツールはシンボリックリンクではうまく機能しない。 React Native のプロジェクトは、おそらく、巻き上げられた(hoisted)
- pnp -
node_modules
なし。 Plug'n'Play は Yarn で使用されている Node のための革新的な方式です。pnp
をリンカーとして使う場合には、symlink
をfalse
に設定することが推奨されます。
symlink
追加されたバージョン:v5.9.0
- デフォルト: true
- タイプ: Boolean
symlink
を false
に設定すると、pnpm は仮想ストアのディレクトリをシンボリックリンクを用いずに構成します。 この設定は node-linker=pnp
と組み合わせる際に役立ちます。
enable-modules-dir
追加されたバージョン:v5.15.0
- デフォルト: true
- タイプ: Boolean
false
を設定すると、pnpm は node_modules
ディレクトリにファイルを一切書き込みません。 この設定はユーザスペース上のファイルシステム (FUSE) に node_modules
ディレクトリがマウントされている場合に有用です。 node_module
ディレクトリを FUSE でマウントするのに使える実験的な CLIツールがあります: @pnpm/mount-modules
virtual-store-dir
追加されたバージョン:v4.1.0
- デフォルト: node_modules/.pnpm
- タイプ: path
ストアにリンクするディレクトリを指定する。 すべてのプロジェクトの直接および間接的な依存はこのディレクトリへリンクされる。
Windows 上でのパスの長さ上限に関する問題を解決するのに役立ちます。 何らかの非常に長いパスを持つ依存がある場合、ドライブ上のルートに仮想ストアを置くことが可能です。 (例: C:\my-project-store
)
もしくは、仮想ストアを .pnpm
にして .gitignore
に追記することもできます。 依存のディレクトリをひとつ上にすることで、スタックトレース上での表示がすっきりします。
注意: 仮想ストアは複数のプロジェクト間で共有することはできません。 すべてのプロジェクトはそれぞれ固有の仮想ストアを持つ必要があります。 (ルートが共通のワークスペース内のプロジェクトは除く)
package-import-method
追加されたバージョン:v1.25.0
- デフォルト: auto
- タイプ: auto, hardlink, copy, clone
パッケージがストアからインポートされる方法を制御します。
- auto - ストアからパッケージをクローンしようとします。 クローンがサポートされていない場合、ストアからパッケージをハードリンクします。 クローンもリンクもできない場合は、コピーします。
- hardlink - ストアからパッケージをハードリンクします。
- copy - ストアからパッケージをハードリンクします。
- clone - ストアからパッケージをクローンします。 (別名: copy-on-write、 参照リンク)
modules-cache-max-age
追加されたバージョン:v6.0.0
- デフォルト: 10080 (単位は分、7 日)
- タイプ: number
孤立したパッケージを node_module
ディレクトリから削除するまでの時間を分単位で指定します。 pnpm はパッケージのキャッシュを node_module
ディレクトリに保持します。 これにより、ブランチを切り替えたり、依存のダウングレードを行う際のインストールのスピードを速くします。
ロックファイル設定
lockfile
追加されたバージョン: v1.32.0 で shrinkwrap
として追加されました
- デフォルト: true
- タイプ: Boolean
false
に設定すると、pnpm は pnpm-lock.yaml
を読み込んだり、書き込んだりしません。
prefer-frozen-lockfile
追加されたバージョン: v1.37.1 で prefer-frozen-shrinkwrap
として追加されました
- デフォルト: true (v1.38.0 から)
- タイプ: Boolean
true
に設定すると、pnpm-lock.yaml
が存在して、 package.json
の依存指定の条件を満たす場合に、ヘッドレスインストールを行います。 ヘッドレスインストールでは、lockfile を変更する必要がないため、すべての依存関係の解決がスキップされます。
レジストリ & 認証設定
registry
- デフォルト: https://registry.npmjs.org/
- タイプ: url
npm パッケージレジストリのベースURL (末尾のスラッシュを含める)。
<scope>:registry
特定のスコープのパッケージに対して使うレジストリを指定する。 例えば、 @babel:registry=https://example.com/packages/npm/
を設定すると、pnpm add @babel/core
やその他の @babel
スコープのパッケージをインストールする際に、デフォルトのレジストリの代わりに https://example.com/packages/npm
を使うように強制します。
<URL>:_authToken
レジストリにアクセスするときに使用する認証用の Bearer トークンを指定します。 For example:
//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
環境変数を使用することもできます。 For example:
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
<URL>:tokenHelper
追加されたバージョン:v6.25.0
tokenHelper とは、アクセストークンを出力する実行ファイルです。 これは、authToken が一定値ではなく定期的に更新されるような場合に使用します。 スクリプトやその他のツールが、既存のリフレッシュトークンを使って新しいアクセストークンを取得できるようになります。
helper へのパスの設定は、引数なしの絶対パスである必要があります。 安全性を高めるため、この値はユーザーの .npmrc
にのみ設定することが許されています。 そうしないと、プロジェクトがプロジェクトのローカルの .npmrc
に値を置いて、任意の実行ファイルを実行することができてしまいます。
デフォルトのレジストリに tokenHelper を設定します:
tokenHelper=/home/ivan/token-generator
指定されたレジストリに tokenHelper を設定します:
//registry.corp.com:tokenHelper=/home/ivan/token-generator
リクエスト設定
ca
- Default: The npm CA certificate
- Type: String, Array or null
The Certificate Authority signing certificate that is trusted for SSL connections to the registry. Values should be in PEM format (AKA "Base-64 encoded X.509 (.CER)"). For example:
ca="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"
Set to null to only allow known registrars, or to a specific CA cert to trust only that specific signing authority.
Multiple CAs can be trusted by specifying an array of certificates:
ca[]="..."
ca[]="..."
See also the strict-ssl
config.
cafile
- デフォルト: null
- タイプ: path
A path to a file containing one or multiple Certificate Authority signing certificates. Similar to the ca
setting, but allows for multiple CAs, as well as for the CA information to be stored in a file instead of being specified via CLI.
cert
- デフォルト: null
- タイプ: String
A client certificate to pass when accessing the registry. Values should be in PEM format (AKA "Base-64 encoded X.509 (.CER)"). For example:
cert="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"
It is not the path to a certificate file (and there is no certfile
option).
https-proxy
- デフォルト: null
- タイプ: url
A proxy to use for outgoing HTTPS requests. If the HTTPS_PROXY
, https_proxy
, HTTP_PROXY
or http_proxy
environment variables are set, their values will be used instead.
key
- デフォルト: null
- タイプ: String
A client key to pass when accessing the registry. Values should be in PEM format (AKA "Base-64 encoded X.509 (.CER)"). For example:
key="-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----"
It is not the path to a key file (and there is no keyfile
option).
local-address
- Default: undefined
- Type: IP Address
The IP address of the local interface to use when making connections to the npm registry.
proxy
- デフォルト: null
- タイプ: url
A proxy to use for outgoing http requests. If the HTTP_PROXY or http_proxy environment variables are set, proxy settings will be honored by the underlying request library.
maxsockets
Added in: v6.18.0
- Default: network-concurrency x 3
- タイプ: Number
The maximum number of connections to use per origin (protocol/host/port combination).
noproxy
Added in: v5.18.8
- デフォルト: null
- タイプ: String
A comma-separated string of domain extensions that a proxy should not be used for.
strict-ssl
- デフォルト: true
- タイプ: Boolean
Whether or not to do SSL key validation when making requests to the registry via HTTPS.
See also the ca
option.
network-concurrency
- Default: 16
- タイプ: Number
Controls the maximum number of HTTP(S) requests to process simultaneously.
fetch-retries
- Default: 2
- タイプ: Number
How many times to retry if pnpm fails to fetch from the registry.
fetch-retry-factor
- Default: 10
- タイプ: Number
The exponential factor for retry backoff.
fetch-retry-mintimeout
- Default: 10000 (10 seconds)
- タイプ: Number
The minimum (base) timeout for retrying requests.
fetch-retry-maxtimeout
- デフォルト: 60000 (1 分)
- タイプ: Number
The maximum fallback timeout to ensure the retry factor does not make requests too long.
fetch-timeout
追加されたバージョン:v6.2.0
- デフォルト: 60000 (1 分)
- タイプ: Number
The maximum amount of time to wait for HTTP requests to complete.
Peer Dependency Settings
auto-install-peers
追加されたバージョン:v6.26.0
- デフォルト: false
- タイプ: Boolean
When true
, any missing non-optional peer dependencies are automatically installed.
strict-peer-dependencies
追加されたバージョン:v2.15.0
- デフォルト: false
- タイプ: Boolean
If this is enabled, commands will fail if there is a missing or invalid peer dependency in the tree.
CLI 設定
[no-]color
追加されたバージョン:v4.1.0
- デフォルト: auto
- Type: auto, always, never
Controls colors in the output.
- auto - output uses colors when the standard output is a terminal or TTY.
- always - ignore the difference between terminals and pipes. You’ll rarely want this; in most scenarios, if you want color codes in your redirected output, you can instead pass a
--color
flag to the pnpm command to force it to use color codes. The default setting is almost always what you’ll want. - never - turns off colors. This is the setting used by
--no-color
.
loglevel
Added in: v4.13.0
- Default: info
- Type: debug, info, warn, error
Any logs at or higher than the given level will be shown. You can instead pass --silent
to turn off all output logs.
use-beta-cli
追加されたバージョン:v3.6.0
- デフォルト: false
- タイプ: Boolean
Experimental option that enables beta features of the CLI. This means that you may get some changes to the CLI functionality that are breaking changes, or potentially bugs.
recursive-install
Added in: v5.4.0
- デフォルト: true
- タイプ: Boolean
If this is enabled, the primary behaviour of pnpm install
becomes that of pnpm install -r
, meaning the install is performed on all workspace or subdirectory packages.
Else, pnpm install
will exclusively build the package in the current directory.
engine-strict
- デフォルト: false
- タイプ: Boolean
If this is enabled, pnpm will not install any package that claims to not be compatible with the current Node version.
Regardless of this configuration, installation will always fail if a project (not a dependency) specifies an incompatible version in its engines
field.
npm-path
追加されたバージョン:v4.8.0
- タイプ: path
The location of the npm binary that pnpm uses for some actions, like publishing.
ビルド設定
child-concurrency
- Default: 5
- タイプ: Number
The maximum number of child processes to allocate simultaneously to build node_modules.
side-effects-cache
Added in: v1.31.0
- デフォルト: false
- タイプ: Boolean
Use and cache the results of (pre/post)install hooks.
side-effects-cache-readonly
Added in: v1.31.0
- デフォルト: false
- タイプ: Boolean
Only use the side effects cache if present, do not create it for new packages.
unsafe-perm
- Default: false IF running as root, ELSE true
- タイプ: Boolean
Set to true to enable UID/GID switching when running package scripts. If set explicitly to false, then installing as a non-root user will fail.
Node.js Settings
use-node-version
追加されたバージョン:v6.5.0
- Default: undefined
- Type: semver
Specifies which exact Node.js version should be used for the project's runtime. pnpm will automatically install the specified version of Node.js and use it for running pnpm run
commands or the pnpm node
command.
node-mirror:<releaseDir>
追加されたバージョン:v6.24.0
- Default:
https://nodejs.org/download/<releaseDir>/
- Type: URL
Sets the base URL for downloading Node.js. The <releaseDir>
portion of this setting can be any directory from https://nodejs.org/download: release
, rc
, nightly
, v8-canary
, etc.
Here is how pnpm may be configured to download Node.js from Node.js mirror in China:
node-mirror:release=https://npmmirror.com/mirrors/node/
node-mirror:rc=https://npmmirror.com/mirrors/node-rc/
node-mirror:nightly=https://npmmirror.com/mirrors/node-nightly/
その他の設定
use-running-store-server
Added in: v2.5.0
- デフォルト: false
- タイプ: Boolean
Only allows installation with a store server. If no store server is running, installation will fail.
save-prefix
- Default: '^'
- タイプ: String
Configure how versions of packages installed to a package.json
file get prefixed.
For example, if a package has version 1.2.3
, by default its version is set to ^1.2.3
which allows minor upgrades for that package, but after pnpm config set save-prefix='~'
it would be set to ~1.2.3
which only allows patch upgrades.
This setting is ignored when the added package has a range specified. For instance, pnpm add foo@2
will set the version of foo
in package.json
to 2
, regardless of the value of save-prefix
.
tag
- Default: latest
- タイプ: String
If you pnpm add
a package and you don't provide a specific version, then it will install the package at the version registered under the tag from this setting.
This also sets the tag that is added to the package@version
specified by the pnpm tag
command if no explicit tag is given.
global-dir
Added in: v4.2.0
- Default: <path to node>/pnpm-global
- タイプ: path
Specify a custom directory to store global packages.
global-bin-dir
追加されたバージョン:v6.15.0
Allows to set the target directory for the bin files of globally installed packages.
state-dir
追加されたバージョン:v6.10.0
- Default: $XDG_STATE_HOME/pnpm
- タイプ: path
The directory where pnpm creates the pnpm-state.json
file that is currently used only by the update checker.
cache-dir
追加されたバージョン:v6.10.0
- Default: $XDG_CACHE_HOME/pnpm
- タイプ: path
The location of the package metadata cache.
use-stderr
追加されたバージョン:v6.5.0
- デフォルト: false
- タイプ: Boolean
When true, all the output is written to stderr.
extend-node-path
追加されたバージョン:v6.16.0
- デフォルト: true
- タイプ: Boolean
When false
, the NODE_PATH
environment variable is not set in the command shims. It is recommended to set this setting to false
if you are getting the next error, when running commands:
The input line is too long. The syntax of the command is incorrect.
update-notifier
Added in: v6.29.0
- デフォルト: true
- タイプ: Boolean
Set to false
to suppress the update notification when using an older version of pnpm than the latest.