The manifest file of a package. It contains all the package's metadata, including dependencies, title, author, et cetera. This is a standard preserved across all major Node.js package managers, including pnpm.

In addition to the traditionalpackage.json format, pnpm also supportspackage.json5 (viajson5) andpackage.yaml (viajs-yaml).

engines​

You can specify the version of Node and pnpm that your software works on:

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

During local development, pnpm will always fail with an error message if its version does not match the one specified in theengines field.

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

dependenciesMeta​

Additional meta information used for dependencies declared insidedependencies,optionalDependencies, anddevDependencies.

dependenciesMeta.*.injected​

If this is set totrue 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 tofalse or not set, then the dependency will instead be installed by creating anode_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 followingpackage.json is a local workspace package:

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

Thebutton dependency will normally be installed by creating a symlink in thenode_modules directory ofcard, pointing to the development directory forbutton.

But what ifbutton specifiesreact in itspeerDependencies? If all projects in the monorepo use the same version ofreact, then there is no problem. But what ifbutton is required bycard that usesreact@16 andform that usesreact@17? Normally you'd have to choose a single version ofreact and specify it usingdevDependencies ofbutton. Symlinking does not provide a way for thereact peer dependency to be satisfied differently by different consumers such ascard andform.

Theinjected field solves this problem by installing a hard linked copies ofbutton in the virtual store. To accomplish this, thepackage.json ofcard could be configured as follows:

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

Whereas thepackage.json ofform could be configured as follows:

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

With these changes, we say thatbutton is an "injected dependency" ofcard andform. Whenbutton importsreact, it will resolve toreact@16 in the context ofcard, but resolve toreact@17 in the context ofform.

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 aspnpm --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 invokingpnpm install again, perhaps using apackage.json lifecycle script such as"prepare": "pnpm run build" to rebuild that one project. Third party tools such aspnpm-sync andpnpm-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 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.

Misalnya:

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

Note that even thoughbar was not specified inpeerDependencies, 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:

• bin
• main
• exports
• types ortypings
• module
• browser
• esnext
• es2015
• unpkg
• umd:main
• typesVersions
• cpu
• os

To override a field, add the publish version of the field topublishConfig.

For instance, the followingpackage.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. TheexecutableFiles 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 fieldpublishConfig.directory to customize the published subdirectory relative to the currentpackage.json.

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

In this example the"dist" folder must contain apackage.json

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

publishConfig.linkDirectory​

• Default:true
• Type:Boolean

When set totrue, the project will be symlinked from thepublishConfig.directory location during local development.

Misalnya:

{
"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 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.

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 overridden 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.

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 packagefoo@1.0.0 requires a large package namedbar 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 withoptionalDependencies, where most optional packages can be safely skipped.

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

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. Contohnya:

{
"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. Only packages listed in this array will be able to run install scripts. IfonlyBuiltDependenciesFile andneverBuiltDependencies are not set, this configuration option will default to blocking all install scripts.

Contoh:

{
"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.

Contoh:

{
"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.ignoredBuiltDependencies​

Added in: v10.1.0

A list of package names that should not be built during installation.

Contoh:

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

pnpm.allowedDeprecatedVersions​

This setting allows muting deprecation warnings of specific packages.

Contoh:

{
"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.

Contoh:

{
"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.auditConfig.ignoreGhsas​

A list of GHSA Codes that will be ignored by thepnpm 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 thelibc of the system.

pnpm.ignoredOptionalDependencies​

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

{
"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 runningpnpm run commands or thepnpm node command.

Misalnya:

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

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.