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.
For instance, the following package.json in a workspace will create a symlink to button in the node_modules directory of 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.
peerDependenciesMeta
Questo campo elenca alcune informazioni aggiuntive relative alle dipendenze elencate nel campo peerDependencies.
peerDependenciesMeta.*.optional
Se questo è impostato su true, la dipendenza peer selezionata verrà contrassegnata come opzionale dal gestore pacchetti. Pertanto, il consumatore che lo omette non sarà più segnalato come errore.
Ad esempio:
{
"peerDependencies": {
"foo": "1"
},
"peerDependenciesMeta": {
"foo": {
"optional": true
},
"bar": {
"optional": true
}
}
}
Si noti che anche se bar non è stato specificato in peerDependencies, è contrassegnato come facoltativo. pnpm quindi presumerà che qualsiasi versione di bar vada bene. Tuttavia, pippo è facoltativo, ma solo per la specifica della versione richiesta.
publishConfig
È possibile sovrascrivere alcuni campi nel manifesto prima che il pacchetto sia impacchettato. I seguenti campi possono essere sovrascritti:
Per sovrascrivere un campo, aggiungi la versione pubblica del campo in publishConfig.
Ad esempio, il seguente package.json:
{
"name": "foo",
"version": "1.0.0",
"main": "src/index.ts",
"publishConfig": {
"main": "lib/index.js",
"typings": "lib/index.d.ts"
}
}
Verrà pubblicato come:
{
"name": "foo",
"version": "1.0.0",
"main": "lib/index.js",
"typings": "lib/index.d.ts"
}
publishConfig.executableFiles
Per impostazione predefinita, per motivi di portabilità, nessun file tranne quelli elencati nel campo bin verrà contrassegnato come eseguibile nell'archivio del pacchetto risultante. Il campo executableFiles consente di dichiarare campi aggiuntivi che devono avere il flag dell'eseguibile (+x) impostato anche se non sono direttamente accessibili tramite il campo bin.
{
"publishConfig": {
"executableFiles": [
"./dist/shim.js"
]
}
}
publishConfig.directory
Puoi anche utilizzare il campo publishConfig.directory per personalizzare la sottocartella pubblicata relativa all'attuale package.json.
Dovrebbe avere una versione modificata del pacchetto corrente nella cartella specificata (di solito utilizzando strumenti di compilazione di terze parti).
In questo esempio la cartella
"dist"deve contenere unpackage.json
{
"name": "foo",
"version": "1.0.0",
"publishConfig": {
"directory": "dist"
}
}
publishConfig.linkDirectory
Aggiunto nella versione: v7.8.0
Quando è impostato su true, il progetto verrà collegato in modo simbolico dalla posizione publishConfig.directory durante lo sviluppo locale.
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.
Un override può essere definito come un riferimento alla specifica di una dipendenza diretta. Ciò si ottiene anteponendo il nome della dipendenza a $:
{
"dependencies": {
"foo": "^1.0.0"
},
"overrides": {
"foo": "$foo"
}
}
Il pacchetto di riferimento non deve necessariamente corrispondere a quello sovrascritto:
{
"dependencies": {
"foo": "^1.0.0"
},
"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
}
}
}
}
}
}
Insieme a Yarn, gestiamo un database di packageExtensions per correggere i pacchetti danneggiati nell'ecosistema. Se utilizzi packageExtensions, prendi in considerazione l'invio di un PR a monte e il contributo della tua estensione al database @yarnpkg/extensions.
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"]
}
}
}
Possono essere utilizzati anche i modelli di nome del pacchetto:
{
"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
Added in: v7.3.0
allowAny è una lista di modelli di nomi di pacchetto, qualsiasi dipendenza peer che corrisponde al modello verrà risolta da qualsiasi versione, indipendentemente dall'intervallo specificato in peerDependencies. Ad esempio:
{
"pnpm": {
"peerDependencyRules": {
"allowAny": ["@babel/*", "eslint"]
}
}
}
L'impostazione di cui sopra disattiva tutti gli avvisi sulle mancate corrispondenze delle versioni delle dipendenze peer relative a pacchetti @babel/ o 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
Added in: v7.2.0
Questa impostazione consente di disattivare gli avvisi di deprecazione di pacchetti specifici.
Esempio:
{
"pnpm": {
"allowedDeprecatedVersions": {
"express": "1",
"request": "*"
}
}
}
Con la configurazione pnpm di cui sopra non verranno stampati avvisi di deprecazione su qualsiasi versione di request e circa v1 di express.
pnpm.patchedDependencies
Aggiunto in: v7.4.0
Questo campo viene aggiunto/aggiornato automaticamente quando si esegue pnpm patch-commit. È un dizionario in cui la chiave dovrebbe essere il nome del pacchetto e la versione esatta. Il valore dovrebbe essere un percorso relativo a un file di patch.
Esempio:
{
"pnpm": {
"patchedDependencies": {
"express@4.18.1": "patches/express@4.18.1.patch"
}
}
}
pnpm.allowNonAppliedPatches
Added in: v7.12.0
Quando true, l'installazione non fallirà se alcune delle patch del campo patchedDependencies non sono state applicate.
{
"pnpm": {
"patchedDependencies": {
"express@4.18.1": "patches/express@4.18.1.patch"
}
"allowNonAppliedPatches": true
}
pnpm.updateConfig
pnpm.updateConfig.ignoreDependencies
Added in: v7.13.0
A volte non è possibile aggiornare una dipendenza. Ad esempio, l'ultima versione della dipendenza ha iniziato a utilizzare ESM ma il tuo progetto non è ancora in ESM. Fastidiosamente, un tale pacchetto verrà sempre stampato dal comando pnpm obsoleto e aggiornato, durante l'esecuzione di pnpm update --latest. Tuttavia, puoi elencare i pacchetti che non desideri aggiornare nel campo ignoreDependencies:
{
"pnpm": {
"updateConfig": {
"ignoreDependencies": ["load-json-file"]
}
}
}
Sono supportati anche i modelli, quindi puoi ignorare qualsiasi pacchetto da un ambito: @babel/*.
pnpm.auditConfig
pnpm.auditConfig.ignoreCves
Aggiunto nella versione: v7.15.0
Un elenco di ID CVE che verranno ignorati dal comando pnpm audit.
{
"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. Altrimenti, pnpm -r run <script name> fallirà.
{
"pnpm": {
"requiredScripts": ["build"]
}
}
resolutions
Same as pnpm.overrides. We read it for easier migration from Yarn.