cuidado, não use package.json para o nome da pasta se quiser clonar este projeto em sua máquina - isso quebrará yarn ( An unexpected error occurred: "EISDIR: illegal operation on a directory, read". ).
Versão original deste documento copiada de yarnpkg.
Veja também a documentação do npm, std-pkg, clean-publish, package-json-validator, cosmiconfig, rc (como uma abordagem oponente ao cosmiconfig).
nameversiondescriptionkeywordslicensehomepagebugsrepositoryauthorcontributorsfilesmainbinmandirectoriesscriptsscripts específicos do npmconfigdependenciesdevDependenciespeerDependenciesoptionalDependenciesbundledDependenciesenginesoscpulibcprivatepublishConfigflatresolutionsworkspacesboltunpkgtypesflow:mainbrowserslistmodulebrowseresnextes2015esmmodule-browsermodules.rootjsnext:mainreact-nativesideEffectssource , umd:mainsource@std/esmjspmignoreformatregistryshimmapbrowserify.transformproxyhomepagebabeleslintConfigjeststylelintsize-limitpwmetricsavanycpreferGlobalstylelessstandard Os dois campos mais importantes em seu package.json são name e version , sem eles seu pacote não poderá ser instalado. Os campos name e version são usados juntos para criar um ID exclusivo.
name{
"name" : " my-awesome-package "
} Este é o nome do seu pacote. Ele é usado em URLs, como argumento na linha de comando e como nome de diretório dentro de node_modules .
yarn add [name] node_modules/[name]
https://registry.npmjs.org/[name]/-/[name]-[version].tgz
Regras
@scope/ para pacotes com escopo definido).. ) ou sublinhado ( _ ).Pontas
js ou node no nome.require() .version{
"version" : " 1.0.0 "
}A versão atual do seu pacote.
description{
"description" : " My short description of my awesome package "
}A descrição é apenas uma string que ajuda as pessoas a entender o propósito do pacote. Ele também pode ser usado ao procurar pacotes em um gerenciador de pacotes.
keywords{
"keywords" : [ " short " , " relevant " , " keywords " , " for " , " searching " ]
}Palavras-chave são um conjunto de strings úteis ao procurar pacotes em um gerenciador de pacotes.
license{
"license" : " MIT " ,
"license" : " (MIT or GPL-3.0) " ,
"license" : " SEE LICENSE IN LICENSE_FILENAME.txt " ,
"license" : " UNLICENSED "
}Todos os pacotes devem especificar uma licença para que os usuários saibam como podem usá-lo e quaisquer restrições que você esteja impondo a ele.
Recomendamos que você use uma licença de código aberto (aprovada pela OSI), a menos que tenha um motivo específico para não fazê-lo. Se você criou seu pacote como parte de seu trabalho, provavelmente é melhor verificar com sua empresa antes de decidir sobre uma licença.
Deve ser um dos seguintes:
SEE LICENSE IN <filename> que aponta para um <filename> no nível superior do seu pacote se você estiver usando uma licença não padrão.UNLICENSED se você não quiser conceder a terceiros o direito de usar um pacote privado ou não publicado sob quaisquer termos. Vários links para documentação, locais para registrar problemas e onde o código do seu pacote realmente reside.
homepage{
"homepage" : " https://your-package.org "
}A página inicial é o URL da página de destino ou da documentação do seu pacote.
Também usado pelo aplicativo Create React
bugs{
"bugs" : " https://github.com/user/repo/issues "
}A URL para o rastreador de problemas do seu projeto. Também pode ser algo como um endereço de e-mail. Ele fornece aos usuários uma maneira de descobrir para onde enviar problemas com seu pacote.
repository{
"repository" : { "type" : " git " , "url" : " https://github.com/user/repo.git " },
"repository" : " github:user/repo " ,
"repository" : " gitlab:user/repo " ,
"repository" : " bitbucket:user/repo " ,
"repository" : " gist:a1b2c3d4e5f "
}O repositório é o local onde reside o código real do seu pacote.
Os mantenedores do seu projeto.
author{
"author" : { "name" : " Your Name " , "email" : " [email protected] " , "url" : " http://your-website.com " },
"author" : " Your Name <[email protected]> (http://your-website.com) "
}Informações do autor do pacote. Um autor é uma pessoa.
contributors{
"contributors" : [
{ "name" : " Your Friend " , "email" : " [email protected] " , "url" : " http://friends-website.com " }
{ "name" : " Other Friend " , "email" : " [email protected] " , "url" : " http://other-website.com " }
],
"contributors" : [
" Your Friend <[email protected]> (http://friends-website.com) " ,
" Other Friend <[email protected]> (http://other-website.com) "
]
}Aqueles que contribuíram para o seu pacote. Os colaboradores são uma variedade de pessoas.
Você pode especificar os arquivos que serão incluídos no seu projeto, juntamente com o ponto de entrada principal do seu projeto.
files{
"files" : [
" filename.js " ,
" directory/ " ,
" glob/*.{js,json} "
]
}Esses são arquivos incluídos no seu projeto. Você pode especificar arquivos únicos, diretórios inteiros ou usar curingas para incluir arquivos que atendam a determinados critérios.
main{
"main" : " filename.js "
}Este é o principal ponto de entrada para a funcionalidade do seu projeto.
bin{
"bin" : " bin.js " ,
"bin" : {
"command-name" : " bin/command-name.js " ,
"other-command" : " bin/other-command "
}
}Arquivos executáveis incluídos no seu projeto que serão instalados.
man{
"man" : " ./man/doc.1 " ,
"man" : [ " ./man/doc.1 " , " ./man/doc.2 " ]
}Se você tiver páginas de manual associadas ao seu projeto, adicione-as aqui.
directories{
"directories" : {
"lib" : " path/to/lib/ " ,
"bin" : " path/to/bin/ " ,
"man" : " path/to/man/ " ,
"doc" : " path/to/doc/ " ,
"example" : " path/to/example/ "
}
}Ao instalar seu pacote, você pode especificar locais exatos para colocar arquivos binários, páginas de manual, documentação, exemplos, etc.
Seu pacote pode incluir scripts executáveis ou outras configurações.
scripts{
"scripts" : {
"build-project" : " node build-project.js "
}
} Os scripts são uma ótima maneira de automatizar tarefas relacionadas ao seu pacote, como processos simples de construção ou ferramentas de desenvolvimento. Usando o campo "scripts" , você pode definir vários scripts para serem executados como yarn run <script> . Por exemplo, o script build-project acima pode ser invocado com yarn run build-project e executará node build-project.js .
Certos nomes de script são especiais. Se definido, o script preinstall é chamado pelo yarn antes de seu pacote ser instalado. Por motivos de compatibilidade, os scripts chamados install , postinstall e prepublish serão todos chamados após a conclusão da instalação do pacote.
O valor do script start é padronizado como node server.js .
"scripts": {"start": "node server.js"}. Se houver um arquivo server.js na raiz do seu pacote, o npm padronizará o comando start para node server.js.
"scripts":{"preinstall": "node-gyp rebuild"}. Se houver um arquivo binding.gyp na raiz do seu pacote, o npm irá padronizar o comando preinstall para compilar usando node-gyp.- documentos npm
scripts específicos do npm npm suporta a propriedade scripts do arquivo package.json , para os seguintes scripts:
prepublish : Executa ANTES do pacote ser compactado e publicado, bem como na instalação local do npm sem quaisquer argumentos. (Veja abaixo)prepare : execute ANTES do pacote ser compactado e publicado e na instalação local do npm sem nenhum argumento (veja abaixo). Isso é executado APÓS a pré-publicação, mas ANTES do prepublishOnly.prepublishOnly : Executa ANTES do pacote ser preparado e empacotado, SOMENTE no npm subscribe. (Veja abaixo.)prepack : execute ANTES de um tarball ser compactado (no pacote npm, publicação npm e ao instalar dependências git)postpack : Executa APÓS o tarball ter sido gerado e movido para seu destino final.publish , postpublish : Executar APÓS a publicação do pacote.preinstall : Execute ANTES do pacote ser instaladoinstall , postinstall : Execute DEPOIS que o pacote for instalado.preuninstall , uninstall : Execute ANTES de o pacote ser desinstalado.postuninstall : Execute DEPOIS que o pacote for desinstalado.preversion : Execute ANTES de alterar a versão do pacote.version : Execute DEPOIS de alterar a versão do pacote, mas ANTES de confirmar.postversion : Execute DEPOIS de alterar a versão do pacote e DEPOIS de confirmar.pretest , test , posttest : executado pelo comando npm test.prestop , stop , poststop : executado pelo comando npm stop.prestart , start , poststart : executado pelo comando npm start.prerestart , restart , postrestart : executado pelo comando npm restart. Nota: o npm restart executará os scripts de parada e início se nenhum script de reinicialização for fornecido.preshrinkwrap , shrinkwrap , postshrinkwrap : Executado pelo comando npm Shrinkwrap.Fonte: documentos npm.
config{
"config" : {
"port" : " 8080 "
}
}Opções de configuração ou parâmetros usados em seus scripts.
Seu pacote provavelmente dependerá de outros pacotes. Você pode especificar essas dependências em seu arquivo package.json .
dependencies{
"dependencies" : {
"package-1" : " ^3.1.4 "
}
}Essas são dependências necessárias tanto no desenvolvimento quanto na produção do seu pacote.
Você pode especificar uma versão exata, uma versão mínima (por exemplo,
>=) ou um intervalo de versões (por exemplo>= ... <).
devDependencies{
"devDependencies" : {
"package-2" : " ^0.4.2 "
}
}Esses são pacotes necessários apenas ao desenvolver seu pacote, mas não serão instalados na produção.
peerDependencies{
"peerDependencies" : {
"package-3" : " ^2.7.18 "
}
}As dependências de peer permitem que você declare a compatibilidade do seu pacote com versões de outros pacotes.
optionalDependencies{
"optionalDependencies" : {
"package-5" : " ^1.6.1 "
}
}Dependências opcionais podem ser usadas com seu pacote, mas não são obrigatórias. Se o pacote opcional não for encontrado, a instalação continuará.
bundledDependencies{
"bundledDependencies" : [
" package-4 "
]
}Dependências agrupadas são uma série de nomes de pacotes que serão agrupados ao publicar seu pacote.
Você pode fornecer informações de nível de sistema associadas ao seu pacote, como compatibilidade do sistema operacional, etc.
engines{
"engines" : {
"node" : " >=4.4.7 <7.0.0 " ,
"zlib" : " ^1.2.8 " ,
"yarn" : " ^0.14.0 "
}
} Os mecanismos especificam versões de clientes que devem ser usados com seu pacote. Isso verifica process.versions bem como a versão atual do fio.
os{
"os" : [ " darwin " , " linux " ],
"os" : [ " !win32 " ]
} Isto especifica a compatibilidade do sistema operacional para o seu pacote. Ele verifica process.platform .
cpu{
"cpu" : [ " x64 " , " ia32 " ],
"cpu" : [ " !arm " , " !mips " ]
} Use isto para especificar que seu pacote será executado apenas em determinadas arquiteturas de CPU. Isso verifica process.arch .
libc{
"libc" : [ " glibc " ],
"libc" : [ " musl " ]
} Use isto para especificar que seu pacote só é executado em um tipo específico de libc. Isso verifica o resultado de detect-libc .
private{
"private" : true
} Se você não deseja que seu pacote seja publicado em um gerenciador de pacotes, defina como true .
publishConfig{
"publishConfig" : {
...
}
}Esses valores de configuração serão usados ao publicar seu pacote. Você pode marcar seu pacote, por exemplo.
flat{
"flat" : true
} Se o seu pacote permitir apenas uma versão de uma determinada dependência e você quiser impor o mesmo comportamento de yarn install --flat na linha de comando, defina-o como true .
Observe que se o seu package.json contém "flat": true e outros pacotes dependem do seu (por exemplo, você está construindo uma biblioteca em vez de um aplicativo), esses outros pacotes também precisarão de "flat": true em seu package.json ou ser instalado com yarn install --flat na linha de comando.
resolutions{
"resolutions" : {
"transitive-package-1" : " 0.0.29 " ,
"transitive-package-2" : " file:./local-forks/transitive-package-2 " ,
"dependencies-package-1/transitive-package-3" : " ^2.1.1 "
}
}Permite substituir uma versão de uma dependência aninhada específica. Consulte a RFC de resoluções de versões seletivas para obter as especificações completas.
Observe que a instalação de dependências via [ yarn install --flat ] adicionará automaticamente um bloco resolutions ao seu arquivo package.json .
workspaces Se --use-workspaces for verdadeiro, packages serão substituídos pelo valor de package.json/workspaces .
Fonte: --use-workspaces.
boltVeja Configuração
{
"bolt" : {
"workspaces" : [
" utils/* " ,
" apps/* "
]
}
}unpkg Se você omitir o caminho do arquivo (ou seja, usar um URL "vazio"), unpkg servirá o arquivo especificado pelo campo unpkg em package.json ou retornará para main (fonte).
types Se o seu pacote tiver um arquivo .js principal, você também precisará indicar o arquivo de declaração principal no seu arquivo package.json . Defina a propriedade types para apontar para o arquivo de declaração incluído. Por exemplo:
{
"main" : " ./lib/main.js " ,
"types" : " ./lib/main.d.ts "
} Observe que o campo typings é sinônimo de types e também pode ser usado.
Observe também que se o seu arquivo de declaração principal for denominado index.d.ts e estiver na raiz do pacote (ao lado de index.js ), você não precisará marcar a propriedade types , embora seja aconselhável fazê-lo.
Fonte: documentação TypeScript
Nota: no Flow eles usam uma abordagem diferente
flow:mainNão é oficialmente suportado. A proposta está aqui.
browserslist? Biblioteca para compartilhar navegadores de destino entre diferentes ferramentas front-end. É usado em:
package.json ou browserslist suportados em 2.0) Todas as ferramentas que dependem do Browserslist encontrarão sua configuração automaticamente, quando você adicionar o seguinte ao package.json :
{
"browserslist" : [
" > 1% " ,
" last 2 versions "
]
}Fonte: lista de navegadores.
Veja também: Criar suporte para aplicativo React.
Consulte "Configurando pacotes npm multiplataforma" para obter uma introdução.
module pkg.module apontará para um módulo que possui sintaxe de módulo ES2015, mas, caso contrário, apenas recursos de sintaxe suportados pelos ambientes de destino. A descrição completa está aqui.
Suportado por: rollup, webpack
browser O campo browser é fornecido por um autor do módulo como uma dica para empacotadores javascript ou ferramentas de componentes ao empacotar módulos para uso do lado do cliente. A proposta está aqui.
Suportado por: rollup, webpack, browserify
Suporte solicitado: babel-plugin-module-resolver
esnextA proposta completa está aqui. Breve explicação:
esnext : código fonte usando recursos do estágio 4 (ou mais antigos), não transpilados, em módulos ES.main : aponta para um módulo CommonJS (ou módulo UMD) com JavaScript tão moderno quanto o Node.js pode suportar atualmente.module deve ser controlável via esnext .browser pode ser gerenciado através de uma versão estendida do esnext {
"main" : " main.js " ,
"esnext" : {
"main" : " main-esnext.js " ,
"browser" : " browser-specific-main-esnext.js "
}
}Veja também: Entregando código-fonte não transpilado via npm
es2015Código ES6 não transpilado. Fonte: Formato de Pacote Angular (APF) v5.0
esmA proposta está aqui: proposta ajustada: Módulo ES "esm": true package.json flag
Veja também:
module-browserVeja este problema
Também conhecido como moduleBrowser , jsnext:browser .
modules.rootMencionado em Em defesa de .js.
Há também modules.resolver .
jsnext:mainDEPRECADO
jsnext:main foi substituído por pkg.module , que indica a localização de um arquivo com declarações de importação/exportação. A proposta original está aqui.
Apoiado por: rollup.
react-native Funciona de forma semelhante ao browser , mas para módulos específicos react-nativos. Fonte.
sideEffectsIndica que os módulos do pacote não têm efeitos colaterais (na avaliação) e expõem apenas as exportações. Isso permite que ferramentas como o webpack otimizem as reexportações.
Veja também: exemplo sideEffects , proposta para marcar funções como puras, eslint-plugin-tree-shaking.
source , umd:mainConsulte Especificando compilações em package.json.
sourceConsulte pacote empacotador/pacote#1652.
@std/esm Os desenvolvedores têm opiniões fortes sobre quase tudo. Para acomodar, @std/esm permite desbloquear recursos extras com o campo "@std/esm" ou "@std":{"esm":{}} em seu package.json .
Fonte: @std/esm Desbloqueáveis
jspm Você pode escrever todas as propriedades do pacote na base do package.json ou, se não quiser alterar as propriedades existentes que gostaria de usar especificamente para npm , pode escrever sua configuração específica do jspm dentro da propriedade jspm de package.json e jspm usarão essas opções em vez das opções de configuração de nível raiz.
Por exemplo:
{
"name" : " my-package " ,
"jspm" : {
"main" : " jspm-main "
}
}Veja a especificação completa.
ignoreSe houver determinados arquivos ou pastas específicos a serem ignorados, eles poderão ser listados em uma matriz.
format As opções são esm , amd , cjs e global .
Ao carregar módulos do
npm, o formato do módulo é tratado comocjspor padrão e nenhuma detecção automática é executada. Para carregar módulos de outro formato você precisará substituir esta propriedade manualmente.
O formato do módulo
esm(Módulo ECMAScript) atualmente não é usado em package.json.
registryjspm entende dependências no contexto de um registro.
Ao carregar pacotes do npm, o jspm definirá o registro padrão como npm e tratará as dependências de acordo.
Ao carregar pacotes do GitHub, a propriedade dependencies é ignorada sem a presença de uma propriedade de registro, pois o jspm não tem como saber o que as dependências significam para os repositórios existentes do GitHub.
A configuração da propriedade de registro também determina como o jspm interpreta o pacote. Por exemplo, um pacote GitHub com registry: "npm" será, junto com a obtenção de suas dependências do npm, interpretado como CommonJS e suporte a recursos como diretório e JSON necessários, exatamente como se tivesse sido instalado a partir do endpoint npm para começar.
Um pacote no GitHub com sua propriedade de registro definida como registry: "jspm" terá suas dependências tratadas como dependências no estilo jspm.
shim Pacotes escritos como globais precisam de uma configuração shim para funcionar corretamente em um ambiente modular. Para corrigir um arquivo some/global.js dentro do pacote, podemos escrever:
{
"shim" : {
"some/global" : {
"deps" : [ " jquery " ],
"exports" : " globalExportName "
}
}
} Tanto deps quanto exports são opcionais.
exports são detectadas automaticamente pelo carregador SystemJS como quaisquer globais escritos pelo script. Na maioria dos casos, esta detecção funcionará corretamente.
A forma de atalho "some/global": ["jquery"] também é suportada se não houver exports .
mapA configuração do mapa reescreverá os requisitos internos para apontar para diferentes módulos locais ou externos.
Considere um pacote que inclui sua própria dependência, dep localizada em third_party/dep . Poderia ter uma instrução require internamente, algo como:
require ( 'dep' ) ;Para usar a versão local, podemos escrever:
{
"map" : {
"dep" : " ./third_party/dep "
}
}Também pode ser útil referenciar um pacote pelo seu próprio nome dentro dos submódulos:
{
"map" : {
"thispackage" : " . "
}
} Podemos então ter requisitos internos para import 'thispackage/module' resolvidos corretamente.
A configuração do mapa também pode fazer referência a submódulos de dependência.
Também podemos excluir totalmente os módulos mapeando-os para o módulo vazio:
{
"map" : {
"jquery" : " @empty "
}
}O valor retornado será então um objeto Módulo sem exportações.
browserify.transformA documentação está aqui
proxyAs pessoas geralmente atendem o aplicativo React front-end no mesmo host e porta de sua implementação back-end.
Fonte: Proxy de solicitações de API em desenvolvimento
homepageFonte: Construindo para Caminhos Relativos
babelVeja este problema.
eslintConfigjest{
"jest" : {
"verbose" : true
}
}
Fonte: documentos de brincadeira
stylelintVeja: Novo carregador de configuração
size-limit Se estiver usando esta biblioteca, você pode definir sua configuração em package.json :
{
"size-limit" : [
{
"limit" : " 9 KB " ,
"path" : " index.js "
}
]
}Fonte: limite de tamanho
pwmetrics Você pode especificar opções em package.json :
{
"pwmetrics" : {
"url" : " http://example.com/ " ,
"expectations" : {
"ttfcp" : {
"warn" : " >=1500 " ,
"error" : " >=2000 "
}
}
}
}Todas as opções disponíveis estão aqui
Fonte: pwmetrics
avaExemplo:
"ava" : {
"require" : [ " @std/esm " ]
}Fonte: ava
nycExemplo:
"nyc" : {
"extension" : [ " .js " , " .mjs " ],
"require" : [ " @std/esm " ]
}Fonte: Nova York
preferGlobalDEPRECADO
Esta opção costumava acionar um aviso npm, mas não avisará mais. Está lá apenas para fins informativos. Agora é recomendado que você instale quaisquer binários como devDependencies locais sempre que possível.
style O atributo style em package.json é útil para importar pacotes CSS. A proposta está aqui.
Suportado por: parcelaify, npm-less, rework-npm, npm-css.
Veja também: especificação istf.
less O mesmo que style mas por menos.
Suportado por: npm-less.
Os seguintes campos são reservados para expansão futura: build , default , email , external , files , imports , maintainer , paths , platform , require , summary , test , using , downloads , uid .
Os seguintes campos são reservados para os registros de pacotes usarem a seu critério: id , type .
Todas as propriedades que começam com _ ou $ também são reservadas para registros de pacotes usarem a seu critério.
Fonte: wiki CommonJS
standard JS padrão é um guia de estilo javaScript, linter e formatador. Você pode adicionar algumas propriedades ao package.json, como parser , ignore , globals , plugins .
Exemplo:
"standard" : {
"parser" : " babel-eslint " ,
"ignore" : [
" **/out/ " ,
" /lib/select2/ " ,
" /lib/ckeditor/ " ,
" tmp.js "
]
}Veja também: JS padrão
