package.json

パッケージのマニフェストファイルです。依存関係、タイトル、作成者など、パッケージのすべてのメタデータが含まれています。これは、pnpmを含む主要なNode.JSパッケージマネージャー全体で保持されている標準です。

engines

ソフトウェアが動作するNodeとpnpmのバージョンを指定できます。

{
    "engines": {
        "node": ">=10",
        "pnpm": ">=3"
    }
}

ローカル開発中、pnpmのバージョンがenginesフィールドで指定されたものと一致しない場合、pnpmは常にエラーメッセージで失敗します。

ユーザーがengine-strict設定フラグを設定していない限り（.npmrcを参照）、このフィールドは推奨のみであり、パッケージが依存関係としてインストールされた場合にのみ警告が表示されます。

dependenciesMeta

dependencies、optionalDependencies、およびdevDependencies内で宣言された依存関係に使用される追加のメタ情報。

dependenciesMeta.*.injected

ローカル依存関係に対してこれがtrueに設定されている場合、パッケージは仮想ストア（node_modules/.pnpm）にハードリンクされ、仮想ストアからモジュールディレクトリにシンボリックリンクされます。

ローカル依存関係に対してこれがfalseに設定されているか、設定されていない場合、パッケージはワークスペース内の場所からモジュールディレクトリに直接シンボリックリンクされます。

たとえば、ワークスペース内の次のpackage.jsonは、cardのnode_modulesディレクトリにbuttonへのシンボリックリンクを作成します。

{
  "name": "card",
  "dependencies": {
    "button": "workspace:1.0.0"
  }
}

しかし、buttonのピア依存関係にreactがある場合はどうでしょうか？モノレポ内のすべてのプロジェクトで同じバージョンのreactを使用している場合は問題ありません。しかし、buttonがreact@16を使用するcardと、react@17を使用するformによって必要とされている場合はどうでしょうか？injectを使用しない場合、reactの単一バージョンを選択し、buttonの開発依存関係としてインストールする必要があります。しかし、injectedフィールドを使用すると、buttonをパッケージに注入でき、buttonはそのパッケージのreactバージョンでインストールされます。

したがって、これはcardのpackage.jsonになります。

{
  "name": "card",
  "dependencies": {
    "button": "workspace:1.0.0",
    "react": "16"
  },
  "dependenciesMeta": {
    "button": {
      "injected": true
    }
  }
}

buttonはcardの依存関係にハードリンクされ、react@16はcard/node_modules/buttonの依存関係にシンボリックリンクされます。

そして、これはformのpackage.jsonになります。

{
  "name": "form",
  "dependencies": {
    "button": "workspace:1.0.0",
    "react": "17"
  },
  "dependenciesMeta": {
    "button": {
      "injected": true
    }
  }
}

buttonはformの依存関係にハードリンクされ、react@17はform/node_modules/buttonの依存関係にシンボリックリンクされます。

通常の依存関係とは対照的に、注入された依存関係は宛先フォルダにシンボリックリンクされないため、たとえばビルドスクリプトの実行後に自動的に更新されません。ハードリンクされたフォルダの内容を依存関係パッケージフォルダの最新の状態に更新するには、もう一度pnpm iを呼び出してください。

pnpmが変更を検出し、更新するためには、buttonパッケージはインストール時に実行されるライフサイクルスクリプトを持っている必要があることに注意してください。たとえば、パッケージはインストール時に再構築できます。"prepare": "pnpm run build"。どのようなスクリプトでも機能します。たとえば、次のように副作用のない簡単な無関係なコマンドでも機能します。"prepare": "pnpm root"。

peerDependenciesMeta

このフィールドは、peerDependenciesフィールドにリストされている依存関係に関連する追加情報を示します。

peerDependenciesMeta.*.optional

これがtrueに設定されている場合、選択されたピア依存関係はパッケージマネージャーによってオプションとしてマークされます。したがって、コンシューマーがそれを省略しても、エラーとして報告されなくなります。

たとえば

{
    "peerDependencies": {
        "foo": "1"
    },
    "peerDependenciesMeta": {
        "foo": {
            "optional": true
        },
        "bar": {
            "optional": true
        }
    }
}

barはpeerDependenciesで指定されていませんが、オプションとしてマークされていることに注意してください。したがって、pnpmは、barのどのバージョンでも問題ないと想定します。ただし、fooはオプションですが、必要なバージョン仕様のみにオプションです。

publishConfig

パッケージをパックする前に、マニフェスト内のいくつかのフィールドを上書きできます。次のフィールドを上書きできます。

• bin
• main
• exports
• typesまたはtypings
• module
• browser
• esnext
• es2015
• unpkg
• umd:main
• typesVersions
• cpu
• os

フィールドを上書きするには、フィールドの公開バージョンをpublishConfigに追加します。

たとえば、次のpackage.json

{
    "name": "foo",
    "version": "1.0.0",
    "main": "src/index.ts",
    "publishConfig": {
        "main": "lib/index.js",
        "typings": "lib/index.d.ts"
    }
}

次のように公開されます。

{
    "name": "foo",
    "version": "1.0.0",
    "main": "lib/index.js",
    "typings": "lib/index.d.ts"
}

publishConfig.executableFiles

デフォルトでは、移植性の理由から、binフィールドにリストされているファイルを除き、結果のパッケージアーカイブで実行可能としてマークされるファイルはありません。executableFilesフィールドを使用すると、binフィールドから直接アクセスできない場合でも、実行可能フラグ（+x）を設定する必要がある追加のフィールドを宣言できます。

{
  "publishConfig": {
    "executableFiles": [
      "./dist/shim.js"
    ]
  }
}

publishConfig.directory

フィールドpublishConfig.directoryを使用して、現在のpackage.jsonを基準とした公開されたサブディレクトリをカスタマイズすることもできます。

指定されたディレクトリに、現在のパッケージの変更されたバージョンがあることが予想されます（通常はサードパーティのビルドツールを使用）。

この例では、"dist"フォルダにpackage.jsonが含まれている必要があります。

{
  "name": "foo",
  "version": "1.0.0",
  "publishConfig": {
    "directory": "dist"
  }
}

publishConfig.linkDirectory

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

trueに設定すると、ローカル開発中にプロジェクトがpublishConfig.directoryの場所からシンボリックリンクされます。

たとえば

{
  "name": "foo",
  "version": "1.0.0",
  "publishConfig": {
    "directory": "dist"
    "linkDirectory": true
  }
}

pnpm.overrides

このフィールドを使用すると、pnpmに依存関係グラフ内の依存関係を上書きするように指示できます。これは、すべてのパッケージで単一バージョンの依存関係を使用するように強制したり、修正をバックポートしたり、依存関係をフォークに置き換えたりする場合に役立ちます。

overridesフィールドは、プロジェクトのルートでのみ設定できることに注意してください。

"pnpm"."overrides"フィールドの例

{
  "pnpm": {
    "overrides": {
      "foo": "^1.0.0",
      "quux": "npm:@myorg/quux@^1.0.0",
      "bar@^2.1.0": "3.0.0",
      "qar@1>zoo": "2"
    }
  }
}

パッケージセレクターを依存関係セレクターから>で区切ることで、上書きされた依存関係が属するパッケージを指定できます。たとえば、qar@1>zooは、qar@1のzoo依存関係のみを上書きし、他の依存関係には上書きしません。

上書きは、直接依存関係の仕様への参照として定義できます。これは、依存関係の名前の先頭に$を付けることで実現できます。

{
  "dependencies": {
    "foo": "^1.0.0"
  },
  "pnpm": {
    "overrides": {
      "foo": "$foo"
    }
  }
}

参照されるパッケージは、上書きされたパッケージと一致する必要はありません。

{
  "dependencies": {
    "foo": "^1.0.0"
  },
  "pnpm": {
    "overrides": {
      "bar": "$foo"
    }
  }
}

pnpm.packageExtensions

packageExtensionsフィールドは、既存のパッケージ定義を追加情報で拡張する方法を提供します。たとえば、react-reduxがpeerDependenciesにreact-domを持っている必要があるが、持っていない場合、packageExtensionsを使用してreact-reduxにパッチを適用できます。

{
  "pnpm": {
    "packageExtensions": {
      "react-redux": {
        "peerDependencies": {
          "react-dom": "*"
        }
      }
    }
  }
}

packageExtensionsのキーはパッケージ名またはパッケージ名とセムバー範囲であるため、パッケージの一部のバージョンのみにパッチを適用できます。

{
  "pnpm": {
    "packageExtensions": {
      "react-redux@1": {
        "peerDependencies": {
          "react-dom": "*"
        }
      }
    }
  }
}

packageExtensionsを使用して拡張できるフィールドは、dependencies、optionalDependencies、peerDependencies、およびpeerDependenciesMetaです。

より大きな例

{
  "pnpm": {
    "packageExtensions": {
      "express@1": {
        "optionalDependencies": {
          "typescript": "2"
        }
      },
      "fork-ts-checker-webpack-plugin": {
        "dependencies": {
          "@babel/core": "1"
        },
        "peerDependencies": {
          "eslint": ">= 6"
        },
        "peerDependenciesMeta": {
          "eslint": {
            "optional": true
          }
        }
      }
    }
  }
}

ヒント

Yarn と同様に、私たちはエコシステム内の壊れたパッケージを修正するために packageExtensions のデータベースを管理しています。packageExtensions を使用している場合は、アップストリームに PR を送信し、@yarnpkg/extensions データベースに拡張機能を寄稿することを検討してください。

pnpm.peerDependencyRules

pnpm.peerDependencyRules.ignoreMissing

pnpm は、このリストにある不足しているピア依存関係に関する警告を表示しません。

例えば、次の設定では、pnpm は依存関係が react を必要とするが、react がインストールされていない場合でも警告を表示しません。

{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": ["react"]
    }
  }
}

パッケージ名のパターンも使用できます。

{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": ["@babel/*", "@eslint/*"]
    }
  }
}

pnpm.peerDependencyRules.allowedVersions

指定された範囲のピア依存関係については、満たされていないピア依存関係の警告は表示されません。

例えば、react@16 を必要とする依存関係がいくつかあるが、react@17 でも問題なく動作することがわかっている場合は、次の設定を使用できます。

{
  "pnpm": {
    "peerDependencyRules": {
      "allowedVersions": {
        "react": "17"
      }
    }
  }
}

これにより、pnpm は、ピア依存関係に react を持つ依存関係は、react v17 のインストールを許可する必要があると認識します。

特定のパッケージのピア依存関係についてのみ警告を抑制することも可能です。例えば、次の設定では、react v17 は、button v2 パッケージのピア依存関係にある場合、または任意の card パッケージの依存関係にある場合にのみ許可されます。

{
  "pnpm": {
    "peerDependencyRules": {
      "allowedVersions": {
        "button@2>react": "17",
        "card>react": "17"
      }
    }
  }
}

pnpm.peerDependencyRules.allowAny

allowAny はパッケージ名のパターンの配列であり、パターンに一致するピア依存関係は、peerDependencies で指定された範囲に関係なく、任意のバージョンから解決されます。例えば

{
  "pnpm": {
    "peerDependencyRules": {
      "allowAny": ["@babel/*", "eslint"]
    }
  }
}

上記の設定では、@babel/ パッケージまたは eslint に関連するピア依存関係のバージョンの不一致に関する警告はすべて抑制されます。

pnpm.neverBuiltDependencies

このフィールドを使用すると、特定の依存関係のビルドを無視できます。リストされたパッケージの "preinstall"、"install"、および "postinstall" スクリプトは、インストール中に実行されません。

"pnpm"."neverBuiltDependencies" フィールドの例

{
  "pnpm": {
    "neverBuiltDependencies": ["fsevents", "level"]
  }
}

pnpm.onlyBuiltDependencies

インストール中に実行を許可するパッケージ名のリスト。このフィールドが存在する場合、リストされたパッケージのみがインストールスクリプトを実行できます。

例

{
  "pnpm": {
    "onlyBuiltDependencies": ["fsevents"]
  }
}

pnpm.onlyBuiltDependenciesFile

この設定オプションを使用すると、pnpm インストールプロセス中にインストールスクリプトの実行を許可するパッケージのみをリストした JSON ファイルを指定できます。これを使用すると、セキュリティを強化したり、インストール中に特定の依存関係のみがスクリプトを実行するようにしたりできます。

例

{
  "dependencies": {
    "@my-org/policy": "1.0.0"
  },
  "pnpm": {
    "onlyBuiltDependenciesFile": "node_modules/@my-org/policy/onlyBuiltDependencies.json"
  }
}

JSON ファイル自体には、パッケージ名の配列が含まれている必要があります。

node_modules/@my-org/policy/onlyBuiltDependencies.json

[
  "fsevents"
]

pnpm.allowedDeprecatedVersions

この設定により、特定のパッケージの非推奨警告を抑制できます。

例

{
  "pnpm": {
    "allowedDeprecatedVersions": {
      "express": "1",
      "request": "*"
    }
  }
}

上記の設定では、pnpm は request の任意のバージョンと express の v1 についての非推奨警告を表示しません。

pnpm.patchedDependencies

このフィールドは、pnpm patch-commit を実行すると自動的に追加/更新されます。キーはパッケージ名と正確なバージョンである必要のあるディクショナリです。値はパッチファイルへの相対パスである必要があります。

例

{
  "pnpm": {
    "patchedDependencies": {
      "express@4.18.1": "patches/express@4.18.1.patch"
    }
  }
}

pnpm.allowNonAppliedPatches

true の場合、patchedDependencies フィールドのパッチの一部が適用されなかった場合でも、インストールは失敗しません。

{
  "pnpm": {
    "patchedDependencies": {
      "express@4.18.1": "patches/express@4.18.1.patch"
    },
    "allowNonAppliedPatches": true
}

pnpm.updateConfig

pnpm.updateConfig.ignoreDependencies

依存関係を更新できない場合があります。例えば、依存関係の最新バージョンが ESM を使用し始めたが、プロジェクトはまだ ESM に対応していない場合などです。厄介なことに、このようなパッケージは、pnpm outdated コマンドによって常に表示され、pnpm update --latest を実行すると更新されます。ただし、ignoreDependencies フィールドにアップグレードしたくないパッケージをリストできます。

{
  "pnpm": {
    "updateConfig": {
      "ignoreDependencies": ["load-json-file"]
    }
  }
}

パターンもサポートされているため、スコープからのパッケージを無視できます: @babel/*。

pnpm.auditConfig

pnpm.auditConfig.ignoreCves

pnpm audit コマンドで無視される CVE ID のリスト。

{
  "pnpm": {
    "auditConfig": {
      "ignoreCves": [
        "CVE-2022-36313"
      ]
    }
  }
}

pnpm.requiredScripts

この配列にリストされたスクリプトは、ワークスペースの各プロジェクトで必須になります。そうでない場合、pnpm -r run <スクリプト名> は失敗します。

{
  "pnpm": {
    "requiredScripts": ["build"]
  }
}

pnpm.supportedArchitectures

インストールを実行しているシステムのアーキテクチャと一致しない場合でも、オプションの依存関係をインストールしたいアーキテクチャを指定できます。

例えば、次の構成は Windows x64 用のオプションの依存関係をインストールするように指示します。

{
  "pnpm": {
    "supportedArchitectures": {
      "os": ["win32"],
      "cpu": ["x64"]
    }
  }
}

一方、この構成は Windows、macOS、および現在インストールを実行しているシステムのアーキテクチャ用のオプションの依存関係をインストールします。x64 と arm64 の両方の CPU のアーティファクトが含まれています。

{
  "pnpm": {
    "supportedArchitectures": {
      "os": ["win32", "darwin", "current"],
      "cpu": ["x64", "arm64"]
    }
  }
}

さらに、supportedArchitectures はシステムの libc の指定もサポートしています。

pnpm.ignoredOptionalDependencies

オプションの依存関係の名前がこの配列に含まれている場合、スキップされます。例えば

{
  "pnpm": {
    "ignoredOptionalDependencies": ["fsevents", "@esbuild/*"]
  }
}

resolutions

pnpm.overrides と機能的に同じで、このフィールドは Yarn からの移行を容易にするためのものです。

resolutions と pnpm.overrides は、パッケージの解決前にマージされます (pnpm.overrides が優先されます)。これは、Yarn から移行していて、pnpm 用にいくつかのパッケージを調整する必要がある場合に役立ちます。