package.json

パッケージに関する情報を記述したファイルです。 タイトル、作者、依存パッケージなどのメタ情報を含んでいます。 このセクションで説明しているのは、pnpmを含む全ての主要なNode.jsのパッケージマネージャに共通する標準的な内容です。

engines

ソフトウェアが（パッケージが）動作するNode.jsとpnpmのバージョンを指定できます。

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

開発時に使用しているpnpmのバージョンがenginesフィールドに指定したバージョンと一致しない場合、常に失敗し、エラーメッセージを出力するでしょう。

ユーザがengine-strict設定フラグ (.npmrcを参照) を指定しなければ、このフィールドの役割は助言を与えるだけですし、あなたのパッケージを依存パッケージとしてインストールするときに警告を出力するだけでしょう。

dependenciesMeta

dependencies, optionalDependencies, devDependencies内で宣言された依存関係のために使用される追加のメタ情報です。

dependenciesMeta.*.injected

ローカルな依存パッケージについてこの設定項目をtrueに設定すると、モジュールディレクトリに対象のパッケージのハードリンク（シンボリックリンクではありません）を作成します。

例えば、ワークスペースに次のようなpackage.jsonがあるなら、cardディレクトリのnode_modulesに、buttonのシンボリックリンクを作成します。

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

ところで、buttonのピア依存関係にreactがあるとどうなるでしょうか。 モノリポに含まれる全てのプロジェクトが、同じバージョンのreactを使用しているなら何も問題はありません。 しかし、cardの要求するbuttonはreact@16を要求し、formがreact@17を要求しているとしたらどうなるでしょうか。 injectedフィールドを使用しないなら、任意のバージョンのreactを選択し、buttonのdev依存関係としてインストールしなければなりません。 injectedフィールドを使用すれば、パッケージにbuttonを注入しつつ、buttonをそれ自体が要求するバージョンのreactと共にインストールできるようになります。

従って、cardのpackage.jsonは次のようになります。

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

cardの依存パッケージとしてbuttonのハードリンクを作成します。そして、card/node_modules/buttonの依存パッケージとしてreact@16のシンボリックリンクを作成します。

こちらはformのpackage.jsonです。

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

formの依存パッケージとしてbuttonのハードリンクを作成します。そして、form/node_modules/buttonの依存パッケージとしてreact@17のシンボリックリンクを作成します。

In contrast to normal dependencies, injected ones are not symlinked to the destination folder, so they are not updated automatically, e.g. after running the build script. To update the hard linked folder contents to the latest state of the dependency package folder, call pnpm i again.

Note that the button package must have any lifecycle script that runs on install in order for pnpm to detect the changes and update it. For example, the package can be rebuilt on install: "prepare": "pnpm run build". Any script would work, even a simple unrelated command without side effects, like this: "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フィールドには、実行可能ファイルとしてのフラグ (+x) を設定するべきファイルを指定できます。binフィールドに指定したファイルから直接アクセスできないファイルも指定できます。

{
  "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"."overdides"フィールドは次のように設定します。

{
  "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と指定すると、zooの依存関係qar@1だけを上書きすることになり、他の依存関係には影響しません。

overrideの内容は、直接依存関係の仕様 (訳注: package. json の dependencies フィールドの記述のこと) への参照として定義することができます。 これは次のように、依存関係の名前を $ でプレフィックスすることで設定できます。

{
  "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フィールドで次のように追加（パッチ）できます。

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

packageExtensionsフィールドのキーはパッケージ名、あるいは、パッケージ名とsemver形式のバージョン範囲を組み合わせたものです。つまり、あるパッケージの特定のバージョンだけをパッチできるのです。

{
  "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 は、このリストで指定された peerDependencies が存在しなくても警告を出力しません。

たとえば、次の構成では、依存関係が react を要求しているが、 react がインストールされていない場合でも、pnpmは警告を出力しません。

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

Package name patterns may also be used:

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

pnpm.peerDependencyRules.allowedVersions

指定された範囲については peerDependencies が満たされていなくても警告が表示されなくなります。

例えば、react@16 を必要とする依存関係があったとして、それが react@17 でも正常に動くことをあなたが知っている場合、次のような構成を使用できます。

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

これは pnpm に、peerDependencies に react を持っているすべての依存関係について、 react v17 をインストールすることを許可するように指示します。

It is also possible to suppress the warnings only for peer dependencies of specific packages. For instance, with the following configuration react v17 will be only allowed when it is in the peer dependencies of the button v2 package or in the dependencies of any card package:

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

pnpm.peerDependencyRules.allowAny

allowAny はパッケージ名パターンの配列です。 パターンに一致するpeerDependencyは、 peerDependenciesで指定された範囲に関係なく、任意のバージョンで解決されます。 例：

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

上記の設定は、 @babel/ パッケージと eslintについてのpeerDependencyの不一致に関する警告をミュートします。

pnpm.neverBuiltDependencies

このフィールドに指定した依存関係のビルドは無視されます。 ここに列挙されたパッケージの「preinstall」、「install」、および「postinstall」スクリプトは、インストール中に実行されません。

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

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

pnpm.onlyBuiltDependencies

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

例:

{
  "pnpm": {
    "onlyBuiltDependencies": ["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

Scripts listed in this array will be required in each project of the workspace. ない場合は、 pnpm -r run <script name> が失敗します。

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

resolutions

pnpm.overrides と同じ。 Yarnからのマイグレーションを容易にするために、この設定を読みます。