package.json
Il file manifesto di un pacchetto. Contiene tutti i metadati del pacchetto, comprese le dipendenze, il titolo, l'autore, eccetera. This is a standard preserved across all major Node.js package managers, including 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
If this is set to true 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 to false or not set, then the dependency will instead be installed by creating a node_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 following package.json is a local workspace package:
{
"name": "card",
"dependencies": {
"button": "workspace:1.0.0"
}
}
The button dependency will normally be installed by creating a symlink in the node_modules directory of card, pointing to the development directory for button.
But what if button specifies react in its peerDependencies? If all projects in the monorepo use the same version of react, then there is no problem. But what if button is required by card that uses react@16 and form that uses react@17? Normally you'd have to choose a single version of react and specify it using devDependencies of button. Symlinking does not provide a way for the react peer dependency to be satisfied differently by different consumers such as card and form.
The injected field solves this problem by installing a hard linked copies of button in the virtual store. To accomplish this, the package.json of card could be configured as follows:
{
"name": "card",
"dependencies": {
"button": "workspace:1.0.0",
"react": "16"
},
"dependenciesMeta": {
"button": {
"injected": true
}
}
}
Whereas the package.json of form could be configured as follows:
{
"name": "form",
"dependencies": {
"button": "workspace:1.0.0",
"react": "17"
},
"dependenciesMeta": {
"button": {
"injected": true
}
}
}
With these changes, we say that button is an "injected dependency" of card and form. When button imports react, it will resolve to react@16 in the context of card, but resolve to react@17 in the context of form.
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 as pnpm --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 invoking pnpm install again, perhaps using a package.json lifecycle script such as "prepare": "pnpm run build" to rebuild that one project. Third party tools such as pnpm-sync and pnpm-sync-dependencies-meta-injected provide a more robust and efficient solution for updating injected dependencies, as well as watch mode support.
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. The executableFiles 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
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
- Predefinito: true
- Tipo: Booleano
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. 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.
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"
}
}
}
You may specify the package the overridden 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.
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"
},
"pnpm": {
"overrides": {
"foo": "$foo"
}
}
}
Il pacchetto di riferimento non deve necessariamente corrispondere a quello sovrascritto:
{
"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 package foo@1.0.0 requires a large package named bar 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 with optionalDependencies, where most optional packages can be safely skipped.
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
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
Questo campo consente di ignorare le build di dipendenze specifiche. Gli script "preinstall", "install" e "postinstall" dei pacchetti elencati non verranno eseguiti durante l'installazione.
Un esempio del campo "pnpm"."neverBuiltDependencies":
{
"pnpm": {
"neverBuiltDependencies": ["fsevents", "level"]
}
}
pnpm.onlyBuiltDependencies
Un elenco di nomi di pacchetti che possono essere eseguiti durante l'installazione. Se questo campo esiste, solo i pacchetti elencati potranno eseguire gli script di installazione.
Esempio:
{
"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.
Esempio:
{
"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
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
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
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
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
Un elenco di ID CVE che verranno ignorati dal comando pnpm audit.
{
"pnpm": {
"auditConfig": {
"ignoreCves": [
"CVE-2022-36313"
]
}
}
}
pnpm.auditConfig.ignoreGhsas
A list of GHSA Codes that will be ignored by the pnpm 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. Altrimenti, pnpm -r run <script name> fallirà.
{
"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 the libc of the system.
pnpm.ignoredOptionalDependencies
If an optional dependency has its name included in this array, it will be skipped. Ad esempio:
{
"pnpm": {
"ignoredOptionalDependencies": ["fsevents", "@esbuild/*"]
}
}
pnpm.executionEnv.nodeVersion
Specifica quale versione esatta di Node.js deve essere utilizzata per il runtime del progetto. pnpm installerà automaticamente la versione specificata di Node.js e la utilizzerà per eseguire i comandi pnpm run o per il comando pnpm node.
Ad esempio:
{
"pnpm": {
"executionEnv": {
"nodeVersion": "16.16.0"
}
}
}
resolutions
Functionally identical to pnpm.overrides, this field is intended to make it easier to migrate from Yarn.
resolutions and pnpm.overrides get merged before package resolution (with pnpm.overrides taking precedence), which can be useful when you're migrating from Yarn and need to tweak a few packages just for pnpm.