Criando um Pacote

Um pacote é uma pasta com um punhado de código e um arquivo package.json, o qual o Yarn usa para consultar informações sobre o seu pacote.

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

Nota: Se quiser seguir este guia, você deve antes ter o git e o Yarn instalados.

Criando seu primeiro pacote

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

git init meu-novo-projeto
cd meu-novo-projeto
yarn init

Isso vai criar um novo repositório git, fazer o terminal entrar na pasta recém-criada, e então abrir um formulário interativo para criar um novo projeto do Yarn com as seguintes perguntas:

name (meu-novo-projeto):
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 dar Enter para usar o valor padrão ou deixar em branco.

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

package.json

Agora você deve ter um arquivo package.json contendo algo assim:

{
  "name": "meu-novo-projeto",
  "version": "1.0.0",
  "description": "Descrição do meu novo projeto.",
  "main": "index.js",
  "repository": {
    "url": "https://exemplo.com/seu-usuario/meu-novo-projeto",
    "type": "git"
  },
  "author": "Seu Nome <voce@exemplo.com.br>",
  "license": "MIT"
}

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

  • name é o identificador do seu pacote. Se for publicá-lo no registro global, você precisa ter certeza que ele é único.
  • version é a versão, compatível com o formato semver, do seu pacote. Você pode publicar um pacote quantas vezes quiser, contanto que sejam publicadas 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 o 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 dele, para poderem contribuir com ele.
  • 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": "meu-novo-projeto",
  "...": "...",
  "keywords": ["legal", "útil", "rapido"],
  "homepage": "https://site-do-projeto.com",
  "bugs": "https://github.com/voce/meu-novo-projeto/issues",
  "contributors": [
    "Seu Amigo <email-dele@exemplo.com> (http://site-dele.com)",
    "Outro Amigo <outro-email@exemplo.com> (https://outro-site.org)"
  ],
  "files": ["index.js", "lib/*.js", "bin/*.js"],
  "bin": {
    "cli-do-meu-novo-projeto": "bin/cli-do-meu-novo-projeto.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 um seu site que informa sobre o pacote com uma introdução, documentação e links para recursos adicionais.
  • bugs é uma url que indica aos usuários do seu pacote para onde ir caso eles descubram um problema com seu pacote.
  • contributors é uma lista de colaboradores do seu pacote. Se existirem outras pessoas envolvidas no seu projeto, elas podem ser listadas aqui.
  • files é uma lista de arquivos que devem ser incluídos no seu pacote quando publicado e instalado. Se não especificado, o Yarn vai incluir todos os arquivos.
  • bin é um mapeamento de comandos cli (executáveis) para o Yarn criar para o pacote ao instalá-lo.

Para uma lista completa de todos os campos do package.json e mais detalhes sobre cada campo acima, veja a documentação do package.json.

Licenciamento e código aberto

Pacotes Yarn são geralmente incentivados a ser de código aberto. No entanto, é importante observar que apenas publicar pacotes por aí não vai torná-los de fato projetos de código aberto.

Para o seu código ser aberto, ele precisa ter uma licença de código aberto. Existem várias opções de licenças de código aberto, e algumas das mais comuns são:

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

Quando você escolher 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 deixar bem claro qual é o licenciamento ou se não é licenciado.

Compartilhamento de código

Você provavelmente vai querer que os usuários do seu pacote possam acessar o código fonte e tenham um canal para informar problemas. Existem alguns sites populares para você hospedar seu código:

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

{
  "homepage": "https://github.com/usuario/meu-novo-projeto",
  "bugs": "https://github.com/usuario/meu-novo-projeto/issues",
  "repository": {
    "url": "https://github.com/usuario/meu-novo-projeto",
    "type": "git"
  }
}

Documentação

Apesar de você já poder publicar seu pacote, o mais ideal é que ele tenha uma documentação e que você a elabore antes de publicá-lo. O mínimo que você deveria escrever é um arquivo README.md na pasta raiz do seu projeto. Nele, você deve apresentar e descrever o projeto e documentar a API pública dele.

O segredo para uma boa documentação é que ela dê aos seus usuários todas as informações que eles vão precisar para começar a trabalhar com ele e manter seu uso contínuo. Pense nas perguntas e dúvidas que alguém que não saiba nadinha sobre seu projeto teria. 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. Divida pacotes grandes em vários pacotes menores, se tiver sentido fazer assim. Isso é fortemente recomendado, já que o Yarn é capaz de instalar centenas - ou até milhares - de pacotes de forma muito eficiente.

Manter vários pacotes pequenos é um ótimo 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 está usando apenas um pequeno pedaço do pacote.

Você também deve prestar atenção no conteúdo do seu pacote. Tenha certeza 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 muito pesado.