package.json
O arquivo de manifesto de um pacote. Contém todos os metadados do pacote, incluindo dependências, título, autor e etc. Este é um padrão preservado por todos os principais gerenciadores de pacotes do Node.JS, incluindo o pnpm.
engines
Você pode especificar a versão do Node e do pnpm em que o seu software funciona:
{
"engines": {
"node": ">=10",
"pnpm": ">=3"
}
}
Durante o desenvolvimento local, o pnpm sempre falhará com uma mensagem de erro se sua versão não corresponder à especificada no campo engines.
A menos que o usuário tenha definido a flag de configuração engine-strict (veja .npmrc), esse campo é apenas consultivo e só produzirá avisos quando seu pacote for instalado como dependência.
dependenciesMeta
dependenciesMeta.*.injected
Se for definido como true para uma dependência local, o pacote terá um link físico para o diretório de módulos, e não um link simbólico.
Por exemplo, o seguinte package.json num espaço de trabalho criará um link simbólico para button no diretório node_modules de card:
{
"name": "card",
"dependencies": {
"button": "workspace:1.0.0"
}
}
Mas e se button tiver react em suas dependências? Se todos os projetos no monorepo usarem as mesmas versões de react, então não há problema. Mas e se button for exigido por card que usa react@16 e form com react@17? Sem usar inject, você teria que escolher uma única versão de react e instalá-la como dependência de desenvolvimento de button. Mas usando o campo injected você pode injetar button em um pacote, e button será instalado com a versão react desse pacote.
Então esse será o package.json de card:
{
"name": "card",
"dependencies": {
"button": "workspace:1.0.0",
"react": "16"
},
"dependenciesMeta": {
"button": {
"injected": true
}
}
}
button será vinculado às dependências de card, e react@16 será associado as dependências de card/node_modules/button.
E esse será o package.json de card:
{
"name": "form",
"dependencies": {
"button": "workspace:1.0.0",
"react": "17"
},
"dependenciesMeta": {
"button": {
"injected": true
}
}
}
button será vinculado às dependências de card, e react@17 será associado as dependências de card/node_modules/button.
peerDependenciesMeta
Esse campo lista algumas informações extras relacionadas às dependências listadas no campo peerDependencies.
peerDependenciesMeta.*.optional
Se for definido como true, a dependência selecionada será marcada como opcional pelo gerenciador de pacotes. Portanto, o consumidor que o omitir não será mais relatado como um erro.
Por exemplo:
{
"peerDependencies": {
"foo": "1"
},
"peerDependenciesMeta": {
"foo": {
"optional": true
},
"bar": {
"optional": true
}
}
}
Observe que, embora bar não tenha sido especificado em peerDependencies, é marcado como opcional. O pnpm, portanto, assumirá que qualquer versão de bar é válida. No entanto, foo é opcional, mas apenas para a especificação da versão necessária.
publishConfig
É possível substituir alguns campos no manifesto antes que o pacote seja concluído. Os seguintes campos podem ser substituídos:
Para subscrever um campo, adicione a versão de publicação do campo para o publishConfig.
Por exemplo, o seguinte package.json:
{
"name": "foo",
"version": "1.0.0",
"main": "src/index.ts",
"publishConfig": {
"main": "lib/index.js",
"typings": "lib/index.d.ts"
}
}
Será publicado como:
{
"name": "foo",
"version": "1.0.0",
"main": "lib/index.js",
"typings": "lib/index.d.ts"
}
publishConfig.executableFiles
Por padrão, por motivos de portabilidade, nenhum arquivo, exceto aqueles listados no campo bin, será marcado como executável no arquivo de pacote resultante. O campo executableFilles permite declarar campos adicionais que devem ter a flag executável (+x) definida mesmo que não sejam diretamente acessíveis através do campo bin.
{
"publishConfig": {
"executableFiles": [
"./dist/shim.js"
]
}
}
publishConfig.directory
Você também pode usar o campo publishConfig.directory para customizar o subdiretório publicado em relação ao package.json atual.
Espera-se que tenha uma versão modificada do pacote atual no diretório especificado (geralmente usando ferramentas de compilação de terceiros).
Nesse exemplo, a pasta
distdeve conter umpackage.json
{
"name": "foo",
"version": "1.0.0",
"publishConfig": {
"directory": "dist"
}
}
pnpm.overrides
Esse campo permite que você instrua o pnpm a substituir qualquer dependência no gráfico de dependências. Isso é útil para forçar todos os seus pacotes a usar uma única versão de uma dependência, fazer compatibilidade de uma correção ou substituir uma dependência por um fork.
Observe que o campo de substituições só pode ser definido na raiz do projeto.
Um exemplo do 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"
}
}
}
Você pode especificar o pacote ao qual a dependência substituída pertence separando o seletor de pacotes do seletor da dependência com um ">", por exemplo qar@1>zoo irá apenas substituir a dependência zoo de qar@1, não para quaisquer outras dependências.
pnpm.packageExtensions
Os campos packageExtensions oferecem uma maneira de estender as definições de pacotes existentes com informações adicionais. Por exemplo, se react-redux deve ter react-dom em suas peerDependencies mas não tem, é possível corrigir react-redux usando packageExtensions:
{
"pnpm": {
"packageExtensions": {
"react-redux": {
"peerDependencies": {
"react-dom": "*"
}
}
}
}
}
As chaves em packageExtensions são nomes de pacotes ou nomes de pacotes com intervalos semver, portanto, é possível corrigir apenas algumas versões de um pacote:
{
"pnpm": {
"packageExtensions": {
"react-redux@1": {
"peerDependencies": {
"react-dom": "*"
}
}
}
}
}
Os campos a seguir podem ser extendidos usando packageExtensions: dependencies, optionalDependencies, peerDependencies e peerDependenciesMeta.
Um exemplo maior:
{
"pnpm": {
"packageExtensions": {
"express@1": {
"optionalDependencies": {
"typescript": "2"
}
},
"fork-ts-checker-webpack-plugin": {
"dependencies": {
"@babel/core": "1"
},
"peerDependencies": {
"eslint": ">= 6"
},
"peerDependenciesMeta": {
"eslint": {
"optional": true
}
}
}
}
}
}
tip
Com Yarn, mantemos uma base de dados de packageExtensions para correção de pacotes quebrados no ecossistema. Se você usa packageExtensions, considere enviar um Pull Request e contribuir com a sua extensão para a base de dados @yarnpkg/extensions.
pnpm.peerDependencyRules
pnpm.peerDependencyRules.ignoreMissing
pnpm não imprimirá avisos sobre dependências ausentes dessa lista.
Por exemplo, com a seguinte configuração, o pnpm não imprimirá avisos se a dependência precisa do react, mas react não estiver instalado:
{
"pnpm": {
"peerDependencyRules": {
"ignoreMissing": ["react"]
}
}
}
Padrões de nome de pacote também podem ser usados:
{
"pnpm": {
"peerDependencyRules": {
"ignoreMissing": ["@babel/*", "@eslint/*"]
}
}
}
pnpm.peerDependencyRules.allowedVersions
Os avisos de dependência não atendidos não serão exibidos para dependências do intervalo específico.
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.
pnpm.peerDependencyRules.allowAny
Added in: v7.3.0
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.
Exemplo:
{
"pnpm": {
"onlyBuiltDependencies": ["fsevents"]
}
}
pnpm.allowedDeprecatedVersions
Adicionado em: v7.2.0
Essa configuração permite silenciar avisos de descontinuação de pacotes específicos.
Exemplo:
{
"pnpm": {
"allowedDeprecatedVersions": {
"express": "1",
"request": "*"
}
}
}
Com a configuração acima, o pnpm não imprimirá avisos de descontinuação sobre qualquer versão de request e sobre a versão v1 de express.
pnpm.patchedDependencies
Added in: v7.4.0
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.
Exemplo:
{
"pnpm": {
"express@4.18.1": "patches/express@4.18.1.patch"
}
}