メインコンテンツまでスキップ
Version: Next

Package manifest (package.json, package.json5, package.yaml)

パッケージに関する情報を記述したファイルです。 タイトル、作者、依存パッケージなどのメタ情報を含んでいます。 This is a standard preserved across all major Node.js package managers, including pnpm.

In addition to the traditional package.json format, pnpm also supports package.json5 (via json5) and package.yaml (via js-yaml).

engines​

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

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

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

Unless the user has set the engine-strict config flag (see .npmrc), this field is advisory only and will only produce warnings when your package is installed as a dependency.

dependenciesMeta​

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

dependenciesMeta.*.injected​

If this is set to true for a dependency that is a local workspace package, that package will be installed by creating a hard linked copy in the virtual store (node_modules/.pnpm).

If this is set to false or not set, then the dependency will instead be installed by creating a node_modules symlink that points to the package's source directory in the workspace. This is the default, as it is faster and ensures that any modifications to the dependency will be immediately visible to its consumers.

For example, suppose the following package.json is a local workspace package:

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

The button dependency will normally be installed by creating a symlink in the node_modules directory of card, pointing to the development directory for button.

But what if button specifies react in its peerDependencies? If all projects in the monorepo use the same version of react, then there is no problem. But what if button is required by card that uses react@16 and form that uses react@17? Normally you'd have to choose a single version of react and specify it using devDependencies of button. Symlinking does not provide a way for the react peer dependency to be satisfied differently by different consumers such as card and form.

The injected field solves this problem by installing a hard linked copies of button in the virtual store. To accomplish this, the package.json of card could be configured as follows:

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

Whereas the package.json of form could be configured as follows:

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

With these changes, we say that button is an "injected dependency" of card and form. When button imports react, it will resolve to react@16 in the context of card, but resolve to react@17 in the context of form.

Because injected dependencies produce copies of their workspace source directory, these copies must be updated somehow whenever the code is modified; otherwise, the new state will not be reflected for consumers. When building multiple projects with a command such as pnpm --recursive run build, this update must occur after each injected package is rebuilt but before its consumers are rebuilt. For simple use cases, it can be accomplished by invoking pnpm install again, perhaps using a package.json lifecycle script such as "prepare": "pnpm run build" to rebuild that one project. Third party tools such as pnpm-sync and pnpm-sync-dependencies-meta-injected provide a more robust and efficient solution for updating injected dependencies, as well as watch mode support.

peerDependenciesMeta​

This field lists some extra information related to the dependencies listed in the peerDependencies field.

peerDependenciesMeta.*.optional​

If this is set to true, the selected peer dependency will be marked as optional by the package manager. Therefore, the consumer omitting it will no longer be reported as an error.

例:

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

Note that even though bar was not specified in peerDependencies, it is marked as optional. pnpm will therefore assume that any version of bar is fine. However, foo is optional, but only to the required version specification.

publishConfig​

It is possible to override some fields in the manifest before the package is packed. The following fields may be overridden:

To override a field, add the publish version of the field to publishConfig.

For instance, the following package.json:

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

Will be published as:

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

publishConfig.executableFiles​

By default, for portability reasons, no files except those listed in the bin field will be marked as executable in the resulting package archive. The executableFiles field lets you declare additional files that must have the executable flag (+x) set even if they aren't directly accessible through the bin field.

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

publishConfig.directory​

You also can use the field publishConfig.directory to customize the published subdirectory relative to the current package.json.

It is expected to have a modified version of the current package in the specified directory (usually using third party build tools).

次の例では"dist"フォルダーにpackage.jsonを配置しなければなりません。

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

publishConfig.linkDirectory​

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

When set to true, the project will be symlinked from the publishConfig.directory location during local development.

例:

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

pnpm.overrides​

このフィールドを指定すると、依存関係グラフにおける任意の依存関係を上書きするようpnpmに指示できるようになります。 This is useful for enforcing all your packages to use a single version of a dependency, backporting a fix, replacing a dependency with a fork, or removing an unused dependency.

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"
    }
  }
}

You may specify the package the overridden dependency belongs to by separating the package selector from the dependency selector with a ">", for example qar@1>zoo will only override the zoo dependency of qar@1, not for any other dependencies.

An override may be defined as a reference to a direct dependency's spec. This is achieved by prefixing the name of the dependency with a $:

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

The referenced package does not need to match the overridden one:

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

If you find that your use of a certain package doesn’t require one of its dependencies, you may use - to remove it. For example, if package foo@1.0.0 requires a large package named bar for a function that you don’t use, removing it could reduce install time:

{
  "pnpm": {
    "overrides": {
      "foo@1.0.0>bar": "-"
    }
  }
}

This feature is especially useful with optionalDependencies, where most optional packages can be safely skipped.

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
          }
        }
      }
    }
  }
}
ヒント

Together with Yarn, we maintain a database of packageExtensions to patch broken packages in the ecosystem. If you use packageExtensions, consider sending a PR upstream and contributing your extension to the @yarnpkg/extensions database.

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 is an array of package name patterns, any peer dependency matching the pattern will be resolved from any version, regardless of the range specified in peerDependencies. 例：

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

The above setting will mute any warnings about peer dependency version mismatches related to @babel/ packages or eslint.

pnpm.neverBuiltDependencies​

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

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

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

pnpm.onlyBuiltDependencies​

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

例:

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

pnpm.onlyBuiltDependenciesFile​

This configuration option allows users to specify a JSON file that lists the only packages permitted to run installation scripts during the pnpm install process. By using this, you can enhance security or ensure that only specific dependencies execute scripts during installation.

例:

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

The JSON file itself should contain an array of package names:

node_modules/@my-org/policy/onlyBuiltDependencies.json
[
  "fsevents"
]

pnpm.allowedDeprecatedVersions​

This setting allows muting deprecation warnings of specific packages.

例:

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

With the above configuration pnpm will not print deprecation warnings about any version of request and about v1 of express.

pnpm.patchedDependencies​

This field is added/updated automatically when you run pnpm patch-commit. It is a dictionary where the key should be the package name and exact version. The value should be a relative path to a patch file.

例:

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

pnpm.allowNonAppliedPatches​

When true, installation won't fail if some of the patches from the patchedDependencies field were not applied.

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

pnpm.updateConfig​

pnpm.updateConfig.ignoreDependencies​

Sometimes you can't update a dependency. For instance, the latest version of the dependency started to use ESM but your project is not yet in ESM. Annoyingly, such a package will be always printed out by the pnpm outdated command and updated, when running pnpm update --latest. However, you may list packages that you don't want to upgrade in the ignoreDependencies field:

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

Patterns are also supported, so you may ignore any packages from a scope: @babel/*.

pnpm.auditConfig​

pnpm.auditConfig.ignoreCves​

A list of CVE IDs that will be ignored by the pnpm audit command.

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

pnpm.auditConfig.ignoreGhsas​

A list of GHSA Codes that will be ignored by the pnpm audit command.

{
  "pnpm": {
    "auditConfig": {
      "ignoreGhsas": [
        "GHSA-42xw-2xvc-qx8m",
        "GHSA-4w2v-q235-vp99",
        "GHSA-cph5-m8f7-6c5x",
        "GHSA-vh95-rmgr-6w4m"
      ]
    }
  }
}

pnpm.requiredScripts​

Scripts listed in this array will be required in each project of the workspace. Otherwise, pnpm -r run <script name> will fail.

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

pnpm.supportedArchitectures​

You can specify architectures for which you'd like to install optional dependencies, even if they don't match the architecture of the system running the install.

For example, the following configuration tells to install optional dependencies for Windows x64:

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

Whereas this configuration will install optional dependencies for Windows, macOS, and the architecture of the system currently running the install. It includes artifacts for both x64 and arm64 CPUs:

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

Additionally, supportedArchitectures also supports specifying the libc of the system.

pnpm.ignoredOptionalDependencies​

If an optional dependency has its name included in this array, it will be skipped. 例:

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

pnpm.executionEnv.nodeVersion​

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.

例:

{
  "pnpm": {
    "executionEnv": {
      "nodeVersion": "16.16.0"
    }
  }
}

resolutions​

Functionally identical to pnpm.overrides, this field is intended to make it easier to migrate from Yarn.

resolutions and pnpm.overrides get merged before package resolution (with pnpm.overrides taking precedence), which can be useful when you're migrating from Yarn and need to tweak a few packages just for pnpm.