Saltar al contenido principal
Version: Próxima versión

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 campo engines.

A menos que el usuario haya establecido un valor para engine-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 de dependencies, opcionalDependenciesy devDependenceas.

dependenciesMeta.*.injected​

If this is set to true for a local dependency, the package will be hard linked to the modules directory, not symlinked.

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

But what if button has react in its peer dependencies? If all projects in the monorepo use the same version of react, then no problem. But what if button is required by card that uses react@16 and form with react@17? Without using inject, you'd have to choose a single version of react and install it as dev dependency of button. But using the injected field you can inject button to a package, and button will be installed with the react version of that package.

So this will be the package.json of card:

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

button will be hard linked into the dependencies of card, and react@16 will be symlinked to the dependencies of card/node_modules/button.

And this will be the package.json of form:

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

button will be hard linked into the dependencies of form, and react@17 will be symlinked to the dependencies of form/node_modules/button.

A diferencia de las dependencias normales, las inyectadas no están vinculadas a la carpeta de destino, por lo que no se actualizan automáticamente, por ejemplo, después de ejecutar el script de compilación. Para actualizar el contenido de la carpeta vinculada de forma permanente al estado más reciente de la carpeta del paquete de dependencia, vuelva a llamar a pnpm i.

Tenga en cuenta que el paquete button debe tener cualquier script de ciclo de vida que se ejecute en la instalación para que pnpm detecte los cambios y lo actualice. Por ejemplo, el paquete se puede reconstruir en la instalación: "prepare": "pnpm run build". Cualquier script funcionaría, incluso un comando simple no relacionado y sin efectos secundarios, como este: "prepare": "pnpm root".

peerDependenciesMeta​

Este campo enumera información adicional relacionada con las dependencias enumeradas en el campo peerDependencies.

peerDependenciesMeta.*.optional​

Si se establece en verdadero, el administrador de paquetes marcará la dependencia del par seleccionada como opcional. Por lo tanto, el consumidor que lo omite ya no será reportado como un error.

Por ejemplo:

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

Tenga en cuenta que aunque bar no fue especificado en peerDependencies, 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 a publishingConfig.

Por ejemplo, el siguiente package.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 campo executableFiles 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 campo publishConfig.directory para personalizar el subdirectorio publicado relativo al actual package.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 a package.json

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

publishConfig.linkDirectory​

  • Por defecto: true
  • Tipo: Boolean

Cuando se establece en true, el proyecto se vinculará desde la ubicación publishConfig.directory durante el desarrollo local.

Por ejemplo:

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

pnpm.overrides​

Este campo le permite indicar a pnpm que anule cualquier dependencia en el gráfico de dependencia. Esto es útil para obligar a todos sus paquetes a usar una sola versión de una dependencia, respaldar una corrección o reemplazar una dependencia con una bifurcación.

Tenga en cuenta que el campo de anulaciones solo se puede establecer en la raíz del proyecto.

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

Puede especificar el paquete al que pertenece la dependencia reemplazada por separando el selector de paquete del selector de dependencia con un ">", por ejemplo qar@1>zoo solo anulará la dependencia zoo de qar@1, no para ninguna otra dependencia.

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​

The packageExtensions fields offer a way to extend the existing package definitions with additional information. For example, if react-redux should have react-dom in its peerDependencies but it has not, it is possible to patch react-redux using packageExtensions:

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

The keys in packageExtensions 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 using packageExtensions: dependencies, optionalDependencies, peerDependencies, and peerDependenciesMeta.

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

Junto con Yarn, mantenemos una base de datos de packageExtensions para parchear paquetes rotos en el ecosistema. If you use packageExtensions, 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 needs react but react 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 need react@16 but you know that they work fine with react@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 allow react v17 to be installed.

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. Por ejemplo:

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

Ejemplo:

{
  "pnpm": {
    "onlyBuiltDependencies": ["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 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.

Ejemplo:

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