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 um identificador único e exclusivo.

name

{
  "name": "meu-pacote-genial"
}

Este é o nome do seu pacote. Ele é usado em URLs, argumentos de linha de comando e como o nome da pasta onde ele vai ficar dentro de 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 @escopo/ 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 seguros para serem usados em URLs.

Dicas

  • Não use o mesmo nome de um módulo fundamental presente no próprio Node.js
  • Não coloque js ou node no nome.
  • Deixe seu nome o mais curto e descritivo possível. Você vai querer que as pessoas entendam o que ele é pelo nome, mas lembre-se que ele também será usado em chamadas require().
  • Tenha certeza de que não exista nada no registro com o mesmo nome.

version

{
  "version": "1.0.0"
}

A versão atual do seu pacote.

Informações

description

{
  "description": "Uma curta descrição do meu pacote genial"
}

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": ["palavras", "chave", "relevantes", "em", "pesquisas"]
}

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 o que é permitido e o que não é ao usar esses pacotes.

Incentivamos todos a usar uma licença de código aberto (aprovada pela OSI) 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 valor entre os seguintes:

  • Um identificador de licença SPDX válido se você estiver usando uma licença padrão.
  • Uma expressão de sintaxe de expressão de licença SPDX 2.0 válida se você estiver usando múltiplas licenças padrão.
  • Uma string SEE LICENSE IN <nome-de-arquivo> que aponta para um <nome-de-arquivo> 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://seu-pacote.org"
}

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

bugs

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

O link para o rastreador de problemas do seu projeto. Também pode ser um endereço de e-mail, ou algo assim. Oferece aos usuários uma maneira de descobrir para onde enviar problemas encontrados em seu pacote.

repository

{
  "repository": { "type": "git", "url": "https://github.com/usuario/repo.git" },
  "repository": "github:usuario/repo",
  "repository": "gitlab:usuario/repo",
  "repository": "bitbucket:usuario/repo",
  "repository": "gist:a1b2c3d4e5f"
}

O repositó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": "seu@email.com",
    "url": "http://seu-site.com"
  },
  "author": "Seu Nome <voce@exemplo.com> (http://seu-site.com)"
}

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

contributors

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

Aqueles que contribuíram para o seu pacote. Contribuidores são um array 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": ["nome-arquivo.js", "pasta/", "glob/*.{js,json}"]
}

Estes são os arquivos que serã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 do seu projeto.

bin

{
  "bin": "bin.js",
  "bin": {
    "nome-comando": "bin/nome-comando.js",
    "outro-comando": "bin/outro-comando"
  }
}

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ê tem páginas de manual associadas com seu projeto, adicione-as aqui.

directories

{
  "directories": {
    "lib": "caminho/para/lib/",
    "bin": "caminho/para/bin/",
    "man": "caminho/para/man/",
    "doc": "caminho/para/doc/",
    "exemplo": "caminho/para/exemplo/"
  }
}

Ao instalar seu pacote, você pode especificar as localizações exatas onde serão colocados 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 que podem ser executados usando yarn run <script>. Por exemplo, o script build-project acima pode ser chamado usando yarn run build-project, que por sua vez irá executar o node build-project.

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

O script start tem como valor padrão 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": {
    "pacote-1": "^3.1.4"
  }
}

Dependências normais são pacotes necessários tanto no processo de desenvolvimento quanto na parte de 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": {
    "pacote-2": "^0.4.2"
  }
}

Estes são pacotes que são somente necessários dentro do ciclo de desenvolvimento do seu pacote, mas que não serão instalados em produção.

peerDependencies

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

Dependências de pares permitem que você declare a compatibilidade do seu pacote com versões de outros pacotes.

optionalDependencies

{
  "optionalDependencies": {
    "pacote-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": ["pacote-4"]
}

As dependências agrupadas são um array de nomes de pacotes que serão incluídos no seu pacote ao publicá-lo.

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.

resolutions

{
  "resolutions": {
    "pacote-transitivo-1": "0.0.29",
    "pacote-transitivo-2": "file:./forks-locais/pacote-transitivo-2",
    "dependencias-pacote-1/pacote-transitivo-3": "^2.1.1"
  }
}

Permite sobrepor a versão de uma dependência aninhada específica. Veja a página Resolução Seletiva de Versões para ver a especificação completa.

Observe que instalar as dependências usando [yarn install --flat] fará com que o bloco resolutions seja adicionado automaticamente ao seu arquivo package.json.

Sistema

Você pode fornecer informações a nível de sistema associados 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 o objeto process.versions, bem como a versão atual do Yarn.

Esta verificação segue as regras normais de semver com uma exceção. Ela permite que versões de pré-lançamento correspondam a semvers que não especificam explicitamente um pré-lançamento. Por exemplo, a versão 1.4.0-rc.0 corresponde a >=1.3.0, o que não aconteceria caso fosse realizada uma verificação normal de semver.

os

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

Use isso para especificar com quais sistemas operacionais seu pacote será ou não compatível. Isso verifica a string process.platform.

cpu

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

Use isso para especificar que seu pacote será executado somente em determinadas arquiteturas de CPU. Isso verifica a string 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 criar uma tag para o seu pacote, por exemplo.