メインコンテンツまでスキップ
Version: 6.x

.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 と同じです。 この設定を使用する合理的な理由は以下のとおりです:
    1. 使っているツールはシンボリックリンクではうまく機能しない。 React Native のプロジェクトは、おそらく、巻き上げられた(hoisted) node_modulesを使用する場合にのみ機能します。
    2. プロジェクトがサーバーレスホスティングにデプロイされる。 一部のサーバーレスサービスの提供者 (AWS Lambdaなど) はシンボリックリンクをサポートしていません。 この問題を解決する代替策は、デプロイ前にアプリケーションをバンドルすることです。
    3. "bundledDependencies" としてパッケージを公開したい場合
    4. --preserve-symlinks フラグを指定して Node.js を実行している場合。
  • pnp - node_modules なし。 Plug'n'Play は Yarn で使用されている Node のための革新的な方式です。 pnp をリンカーとして使う場合には、 symlink を false に設定することが推奨されます。

追加されたバージョン：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​

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.