package.json
El fichero manifest de un paquete. Contient toda la metadata del paquete, incluyendo dependencies, titulo, autor, etcétera. Este es un estandar a través de todos gestores de paquetes de Node.JS, incluído pnpm.
engines
Puedes específicar la versión de Node y pnpm con la que tu aplicación trabaja:
{
"engines":{
"node":">=10",
"pnpm":">=3"
}
}
Durante el desarrollo local, pnpm siempre fallará con un mensaje de error si su versión no coincide con la especificada en el campoengines
.
A menos que el usuario haya establecido un valor paraengine-strict
(ver.npmrc), este campo es solo indicativo y solo generará advertencias cuando su paquete esté instalado como una dependencia.
dependenciesMeta
Metainformación adicional utilizada para dependencias declaradas dentro dedependencies
,opcionalDependencies
ydevDependenceas
.
dependenciesMeta.*.injected
If this is set totrue
for a local dependency, the package will be hard linked to the virtual store (node_modules/.pnpm
) and symlinked from the virtual store to the modules directory.
If this is set tofalse
or not set for a local dependency, the package will be symlinked directly from its location in the workspace to the module directory.
For instance, the followingpackage.json
in a workspace will create a symlink tobutton
in thenode_modules
directory ofcard
:
{
"name":"card",
"dependencies":{
"button":"workspace:1.0.0"
}
}
But what ifbutton
hasreact
in its peer dependencies? If all projects in the monorepo use the same version ofreact
, then no problem. But what ifbutton
is required bycard
that usesreact@16
andform
withreact@17
? Without usinginject
, you'd have to choose a single version ofreact
and install it as dev dependency ofbutton
. But using theinjected
field you can injectbutton
to a package, andbutton
will be installed with thereact
version of that package.
So this will be thepackage.json
ofcard
:
{
"name":"card",
"dependencies":{
"button":"workspace:1.0.0",
"react":"16"
},
"dependenciesMeta":{
"button":{
"injected":true
}
}
}
button
will be hard linked into the dependencies ofcard
, andreact@16
will be symlinked to the dependencies ofcard/node_modules/button
.
And this will be thepackage.json
ofform
:
{
"name":"form",
"dependencies":{
"button":"workspace:1.0.0",
"react":"17"
},
"dependenciesMeta":{
"button":{
"injected":true
}
}
}
button
will be hard linked into the dependencies ofform
, andreact@17
will be symlinked to the dependencies ofform/node_modules/button
.
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, callpnpm i
again.
Note that thebutton
package must have any lifecycle script that runs on install in order forpnpm
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
This field lists some extra information related to the dependencies listed in thepeerDependencies
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 ejemplo:
{
"peerDependencies":{
"foo":"1"
},
"peerDependenciesMeta":{
"foo":{
"optional":true
},
"bar":{
"optional":true
}
}
}
Tenga en cuenta que aunquebar
no fue especificado enpeerDependencies
, está marcada como opcional. pnpm por lo tanto supondrá que cualquier versión de bar está bien. Sin embargo,foo
es opcional, pero solo para la especificación de versión requerida.
publishConfig
Es posible anular algunos campos en el manifiesto antes de que el paquete esté. Los siguientes campos pueden ser anulados:
Para anular un campo, agregue la versión de publicación del campo apublishingConfig
.
Por ejemplo, el siguientepackage.json
:
{
"name":"foo",
"version":"1.0.0",
"main":"src/index.ts",
"publishConfig":{
"main":"lib/index.js",
"typings":"lib/index.d.ts"
}
}
Se publicará como:
{
"name":"foo",
"version":"1.0.0",
"main":"lib/index.js",
"typings":"lib/index.d.ts"
}
publishConfig.executableFiles
De manera predeterminada, por razones de portabilidad, ningún archivo, excepto los que se enumeran en el campo bin, se marcará como ejecutable en el archivo del paquete resultante. El campoexecutableFiles
le permite declarar campos adicionales que deben tener el indicador ejecutable (+x) establecido incluso si no se puede acceder directamente a ellos a través del campo bin.
{
"publishConfig":{
"executableFiles":[
"./dist/shim.js"
]
}
}
publishConfig.directory
También puede utilizar el campopublishConfig.directory
para personalizar el subdirectorio publicado relativo al actualpackage.json
.
Se espera que tenga una versión modificada del paquete actual en el directorio especificado (usualmente usando herramientas de compilación de terceros).
In this example the
"dist"
folder must contain apackage.json
{
"name":"foo",
"version":"1.0.0",
"publishConfig":{
"directory":"dist"
}
}
publishConfig.linkDirectory
- Por defecto:true
- Tipo:Boolean
Cuando se establece entrue
, el proyecto se vinculará desde la ubicaciónpublishConfig.directory
durante el desarrollo local.
Por ejemplo:
{
"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 exampleqar@1>zoo
will only override thezoo
dependency ofqar@1
, not for any other dependencies.
Una anulación se puede definir como una referencia a la especificación de una dependencia directa. Esto se logra anteponiendo el nombre de la dependencia con un$
:
{
"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"
}
}
}
pnpm.packageExtensions
ThepackageExtensions
fields offer a way to extend the existing package definitions with additional information. For example, ifreact-redux
should havereact-dom
in itspeerDependencies
but it has not, it is possible to patchreact-redux
usingpackageExtensions
:
{
"pnpm":{
"packageExtensions":{
"react-redux":{
"peerDependencies":{
"react-dom":"*"
}
}
}
}
}
The keys inpackageExtensions
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 usingpackageExtensions
:dependencies
,optionalDependencies
,peerDependencies
, andpeerDependenciesMeta
.
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
}
}
}
}
}
}
Junto con Yarn, mantenemos una base de datos depackageExtensions
para parchear paquetes rotos en el ecosistema. If you usepackageExtensions
, 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 needsreact
butreact
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 needreact@16
but you know that they work fine withreact@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 allowreact
v17 to be installed.
It is also possible to suppress the warnings only for peer dependencies of specific packages. For instance, with the following configurationreact
v17 will be only allowed when it is in the peer dependencies of thebutton
v2 package or in the dependencies of anycard
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 inpeerDependencies
. Por ejemplo:
{
"pnpm":{
"peerDependencyRules":{
"allowAny":["@babel/*","eslint"]
}
}
}
The above setting will mute any warnings about peer dependency version mismatches related to@babel/
packages oreslint
.
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.
Ejemplo:
{
"pnpm":{
"onlyBuiltDependencies":["fsevents"]
}
}
pnpm.onlyBuiltDependenciesFile
Added in: v8.9.0
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.
Ejemplo:
{
"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:
[
"fsevents"
]
pnpm.allowedDeprecatedVersions
This setting allows muting deprecation warnings of specific packages.
Ejemplo:
{
"pnpm":{
"allowedDeprecatedVersions":{
"express":"1",
"request":"*"
}
}
}
With the above configuration pnpm will not print deprecation warnings about any version ofrequest
and about v1 ofexpress
.
pnpm.patchedDependencies
This field is added/updated automatically when you runpnpm 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.
Ejemplo:
{
"pnpm":{
"patchedDependencies":{
"express@4.18.1":"patches/express@4.18.1.patch"
}
}
}
pnpm.allowNonAppliedPatches
Whentrue
, installation won't fail if some of the patches from thepatchedDependencies
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 thepnpm outdated
command and updated, when runningpnpm update --latest
. However, you may list packages that you don't want to upgrade in theignoreDependencies
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 thepnpm audit
command.
{
"pnpm":{
"auditConfig":{
"ignoreCves":[
"CVE-2022-36313"
]
}
}
}
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
Added in: v8.10.0
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 thelibc
of the system.
resolutions
Functionally identical topnpm.overrides
, this field is intended to make it easier to migrate from Yarn.
resolutions
andpnpm.overrides
get merged before package resolution (withpnpm.overrides
taking precedence), which can be useful when you're migrating from Yarn and need to tweak a few packages just for pnpm.
- engines
- dependenciesMeta
- peerDependenciesMeta
- publishConfig
- pnpm.overrides
- pnpm.packageExtensions
- pnpm.peerDependencyRules
- pnpm.neverBuiltDependencies
- pnpm.onlyBuiltDependencies
- pnpm.onlyBuiltDependenciesFile
- pnpm.allowedDeprecatedVersions
- pnpm.patchedDependencies
- pnpm.allowNonAppliedPatches
- pnpm.updateConfig
- pnpm.auditConfig
- pnpm.requiredScripts
- pnpm.supportedArchitectures
- resolutions