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

.npmrc

pnpm は、コマンド行、環境変数、および .npmrc ファイルから設定を取得します。

pnpm config コマンドを使用して、ユーザーおよびグローバルの .npmrc ファイルの内容を更新および編集することができます。

関連する4つのファイルは次のとおりです。

  • プロジェクトごとの設定ファイル(/path/to/my/project/.npmrc)
  • ワークスペースごとの設定ファイル (pnpm-workspace.yaml ファイルが含まれているディレクトリー)
  • ユーザーごとの設定ファイル(~/.npmrc)
  • グローバルな設定ファイル (/etc/npmrc)

.npmrc ファイルはすべて key = value という INI形式 のパラメータのリストです。

依存の巻き上げ設定

hoist

  • デフォルト: true
  • タイプ: boolean

trueの場合、すべての依存関係は node_modules/.pnpm に巻き上げられます。 これにより、リストされていない依存に、 node_modules 内のすべてのパッケージからアクセスできるようになります。

hoist-pattern

  • デフォルト: ['*']
  • タイプ: string[]

どのパッケージを node_modules/.pnpm に巻き上げるかを指定します。 デフォルトでは、全てのパッケージが巻き上げられます。しかし、非常に多くの依存を持つ、扱いに困るパッケージについてわかっている場合には、このオプションにより、それらを省いて巻き上げするように指定することができます。 (推奨)

例:

hoist-pattern[]=*eslint*
hoist-pattern[]=*babel*

public-hoist-pattern

  • デフォルト: ['*eslint*', '*prettier*']
  • タイプ: string[]

hoist-pattern が仮想ストア内の隠し node_modules ディレクトリに依存を巻き上げるのに対し、public-hoist-pattern はパターンにマッチする依存をルートの node_modules ディレクトリへと巻き上げます。 ルートの node_modules ディレクトリに巻き上げると、アプリケーションのコードは、たとえ依存解決方法を不適切なものに変更されていたとしても、それらの巻き上げられた非常に大量の依存へアクセスできることになります。

この設定は、いくつかのプラグイン機構を持った、依存を適切に解決しない、扱いに困るツールを扱う際に役立ちます。

例:

public-hoist-pattern[]=*plugin*

注意: shamefully-hoisttrue に設定するのと public-hoist-pattern* に設定するのは同じ効果があります。

shamefully-hoist

  • デフォルト: false
  • タイプ: Boolean

デフォルトでは、pnpm はそれなりに厳格な node_modules を作成します。依存パッケージは定義されない依存へのアクセスをすることが可能なまま、node_modules の外からはアクセスできないようになっています。 この方式では、ほとんどのパッケージがそのエコシステムの中で問題なく機能します。 ただし、いくつかのツールが、依存がルートの node_modules に 巻き上げられている場合にのみ機能する場合には、この設定を true にすることでそのように巻き上げることができます。

node_modules に関する設定

store-dir

  • デフォルト:
    • $XDG_DATA_HOME 環境変数が設定されている場合、 $XDG_DATA_HOME/pnpm/store
    • Windows: ~/AppData/Local/pnpm/store
    • macOS: ~/Library/pnpm/store
    • Linux: ~/.local/share/pnpm/store
  • タイプ: path

パッケージをディスク上のどこに保存するか指定します。

ストアはインストールを行うのと同じディスク状にある必要があります。つまり、ディスクごとに一つのストアを持つことになります。 現在のディスクにホームディレクトリがある場合は、その中にストアが作成されます。 もしディスク状にホームディレクトリがない場合は、ストアはファイルシステムのルートに作られます。 例えば、/mnt にマウントされたファイルシステム状でインストールを行なった場合、ストアは /mnt/.pnpm-store に作られます。 Windows システムでも同様です。

異なるディスク状のストアを指定することも可能ですが、その場合 pnpm はハードリンクをせずにパッケージをコピーします。これは、ハードリンクは同一のファイルシステム状でのみ可能なためです。

modules-dir

  • デフォルト: node_modules
  • タイプ: path

node_modules の代わりに依存をインストールする場所を指定します。

node-linker

  • デフォルト: 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 をリンカーとして使う場合には、 symlinkfalse に設定することが推奨されます。
  • デフォルト: true
  • タイプ: Boolean

symlinkfalse に設定すると、pnpm は仮想ストアのディレクトリをシンボリックリンクを用いずに構成します。 この設定は node-linker=pnp と組み合わせる際に役立ちます。

enable-modules-dir

  • デフォルト: true
  • タイプ: Boolean

false を設定すると、pnpm は node_modules ディレクトリにファイルを一切書き込みません。 この設定はユーザスペース上のファイルシステム (FUSE) に node_modules ディレクトリがマウントされている場合に有用です。 node_module ディレクトリを FUSE でマウントするのに使える実験的な CLIツールがあります: @pnpm/mount-modules

virtual-store-dir

  • デフォルト: node_modules/.pnpm
  • タイプ: path

ストアにリンクするディレクトリを指定する。 すべてのプロジェクトの直接および間接的な依存はこのディレクトリへリンクされる。

Windows 上でのパスの長さ上限に関する問題を解決するのに役立ちます。 何らかの非常に長いパスを持つ依存がある場合、ドライブ上のルートに仮想ストアを置くことが可能です。 (例: C:\my-project-store)

もしくは、仮想ストアを .pnpm にして .gitignore に追記することもできます。 依存のディレクトリをひとつ上にすることで、スタックトレース上での表示がすっきりします。

注意: 仮想ストアは複数のプロジェクト間で共有することはできません。 すべてのプロジェクトはそれぞれ固有の仮想ストアを持つ必要があります。 (ルートが共通のワークスペース内のプロジェクトは除く)

package-import-method

  • デフォルト: auto
  • Type: auto, hardlink, copy, clone, clone-or-copy

パッケージがストアからインポートされる方法を制御します。

  • auto - ストアからパッケージをクローンしようとします。 クローンがサポートされていない場合、ストアからパッケージをハードリンクします。 クローンもリンクもできない場合は、コピーします。
  • hardlink - ストアからパッケージをハードリンクします。
  • clone-or-copy - try to clone packages from the store. If cloning is not supported then fall back to copying
  • copy - ストアからパッケージをハードリンクします。
  • clone - ストアからパッケージをクローンします。 (別名: copy-on-write、 参照リンク)

modules-cache-max-age

  • デフォルト: 10080 (単位は分、7 日)
  • タイプ: number

孤立したパッケージを node_module ディレクトリから削除するまでの時間を分単位で指定します。 pnpm はパッケージのキャッシュを node_module ディレクトリに保持します。 これにより、ブランチを切り替えたり、依存のダウングレードを行う際のインストールのスピードを速くします。

ロックファイル設定

lockfile

  • デフォルト: true
  • タイプ: Boolean

false に設定すると、pnpm は pnpm-lock.yaml を読み込んだり、書き込んだりしません。

prefer-frozen-lockfile

  • デフォルト: true
  • タイプ: 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 トークンを指定します。 例:

//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 

環境変数を使用することもできます。 例:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

<URL>:tokenHelper

tokenHelper とは、アクセストークンを出力する実行ファイルです。 これは、authToken が一定値ではなく定期的に更新されるような場合に使用します。 スクリプトやその他のツールが、既存のリフレッシュトークンを使って新しいアクセストークンを取得できるようになります。

helper へのパスの設定は、引数なしの絶対パスである必要があります。 安全性を高めるため、この値はユーザーの .npmrc にのみ設定することが許されています。 そうしないと、プロジェクトがプロジェクトのローカルの .npmrc に値を置いて、任意の実行ファイルを実行することができてしまいます。

デフォルトのレジストリに tokenHelper を設定します:

tokenHelper=/home/ivan/token-generator

指定されたレジストリに tokenHelper を設定します:

//registry.corp.com:tokenHelper=/home/ivan/token-generator

<URL>:always-auth

  • デフォルト: false
  • タイプ: Boolean

特定のレジストリにアクセスする際に、pnpm からのすべてのリクエスト (GET リクエストを含む) に対して認証を必須にするよう強制します。 例:

@babel:registry=https://gitlab.com/api/v4/packages/npm/
//gitlab.com/api/v4/packages/npm/:always-auth=true

registry=https://registry.npmjs.org/
//registry.npmjs.org/:always-auth=true

リクエスト設定

ca

  • デフォルト: npm の CA 証明書
  • タイプ: String, Array or null

レジストリへのSSL接続をするのに信用する署名用CA証明書を指定します。 値は PEM フォーマット (Base64エンコードされた X.509 (.CER)) で指定します。 例:

ca="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

null に設定すると、既知の登録者のみを許可できます。もしくは、特定の CA 証明書の署名のみを信頼するように設定できます。

証明書の配列を指定することで、複数の信頼する CA を指定することもできます。

ca[]="..."
ca[]="..."

strict-ssl も参照してください。

cafile

  • デフォルト: null
  • タイプ: path

ひとつ、もしくは複数のCA 署名用証明書を持つファイルへのパスを指定します。 ca 設定と同様ですが、複数の CA に関する情報を CLI 経由ではなくファイルに保持しておくことができます。

cert

  • デフォルト: null
  • タイプ: String

レジストリにアクセスするときに渡すクライアント証明書。 値は PEM フォーマット (Base64エンコードされた X.509 (.CER)) で指定します。 例:

cert="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

これは証明書ファイルへのパスではありません (certfile オプションはありません)。

key

  • デフォルト: null
  • タイプ: String

レジストリにアクセスするときに渡すクライアントキー。 値は PEM フォーマット (Base64エンコードされた X.509 (.CER)) で指定します。 例:

key="-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----"

キーファイルへのパスではありません (keyfile オプションはありません)。

この設定には機密情報が含まれています。 リポジトリにコミットされたローカルの .npmrc ファイルに書き込まないでください。

git-shallow-hosts

  • デフォルト: ['github.com', 'gist.github.com', 'gitlab.com', 'bitbucket.com', 'bitbucket.org']
  • タイプ: string[]

Git リポジトリである依存関係を取得する際、この設定でホストがリストアップされている場合、pnpm は浅いクローンを用いて、すべての履歴ではなく、必要なコミットのみを取得するようにします。

https-proxy

  • デフォルト: null
  • タイプ: url

送信する HTTPS リクエストに使用するプロキシ。 HTTPS_PROXYhttps_proxyHTTP_PROXY 、または http_proxy 環境変数が設定されている場合は、その値が代わりに使用されます。

local-address

  • デフォルト: undefined
  • タイプ: IP Address

npm レジストリへの接続を行うときに使用するローカルインターフェイスのIPアドレス。

proxy

  • デフォルト: null
  • タイプ: url

送信する HTTP リクエストに使用するプロキシ。 HTTP_PROXY または http_proxy 環境変数が設定されている場合、プロキシー設定は、内部のリクエストライブラリーに受け渡されます。

maxsockets

  • デフォルト: network-concurrency x 3
  • タイプ: Number

origin (protocol/host/port の組み合わせ) ごとに使用する最大接続数です。

noproxy

  • デフォルト: null
  • タイプ: String

プロキシーを使わない TLD をコンマ区切りの文字列で指定します。

strict-ssl

  • デフォルト: true
  • タイプ: Boolean

HTTPS 経由でレジストリにリクエストを送る際にSSL鍵の検証を行うかどうかを指定します。

ca オプションも参照してください。

network-concurrency

  • デフォルト: 16
  • タイプ: Number

同時に処理する HTTP(S) のリクエストの最大数を制御します。

fetch-retries

  • デフォルト: 2
  • タイプ: Number

pnpm がレジストリからの取得に失敗した際に何回リトライするかを指定する。

fetch-retry-factor

  • デフォルト: 10
  • タイプ: Number

指数関数バックオフに使用する係数を指定する。

fetch-retry-mintimeout

  • デフォルト: 10000 (10 秒)
  • タイプ: Number

リクエストをリトライする際の最小(最初) のタイムアウト。

fetch-retry-maxtimeout

  • デフォルト: 60000 (1 分)
  • タイプ: Number

リクエストが長時間リトライされないということがないようにするためのフォールバック用の最大タイムアウト。

fetch-timeout

  • デフォルト: 60000 (1 分)
  • タイプ: Number

HTTP リクエストが完了するまでに待つ最大の時間。

Peer Dependency Settings

auto-install-peers

  • デフォルト: false
  • タイプ: Boolean

true の場合、不足している Optional ではないピアの依存関係が自動的にインストールされます。

strict-peer-dependencies

  • デフォルト: true
  • タイプ: Boolean

このオプションを有効にすると、コマンドを実行した際に欠落していたり無効な peer dependency が存在すると失敗します。

CLI 設定

[no-]color

  • デフォルト: auto
  • タイプ: auto, always, never

出力時の色を制御する。

  • auto - 標準出力がターミナルかTTYの場合は、出力に色を使用します。
  • always - ターミナルとパイプの違いを無視します。 これが必要になることはめったにありません。ほとんどの場合では、リダイレクトされた出力にカラーコードを含めたい場合、pnpm コマンドに --colorフラグを指定し、 pnpmコマンドにカラーコードを使用することを強制させることで代用できます。 ほとんどの場合デフォルトの設定があなたの求めているものでしょう。
  • never - 色を使いません。 これは --no-color で使用される設定です。

loglevel

  • デフォルト: info
  • タイプ: debug, info, warn, error

設定したレベル以上のログのみが出力されます。 --silent を渡して、すべての出力ログをオフにすることもできます。

use-beta-cli

  • デフォルト: false
  • タイプ: Boolean

CLI のベータ機能を有効にする実験的なオプションです。 これは、CLI の挙動に破壊的変更を起こしたり、潜在的なバグを発生させる可能性があることを意味します。

recursive-install

  • デフォルト: true
  • タイプ: Boolean

このオプションを有効にすると、 pnpm install の主要な挙動は pnpm install -r と同様になります。つまり、インストールはワークスペース全体、もしくはサブディレクトリ全体で行われます。

それ以外の場合は、 pnpm install は現在のディレクトリ内のパッケージのみを単独でビルドします。

engine-strict

  • デフォルト: false
  • タイプ: Boolean

このオプションを有効にすると、pnpm は現在の Node.js のバージョンと互換性がないパッケージをインストールしません。

このオプションに関わらず、プロジェクト側 (依存側ではない) が互換性のないバージョン指定をengines フィールドで指定している場合は、常にインストールは失敗します。

npm-path

  • タイプ: path

publish などのいくつかの処理で pnpm が使用する、npm 実行ファイルの場所を指定します。

ビルド設定

child-concurrency

  • デフォルト: 5
  • タイプ: Number

node_modules をビルドする際に同時に実行する子プロセスの最大数。

side-effects-cache

  • デフォルト: true
  • タイプ: Boolean

インストール (前/後) のフックの結果をキャッシュするかどうか。

side-effects-cache-readonly

  • デフォルト: false
  • タイプ: Boolean

副作用のあるキャッシュが存在する場合にのみ使用されます。有効にすると、新しいパッケージに対してはそのようなキャッシュを作成しません。

unsafe-perm

  • デフォルト: root で実行している場合は false 、それ以外の場合は true
  • タイプ: Boolean

このオプションを true にすると、パッケージスクリプト実行時の UID/GID の切り替えを有効にします。 明示的に false に設定されている場合は、ルート以外のユーザでインストールしようとした場合は失敗します。

Node.js Settings

use-node-version

  • デフォルト: undefined
  • タイプ: semver

プロジェクトのランタイムとして使う Node.js の正確なバージョンを指定します。 pnpm は自動で指定されたバージョンの Node.js をインストールして pnpm runpnpm node を実行する際に使用します。

node-version

  • デフォルト: node -vによって戻される値 (vプレフィックスなし)
  • タイプ: semver

パッケージの engines の設定を確認するときに使用する Node.js バージョン。

If you want to prevent contributors of your project from adding new incompatible dependencies, use node-version and engine-strict in a .npmrc file at the root of the project:

node-version=12.22.0
engine-strict=true

This way, even if someone is using Node.js v16, they will not be able to install a new dependency that doesn't support Node.js v12.22.0.

node-mirror:<releaseDir>

  • デフォルト: https://nodejs.org/download/<releaseDir>/
  • タイプ: URL

Node.jsをダウンロードするためのベースURLを設定します。 この設定の <releaseDir> の部分は https://nodejs.org/download から任意のディレクトリを指定できます: release, rc, nightly, v8-canary, などです。

中国のNode.jsミラーからNode.jsをダウンロードするためのpnpmの設定方法:

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/

Workspace Settings

  • デフォルト: true
  • タイプ: true, false, deep

このオプションを有効にすると、ローカルで利用可能なパッケージはレジストリからダウンロードせずに node_modules へとリンクされます。 これはモノレポで非常に役立ちます。 ローカルパッケージも subependencies にリンクさせる必要がある場合は、deep の設定を使用することができます。

それ以外の場合には、依存はレジストリからダウンロードされます。 ただし、ワークスペースのパッケージは workspace: プロトコルを範囲指定することでリンクすることができます。

prefer-workspace-packages

  • デフォルト: false
  • タイプ: Boolean

このオプションを有効にすると、レジストリに新しいバージョンのパッケージがある場合でも、ワークスペース内のローカルにあるパッケージが優先されます。

この設定は、ワークスペースのオプションで save-workspace-protocol が使用されていない場合にのみ役立ちます。

shared-workspace-lockfile

  • デフォルト: true
  • タイプ: Boolean

このオプションが有効になっている場合、pnpm はワークスペースのルートの pnpm-lock.yaml のみを作成します。 これにより、すべてのワークスペースの依存がワークスペースのルートの node_modules この一箇所に集められます。(そして各パッケージの node_modules ディレクトリへとシンボリックリンクが作成されます。)

このオプションの利点:

  • 各依存の一箇所への設置
  • より高速なモノレポでのインストール
  • 一箇所にすべて記述され、より少ないコードレビュー時の変更
note

たとえルートの node_modules にすべての依存がハードリンクされていても、各ワークスペースパッケージはその package.json に定義された依存にしかアクセスできません。これにより、 pnpm の厳密性は保持されます。 これは前述のシンボリックリンクによるものです。

save-workspace-protocol

  • デフォルト: true
  • Type: true, false, rolling

This setting controls how dependencies that are linked from the workspace are added to package.json.

If foo@1.0.0 is in the workspace and you run pnpm add foo in another project of the workspace, below is how foo will be added to the dependencies field. The save-prefix setting also influences how the spec is created.

save-workspace-protocolsave-prefixspec
false''1.0.0
false'~'~1.0.0
false'^'^1.0.0
true''workspace:1.0.0
true'~'workspace:~1.0.0
true'^'workspace:^1.0.0
rolling''workspace:*
rolling'~'workspace:~
rolling'^'workspace:^

include-workspace-root

Added in: v7.4.0

  • デフォルト: false
  • タイプ: Boolean

When executing commands recursively in a workspace, execute them on the root workspace project as well.

その他の設定

use-running-store-server

  • デフォルト: false
  • タイプ: Boolean

ストアサーバーでのインストールのみを許可します。 ストアサーバーが起動していない場合は、インストールは失敗します。

save-prefix

  • デフォルト: '^'
  • タイプ: String

パッケージのバージョンが package.json にインストールされる際に、何を接頭辞に付けるか指定します。

例えば、あるパッケージのバージョンが 1.2.3 である場合、デフォルトでは保存されるバージョン指定は ^1.2.3 となり、マイナーアップグレードを許容します。pnpm config set save-prefix='~' を設定すると、~1.2.3 として保存され、パッチアップグレードのみを許容します。

この設定はパッケージがバージョン範囲指定とともに追加された際には無視されます。 例えば、 pnpm add foo@2package.json 内の foo のバージョンを 2 に設定し、save-prefix の設定値を考慮しません。

tag

  • デフォルト: latest
  • タイプ: String

パッケージを pnpm add でバージョン指定なしで追加した場合、この設定のタグで登録されているバージョンをインストールします。

この設定は、pnpm tag コマンドに明示的にタグを指定しなかった場合にも、 package@version に対するタグとして使われます。

global-dir

  • デフォルト:
    • $XDG_DATA_HOME 環境変数が設定されている場合、 $XDG_DATA_HOME/pnpm/global
    • Windows の場合: ~/AppData/Local/pnpm/global
    • macOSの場合: ~/Library/pnpm/global
    • Linuxの場合: ~/.local/share/pnpm/global
  • タイプ: path

グローバルパッケージを格納するディレクトリを指定します。

global-bin-dir

グローバルにインストールされたパッケージのbinファイルの保存先ディレクトリを設定することができます。

state-dir

  • デフォルト:
    • $XDG_STATE_HOME 環境変数が設定されている場合、 $XDG_STATE_HOME/pnpm
    • Windows の場合: ~/AppData/Local/pnpm-state
    • macOSの場合: ~/.pnpm-state
    • Linuxの場合: ~/.local/state/pnpm
  • タイプ: path

pnpm が pnpm-state.json ファイルを作成するディレクトリを指定します。これは現時点ではアップデートのチェックにのみ使用されています。

cache-dir

  • デフォルト:
    • $XDG_CACHE_HOME 環境変数が設定されている場合、 $XDG_CACHE_HOME/pnpm
    • Windows の場合: ~/AppData/Local/pnpm-cache
    • macOSの場合: ~/Library/Caches/pnpm
    • Linuxの場合: ~/.cache/pnpm
  • タイプ: path

パッケージメタデータのキャッシュを置く場所を指定します。

use-stderr

  • デフォルト: false
  • タイプ: Boolean

true に設定すると、すべての出力は標準エラーに書き込まれます。

update-notifier

  • デフォルト: true
  • タイプ: Boolean

falseに設定すると、最新版より古いバージョンのpnpmを使用している場合に、更新通知を行わないようにします。