package.json
O arquivo de manifesto de um pacote. Contém todos os metadados do pacote, incluindo dependências, título, autor e etc. Este é um padrão preservado por todos os principais gerenciadores de pacotes do Node.JS, incluindo o pnpm.
engines
Você pode especificar a versão do Node e do pnpm em que o seu software funciona:
{
"engines": {
"node": ">=10",
"pnpm": ">=3"
}
}
Durante o desenvolvimento local, o pnpm sempre falhará com uma mensagem de erro se sua versão não corresponder à especificada no campo engines.
A menos que o usuário tenha definido a flag de configuração engine-strict (veja .npmrc), esse campo é apenas consultivo e só produzirá avisos quando seu pacote for instalado como dependência.
dependenciesMeta
Informações meta adicionais usadas para dependências declaradas dentro de dependencies, optionalDependencies, e devDependencies.
dependenciesMeta.*.injected
If this is set to true for a local dependency, the package will be hard linked to the modules directory, not symlinked.
Por exemplo, o seguinte package.json num espaço de trabalho criará um link simbólico para button no diretório node_modules de card:
{
"name": "card",
"dependencies": {
"button": "workspace:1.0.0"
}
}
Mas e se button tiver react em suas dependências? Se todos os projetos no monorepo usarem as mesmas versões de react, então não há problema. Mas e se button for exigido por card que usa react@16 e form com react@17? Sem usar inject, você teria que escolher uma única versão de react e instalá-la como dependência de desenvolvimento de button. Mas usando o campo injected você pode injetar button em um pacote, e button será instalado com o react na versão desse pacote.
Então esse será o package.json de card:
{
"name": "card",
"dependencies": {
"button": "workspace:1.0.0",
"react": "16"
},
"dependenciesMeta": {
"button": {
"injected": true
}
}
}
button será vinculado fisicamente às dependências de card, e react@16 será linkado simbolicamente as dependências de card/node_modules/button.
E esse será o package.json de form:
{
"name": "form",
"dependencies": {
"button": "workspace:1.0.0",
"react": "17"
},
"dependenciesMeta": {
"button": {
"injected": true
}
}
}
button será linkado fisicamente às dependências de form, e react@17 será linkado simbolicamente as dependências de form/node_modules/button.
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.
Por exemplo:
{
"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 fields 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).
Nesse exemplo, a pasta
distdeve conter umpackage.json
{
"name": "foo",
"version": "1.0.0",
"publishConfig": {
"directory": "dist"
}
}
publishConfig.linkDirectory
Added in: v7.8.0
When set to true, the project will be symlinked from the publishConfig.directory location during local development.
Por exemplo:
{
"name": "foo",
"version": "1.0.0",
"publishConfig": {
"directory": "dist"
"linkDirectory": true
}
}
pnpm.overrides
This field allows you to instruct pnpm to override any dependency in the dependency graph. This is useful to enforce all your packages to use a single version of a dependency, backport a fix, or replace a dependency with a fork.
Note that the overrides field can only be set at the root of the project.
An example of the "pnpm"."overrides" field:
{
"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 overriden 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"
},
"overrides": {
"foo": "$foo"
}
}
The referenced package does not need to match the overridden one:
{
"dependencies": {
"foo": "^1.0.0"
},
"overrides": {
"bar": "$foo"
}
}
pnpm.packageExtensions
The packageExtensions fields offer a way to extend the existing package definitions with additional information. For example, if react-redux should have react-dom in its peerDependencies but it has not, it is possible to patch react-redux using packageExtensions:
{
"pnpm": {
"packageExtensions": {
"react-redux": {
"peerDependencies": {
"react-dom": "*"
}
}
}
}
}
The keys in packageExtensions are package names or package names and semver ranges, so it is possible to patch only some versions of a package:
{
"pnpm": {
"packageExtensions": {
"react-redux@1": {
"peerDependencies": {
"react-dom": "*"
}
}
}
}
}
The following fields may be extended using packageExtensions: dependencies, optionalDependencies, peerDependencies, and peerDependenciesMeta.
A bigger example:
{
"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 will not print warnings about missing peer dependencies from this list.
For instance, with the following configuration, pnpm will not print warnings if a dependency needs react but react is not installed:
{
"pnpm": {
"peerDependencyRules": {
"ignoreMissing": ["react"]
}
}
}
Package name patterns may also be used:
{
"pnpm": {
"peerDependencyRules": {
"ignoreMissing": ["@babel/*", "@eslint/*"]
}
}
}
pnpm.peerDependencyRules.allowedVersions
Unmet peer dependency warnings will not be printed for peer dependencies of the specified range.
For instance, if you have some dependencies that need react@16 but you know that they work fine with react@17, then you may use the following configuration:
{
"pnpm": {
"peerDependencyRules": {
"allowedVersions": {
"react": "17"
}
}
}
}
This will tell pnpm that any dependency that has react in its peer dependencies should allow react v17 to be installed.
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
Added in: v7.3.0
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. Por exemplo:
{
"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
This field allows to ignore the builds of specific dependencies. The "preinstall", "install", and "postinstall" scripts of the listed packages will not be executed during installation.
An example of the "pnpm"."neverBuiltDependencies" field:
{
"pnpm": {
"neverBuiltDependencies": ["fsevents", "level"]
}
}
pnpm.onlyBuiltDependencies
A list of package names that are allowed to be executed during installation. If this field exists, only the listed packages will be able to run install scripts.
Exemplo:
{
"pnpm": {
"onlyBuiltDependencies": ["fsevents"]
}
}
pnpm.allowedDeprecatedVersions
Added in: v7.2.0
This setting allows muting deprecation warnings of specific packages.
Exemplo:
{
"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
Adicionado em: v7.4.0
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.
Exemplo:
{
"pnpm": {
"patchedDependencies": {
"express@4.18.1": "patches/express@4.18.1.patch"
}
}
}
pnpm.allowNonAppliedPatches
Added in: v7.12.0
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
Added in: v7.13.0
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
Added in: v7.15.0
A list of CVE IDs that will be ignored by the pnpm audit command.
{
"pnpm": {
"auditConfig": {
"ignoreCves": [
"CVE-2022-36313"
]
}
}
}
pnpm.requiredScripts
Added in: v7.19.0
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"]
}
}
resolutions
Same as pnpm.overrides. We read it for easier migration from Yarn.