Passa al contenuto principale
Versione: 8.x

package.json

Il file manifesto di un pacchetto. Contiene tutti i metadati del pacchetto, comprese le dipendenze, il titolo, l'autore, eccetera. Questo è uno standard mantenuto in tutti i principali gestori di pacchetti Node.JS, incluso pnpm.

engines​

Puoi specificare la versione di Node e pnpm su cui funziona il tuo software:

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

Durante lo sviluppo locale, pnpm fallirà sempre con un messaggio di errore se la sua versione non corrisponde a quella specificata nel campo engine.

A meno che l'utente non abbia impostato il flag di configurazione engine-strict (vedi .npmrc), questo campo è solo consultivo e produrrà avvisi solo quando il tuo pacchetto è installato come dipendenza.

dependenciesMeta​

Ulteriori informazioni meta utilizzate per le dipendenze dichiarate all'interno di dependencies, optionalDependenciese devDependencies.

dependenciesMeta.*.injected​

Se questo è impostato su true per una dipendenza locale, il pacchetto sarà collegato alla cartella dei moduli, non collegato simbolicamente.

Ad esempio, il seguente package.json in uno spazio di lavoro creerà un collegamento simbolico a button nella cartella node_modules di card:

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

Ma cosa succede se button ha react nelle sue dipendenze peer? Se tutti i progetti nel monorepo utilizzano la stessa versione di react, nessun problema. Ma se button è richiesto da card che utilizza react@16 e form con react@17? Senza usare inject, dovresti scegliere una singola versione di react e installarla come dipendenza dev di button. Ma usando il campo injected puoi iniettare button in un pacchetto e button verrà installato con la versione di react di quel pacchetto.

Quindi questo sarà il package.json di card:

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

button sarà collegato fisicamente alle dipendenze di card e react@16 sarà collegato simbolicamente alle dipendenze di card/node_modules/button.

E questo sarà il package.json di form:

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

button sarà collegato fisicamente alle dipendenze di form e react@17 sarà collegato simbolicamente alle dipendenze di form/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, 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​

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.

Ad esempio:

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

In questo esempio la cartella "dist" deve contenere un package.json

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

publishConfig.linkDirectory​

  • Predefinito: true
  • Tipo: Booleano

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

Ad esempio:

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

pnpm.overrides​

Questo campo consente di indicare a pnpm di sovrascrivere qualsiasi dipendenza nel grafico delle dipendenze. Questo è utile per imporre a tutti i tuoi pacchetti di utilizzare una singola versione di una dipendenza, eseguire il backport di una correzione o sostituire una dipendenza con un fork.

Nota che il campo delle sostituzioni può essere impostato solo alla radice del progetto.

Un esempio del campo "pnpm"."overrides":

{
  "pnpm": {
    "overrides": {
      "foo": "^1.0.0",
      "quux": "npm:@myorg/quux@^1.0.0",
      "bar@^2.1.0": "3.0.0",
      "qar@1>zoo": "2"
    }
  }
}

Puoi specificare il pacchetto a cui appartiene la dipendenza sovrascritta separando il selettore del pacchetto dal selettore delle dipendenze con un ">", per esempio qar@1>zoo sovrascriverà solo la dipendenza zoo di qar@1, non per altre dipendenze.

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

pnpm.packageExtensions​

I campi packageExtensions offrono un modo per estendere le definizioni dei pacchetti esistenti con informazioni aggiuntive. Ad esempio, se react-redux dovrebbe avere react-dom nelle sue peerDependencies ma non ce l'ha, è possibile patchare react-redux usando packageExtensions:

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

Le chiavi in packageExtensions sono nomi di pacchetti o nomi di pacchetti e intervalli di semver, quindi è possibile correggere solo alcune versioni di un pacchetto:

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

I seguenti campi possono essere estesi utilizzando packageExtensions: dependencies, optionalDependencies, peerDependencies, e peerDependenciesMeta.

Un esempio più grande:

{
  "pnpm": {
    "packageExtensions": {
      "express@1": {
        "optionalDependencies": {
          "typescript": "2"
        }
      },
      "fork-ts-checker-webpack-plugin": {
        "dependencies": {
          "@babel/core": "1"
        },
        "peerDependencies": {
          "eslint": ">= 6"
        },
        "peerDependenciesMeta": {
          "eslint": {
            "optional": true
          }
        }
      }
    }
  }
}
tip

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 non stamperà avvisi sulle dipendenze peer mancanti da questo elenco.

Ad esempio, con la configurazione seguente, pnpm non stamperà avvisi se una dipendenza ha bisogno di react ma react non è installato:

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

Package name patterns may also be used:

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

pnpm.peerDependencyRules.allowedVersions​

Gli avvisi di dipendenza peer non soddisfatte non verranno stampati per le dipendenze peer dell'intervallo specificato.

Ad esempio, se hai alcune dipendenze che richiedono react@16 ma sai che funzionano bene con react@17, puoi utilizzare la seguente configurazione:

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

Questo dirà a pnpm che qualsiasi dipendenza che ha react nelle sue dipendenze peer dovrebbe consentire l'installazione di 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. For instance:

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

Esempio:

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

pnpm.allowedDeprecatedVersions​

This setting allows muting deprecation warnings of specific packages.

Esempio:

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

Esempio:

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

resolutions​

Same as pnpm.overrides. We read it for easier migration from Yarn.