Criando um Pacote

Um package é um diretório com algum código e um arquivo package.json que fornece informação para o Yarn sobre o seu pacote.

A maioria dos pacotes usam algum tipo de sistema de controle de versão. O mais comum é git, mas o Yarn não se importa com qual você escolher usar. Para este guia, nossos exemplos vão usar git.

Nota: Se você quer seguir este guia, certifique-se de instalar primeiro git e Yarn.

Criando seu primeiro pacote

Para criar seu primeiro pacote, abra o terminal/console do seu sistema e execute os seguintes comandos:

git init my-new-project
cd my-new-project
yarn init

Isso vai criar um novo repositório git, posicioná-lo dentro deste, e então abrir um formulário interativo para criar um novo projeto yarn com as seguintes questões:

name (my-new-project):
version (1.0.0):
description:
entry point (index.js):
git repository:
author:
license (MIT):

Você pode digitar as respostas para cada um dos campos ou apenas apertar enter/return para usar o valor padrão ou deixar em branco.

Dica: Se você quer usar os valores padrões para tudo, pode executar yarn init --yes e ele vai pular todas as perguntas.

`package.json`

Agora você deve ter um package.json que parece com isso:

{
  "name": "my-new-project",
  "version": "1.0.0",
  "description": "My New Project description.",
  "main": "index.js",
  "repository": {
    "url": "https://example.com/your-username/my-new-project",
    "type": "git"
  },
  "author": "Your Name <you@example.com>",
  "license": "MIT"
}

Os campos que você vê no package.json tem os seguintes significados:

name é o identificador do seu pacote, se você vai publicá-lo no registro global, você precisa ter certeza que é único.
version é a versão, compatível com o formato semver, do seu pacote, você pode publicar um pacote quantas vezes você quiser, mas eles devem ter novas versões.
description é um campo opcional, mas recomendado, que é usado por outros usuários do Yarn para buscar e entender o seu projeto.
main é usado para definir o ponto de entrada do seu código usado por programas como Node.js. Se não for especificado, o padrão será index.js.
repository é outro campo opcional, mas recomendado, que ajuda os usuários do seu pacote a encontrarem o código fonte para contribuir.
author é o criador ou mantenedor de um pacote. Segue o formato "Seu Nome <voce@exemplo.com>(http://seu-website.com)"
license são os termos legais de publicação do seu pacote e qual é o uso permitido do código do seu pacote.

Quando você executa yarn init, tudo o que ele está fazendo é criar esse arquivo, nada acontece em segundo plano. Você pode ficar à vontade para editar esse arquivo o quanto você quiser.

Campos adicionais

Vamos ver alguns campos adicionais do package.json que você pode querer adicionar.

{
  "name": "my-new-project",
  "...": "...",
  "keywords": ["cool", "useful", "stuff"],
  "homepage": "https://my-new-project-website.com",
  "bugs": "https://github.com/you/my-new-project/issues",
  "contributors": [
    "Your Friend <their-email@example.com> (http://their-website.com)",
    "Another Friend <another-email@example.com> (https://another-website.org)"
  ],
  "files": [
    "index.js",
    "lib/*.js",
    "bin/*.js"
  ],
  "bin": {
    "my-new-project-cli": "bin/my-new-project-cli.js"
  }
}

keywords é uma lista de termos que outros desenvolvedores podem procurar para achar seu pacote ou pacotes relacionados.
homepage é uma url que aponta os usuários para o seu website que os informa sobre o pacote com uma introdução, documentação e links para recursos adicionais.
bugs é uma url que aponta os usuários do seu pacote para caso eles descubram um problema com seu pacote.
contributors é uma lista de colaboradores do seu pacote. Se há outras pessoas envolvidas no seu projeto, elas podem ser especificadas aqui.
files é uma lista de arquivos que devem ser incluídos no seu pacote quando publicado e instalado. Se não especificado, Yarn vai incluir todos os arquivos.
bin é um mapeamento de comandos cli (binários) para o Yarn criar para o pacote quando instalá-lo.

Para uma lista completa de todos os campos do package.json e mais detalhes sobre cada campo acima, por favor veja package.json documentation.

Licenciamento e de código aberto

Pacotes Yarn são geralmente incentivados a ser open source, no entanto, é importante notar que pacotes não são inerentemente de código aberto simplesmente publicando-os.

Para seu código ser abeto, ele precisa ter uma licença de código aberto. Há muitas licenças de código aberto para escolher, algumas das mais comuns são:

Se você quiser mais opções, você pode obter uma lista mais completa aqui.

Quando você escolhe uma licença de código aberto para seu pacote, certifique-se de adicionar o arquivo LICENSE na pasta raiz do seu pacote com o texto da licença e atualize seu campo license no arquivo package.json.

Nota: Se você não quer que seu projeto seja licenciado como um projeto de código aberto, você deve ser explícito sobre qual é o licenciamento ou se não é licenciado.

Compartilhamento de código

Você provavelmente vai querer que os usuários do seu pacote sejam capazes de acessar o código fonte e terem maneiras de reportar problemas. Há alguns websites populares para hospedagem do seu código:

Esses sites permitem que seus usuários vejam seu código, reportem problemas e contribuam com o projeto. Quando você tiver seu código em algum lugar, você deve adicionar os seguintes campos no seu arquivo package.json:

{
  "homepage": "https://github.com/username/my-new-project",
  "bugs": "https://github.com/username/my-new-project/issues",
  "repository": {
    "url": "https://github.com/username/my-new-project",
    "type": "git"
  }
}

Documentação

Você deve idealmente escrever sua documentação antes de sair publicando seu pacote. O mínimo que você deve escrever é um arquivo README.md na pasta raiz do seu projeto que introduz seu pacote e documenta a API pública.

Boa documentação é definida por dar aos usuários todo conhecimento que precisam para começar, e continuar, a usar seu projeto. Pense sobre as questões que alguém que não saiba nada sobre seu projeto possa ter. Descreva as coisas com precisão e detalhamento, tanto quanto for necessário, mas também tente mantê-lo breve e fácil de ler. Projetos com documentação de alta qualidade são muito mais bem sucedidos.

Mantenha pacotes pequenos

Ao criar pacotes Yarn, você é incentivado a mantê-los pequenos e simples. Quebre pacotes grandes em vários pacotes menores, se tiver sentido fazer assim. Isso é altamente recomendado, já que Yarn é capaz de instalar centenas, ou até milhares, de pacotes de forma muito eficiente.

Muitos pacotes pequenos são um grande modelo de gerenciamento de pacotes. Muitas vezes isso leva a menores tamanhos de download, já que você não está agrupando dependências massivas e usando apenas um pequeno pedaço do pacote.

Você deve considerar também o conteúdo do seu pacote. Certifique-se de que não está distribuindo acidentalmente seus testes ou quaisquer outros arquivos que não sejam necessários para o uso do seu pacote (scripts de compilação, imagens, etc).

Também tenha cuidado com os pacotes que você está dependendo, prefira dependências pequenas, a menos que você tenha uma boa razão para fazer o contrário. Certifique-se de que não está acidentalmente dependendo de algo massivo.

Publicando um Pacote →