package.json

Fundamentos

Os dois campos mais importantes no seu package.json são name e version, sem eles não será possível instalar seu pacote. Os campos name e version são usados juntos para criar uma id exclusiva.

name

{
  "name": "my-awesome-package"
}

Este é o nome do seu pacote. Ele é usado em URLs, como um argumento na linha de comando e como o nome do diretório dentro da pasta node_modules.

yarn add [name]
node_modules/[name]


https://registry.npmjs.org/[name]/-/[name]-[version].tgz

Regras

  • Deve ser menor ou igual a 214 caracteres (incluindo o @scope/ para pacotes com escopo).
  • Não deve iniciar com um ponto (.) ou um sublinhado (_).
  • Não deve ter letras maiúsculas no nome.
  • Deve usar apenas caracteres de URL-seguro.

Dicas

  • Não use o mesmo nome de um módulo fundamental do Node.js
  • Não coloque js ou node no nome.
  • Mantenha os nomes curtos e descritivos. Você quer que as pessoas entendam o que ele é pelo nome, mas o nome também será usado em chamadas require().
  • Certifique-se de que não existe algo no registro com o mesmo nome.

version

{
  "version": "1.0.0"
}

A versão atual do seu pacote.

Informações

description

{
  "description": "My short description of my awesome package"
}

A descrição é apenas uma string que ajuda as pessoas a entenderem o propósito do pacote. Ela também pode ser usada na procura de pacotes em um gerenciador de pacotes.

keywords

{
  "keywords": ["short", "relevant", "keywords", "for", "searching"]
}

Keywords é um array de strings que são úteis ao procurar por 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 eles são autorizados a usá-lo, e todas as restrições que você está colocando nele.

Você é encorajado a usar uma licença de código aberto (OSI-aproved), a menos que você tenha um motivo específico para não fazer isso. Se você construiu seu pacote como parte do seu trabalho, é provavelmente melhor verificar com sua empresa antes de decidir sobre uma licença.

Deve ser um dos seguintes:

  • Um identificador de licença SPDX válido se você estiver usando uma licença padrão.
  • Uma expressão de 2.0 de sintaxe de expressão de licença SPDX valida se você estiver usando múltiplas licenças padrão.
  • Uma string SEE LICENSE IN <nomearquivo> que aponta para um <nomearquivo> na raiz do seu pacote, se você estiver usando uma licença não-padrão.
  • Uma string UNLICENSED se você não quer conceder a outros o direito de usar um pacote privado ou não-publicado sob quaisquer condições.

Vários links para documentação, lugares para reportar problemas e onde o código do seu pacote está hospedado.

homepage

{
  "homepage": "https://your-package.org"
}

A homepage é a URL para a página inicial ou a documentação do seu pacote.

bugs

{
  "bugs": "https://github.com/user/repo/issues"
}

A URL para o rastreador de problemas do seu projeto. Isso também pode ser algo como um endereço de e-mail. Oferece aos usuários uma maneira de descobrir para onde enviar problemas encontrados em 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 respositório é o local onde está hospedado o código fonte do seu pacote.

Mantenedores

Os mantenedores do seu projeto.

author

{
  "author": { "name": "Seu Nome", "email": "voce@examplo.com", "url": "http://seu-website.com" },
  "author": "Seu Nome <voce@examplo.com> (http://seu-website.com)"
}

Informações sobre o autor do pacote. Um autor é uma pessoa.

contributors

{
  "contributors": [
    { "name": "Seu Amigo", "email": "amigo@examplo.com", "url": "http://amigo-website.com" }
    { "name": "Outro Amigo", "email": "outro@examplo.com", "url": "http://outro-website.com" }
  ],
  "contributors": [
    "Seu Amigo <amigo@examplo.com> (http://amigo-website.com)",
    "Outro Amigo <outro@examplo.com> (http://outro-website.com)"
  ]
}

Aqueles que contribuíram para o seu pacote. Contribuintes são um conjunto de pessoas.

Arquivos

Você pode especificar arquivos que serão incluídos no seu projeto, juntamente com o ponto de entrada principal para o seu projeto.

files

{
  "files": [
    "filename.js",
    "directory/",
    "glob/*.{js,json}"
  ]
}

Estes são arquivos que são incluídos em seu projeto. Você pode especificar arquivos individuais, diretórios inteiros ou usar curingas para incluir arquivos que atendam a determinados critérios.

main

{
  "main": "filename.js"
}

Este é o ponto de entrada principal para a funcionalidade para o seu projeto.

bin

{
  "bin": "bin.js",
  "bin": {
    "command-name": "bin/command-name.js",
    "other-command": "bin/other-command"
  }
}

Arquivos executáveis incluídos com o seu projeto que será instalado.

man

{
  "man": "./man/doc.1",
  "man": ["./man/doc.1", "./man/doc.2"]
}

Se você tem páginas de manual associadas com 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 instalarem seu pacote, você pode especificar localizações exatas para colocar arquivos binários, páginas de manual, documentação, exemplos, etc.

Tarefas

Seu pacote pode incluir scripts executáveis ou outras configurações.

scripts

{
  "scripts": {
    "build-project": "node build-project.js"
  }
}

Scripts são uma ótima maneira de automatizar tarefas relacionadas ao seu pacote, tais como processos de compilação simples ou ferramentas de desenvolvimento. Usando o campo de "scripts", você pode definir vários scripts para serem executados como yarn run <script>. Por exemplo, o script de build-project acima pode ser chamado com yarn run build-project e irá executar o node build-project.

Certos nomes de script são especiais. Se definido, o script preinstall é chamado pelo Yarn antes que o pacote seja instalado. Por razões de compatibilidade, scripts chamados install, postinstall e prepublish serão todos chamados depois que seu pacote acabou de instalar.

O script start é padrão para node server.js.

config

{
  "config": {
    "port": "8080"
  }
}

Opções de configuração ou parâmetros utilizados em seus scripts.

Dependências

Seu pacote muito provavelmente vai depender de outros pacotes. Você pode especificar essas dependências no seu arquivo package.json.

dependencies

{
  "dependencies": {
    "package-1": "^3.1.4"
  }
}

Estas são as dependências que são 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, >=... <).

devDependecies

{
  "devDependencies": {
    "package-2": "^0.4.2"
  }
}

Estes são os pacotes que são somente necessários quando no desenvolvimento do seu pacote, mas não serão instalados em produção.

peerDependencies

{
  "peerDependencies": {
    "package-3": "^2.7.18"
  }
}

Dependências de pares permitem que você defina 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 necessárias. Se um pacote opcional não for encontrado, a instalação continua.

bundledDependencies

{
  "bundledDependencies": [
    "package-4"
  ]
}

As dependências agrupadas são um array de nomes de pacotes que serão agrupados ao publicar seu pacote.

flat

{
  "flat": true
}

Se seu pacote permite apenas uma versão de uma determinada dependência e você gostaria de impor o mesmo comportamento de yarn install --flat na linha de comando, defina isto como true.

Observe que se seu package.json contém "flat": true e outros pacotes dependem dele (por exemplo, você está construindo uma biblioteca em vez de um aplicativo), esses outros pacotes também precisarão de "flat": true em seus package.json ou que sejam instalados com yarn install --flat na linha de comando.

Sistema

Você pode fornecer informações de nível de sistema associado com seu pacote, tais como compatibilidade de sistema operacional, etc.

engines

{
  "engines": {
    "node": ">=4.4.7 <7.0.0",
    "zlib": "^1.2.8",
    "yarn": "^0.14.0"
  }
}

Os engines especificam as versões de clientes que devem ser usadas com o seu pacote. Isto verifica contra process.versions, bem como a versão atual yarn.

os

{
  "os": ["darwin", "linux"],
  "os": ["!win32"]
}

Isso especifica a compatibilidade com sistema operacional para o seu pacote. Ele verifica contra process.platform.

cpu

{
  "cpu": ["x64", "ia32"],
  "cpu": ["!arm", "!mips"]
}

Use isso para especificar que seu pacote será executado somente em algumas arquiteturas de CPU. Isto verifica contra process.arch.

Publicando

private

{
  "private": true
}

Se você não quiser que seu pacote seja publicado em um gerenciador de pacotes, defina isso como true.

publishConfig

{
  "publishConfig": {
    ...
  }
}

Esses valores de configuração vão ser usados na publicação do seu pacote. Você pode identificar seu pacote, por exemplo.