Artigo original: How to make a beautiful, tiny npm package and publish it
Você não vai acreditar; é muito fácil!
Se você já criou muitos módulos do npm, pode pular essa seção. Se não, vamos fazer uma rápida introdução.
Versão abreviada
Um módulo do npm necessita apenas de um arquivo package.json com as propriedades name e version.
Olá!
Aí está você, apenas um pequeno elefante com a vida toda pela frente. Você não é um mestre em fazer pacotes do npm, mas adoraria saber como, certo? Todos os grandes elefantes andam por aí com suas patas gigantes, fazendo pacotes após pacotes. Você pode pensar:
"Não consigo competir com isso".
Bem, estou aqui para dizer para você que você consegue! Não precisa duvidar da sua capacidade.
Vamos começar!
Você não é um elefante
Entenda o que eu disse como uma metáfora.
Você já se perguntou como elefantes bebês são chamados?
Com certeza, já. Um elefante bebê é um "bebê elefante", oras.
Eu acredito em você
A autossabotagem é real. Acaba ocorrendo que as pessoas deixam de fazer coisas muito legais. Você acha que você não será bem-sucedido. Então, você acaba não fazendo nada, mas exalta as pessoas que fazem coisas incríveis. Isso é muito irônico. Por isso, vou mostrar para você o menor módulo npm possível.
Em breve, você terá várias ideias de módulos npm ao seu alcance, código reutilizável até onde os olhos podem ver – tudo isso sem truques e sem instruções complexas.
As instruções complexas
Eu prometi que eu não usaria instruções complexas, mas usei. Elas, porém, não são tão complexas assim. Você vai me perdoar um dia.
Passo 1: conta do npm
Você vai precisar de uma. É parte do acordo. Crie a conta aqui.
Passo 2: login
Você fez a conta do npm? Já fez? Legal. Também vou assumir que você sabe usar linha de comando/console etc (textos em inglês). Eu vou chamar de terminal a partir de agora. Aparentemente, há uma diferença.
Vá no terminal e escreva:
npm adduserVocê também pode usar o comando:
npm loginEscolha o comando que agrade a você.
Você receberá uma mensagem pedindo seu nome de usuário, senha e e-mail.
A mensagem será parecida com esta:
Logged in as bamblehorse to scope @username on https://registry.npmjs.org/.Vamos em frente!
Hora de fazer um pacote
Primeiramente, precisamos de uma pasta para colocar nosso código. Crie uma pasta da maneira que se sentir confortável. Eu vou chamar o meu pacote de tiny (palavra em inglês para minúsculo) porque o pacote será, de fato, muito pequeno. Eu adicionei alguns comandos de terminal para aqueles que não estão familiarizados com eles.
md tinyNessa pasta, vamos precisar de um arquivo package.json. Se você já usa Node.js, já viu esse arquivo antes. É um arquivo JSON que inclui informações sobre o seu projeto e possui uma infinidade de opções diferentes. Neste tutorial, vamos focar apenas em duas delas.
cd tiny && touch package.jsonQual deve ser o tamanho do pacote?
Muito pequeno.
Todos os tutoriais sobre fazer um pacote npm, inclusive o da documentação oficial, dizem para você adicionar determinados campos no seu package.json. Vamos tentar publicar nosso pacote com o mínimo possível até ele funcionar. Como se fosse um TDD para um pacote do npm mínimo.
Observação: eu estou mostrando isso para demonstrar que fazer um pacote do npm não precisa ser complicado. Para ser útil para a comunidade em geral, um pacote precisa de algumas coisas a mais – e vamos abordar isso mais adiante no artigo.
Publicação: primeira tentativa
Para publicar o seu pacote do npm, você deve executar um comando bem conveniente: npm publish.
Então, temos um package.json vazio na nossa pasta e vamos fazer uma tentativa:
npm publishOpa!
Recebemos um erro:
npm ERR! file package.json
npm ERR! code EJSONPARSE
npm ERR! Failed to parse json
npm ERR! Unexpected end of JSON input while parsing near ''
npm ERR! File: package.json
npm ERR! Failed to parse package.json data.
npm ERR! package.json must be actual JSON, not just JavaScript.
npm ERR!
npm ERR! Tell the package author to fix their package.json file. JSON.parseO npm não gostou muito do seu pacote.
Faz sentido.
Publicação: segunda tentativa
Vamos dar um nome para o nosso pacote no arquivo package.json:
{
"name": "@bamblehorse/tiny"
}Você deve ter percebido que eu adicionei meu username do npm no começo.
Por que fazer isso?
Usando o nome @bamblehorse/tiny ao invés de apenas tiny, criamos um pacote sob o escopo do nosso username. Isso é chamado de scoped package (em português, pacote com escopo). Isso nos permite usar nomes curtos que talvez já foram usados. Por exemplo, o pacote tiny já existe no npm.
Você já deve ter visto isso em bibliotecas populares como a do framework Angular, da Google. Eles possuem alguns scoped packages, como @angular/core e @angular/http.
Bem legal, não?
Vamos tentar publicar uma segunda vez:
npm publishO erro é menor dessa vez – tivemos um progresso.
npm ERR! package.json requires a valid "version" fieldCada pacote do npm precisa de uma versão para que os desenvolvedores saibam se eles podem atualizar com segurança para uma nova versão do nosso pacote sem quebrar o resto do código deles. O sistema de versionamento do npm é chamado de SemVer, que significa Semantic Versioning (em português, versionamento semântico).
Não se preocupe muito em entender os nomes mais complexos de versão, mas aqui está um resumo de como os mais básicos funcionam:
Dado um número de versão MAJOR.MINOR.PATCH, incremente o:
1. MAJOR quando você faz mudanças incompatíveis na API.
2. MINOR quando você adiciona uma funcionalidade de modo compatível com a versão anterior, e
3. PATCH quando você conserta erros de maneira compatível com a última versão.
Rótulos adicionais para pré-lançamento e metadados de build estão disponíveis como extensões do formato MAJOR.MINOR.PATCH.
https://semver.org
Publicando: terceira tentativa
Vamos colocar no nosso package.json a versão: 1.0.0 – o primeiro lançamento major.
{
"name": "@bamblehorse/tiny",
"version": "1.0.0"
}Vamos publicar!
npm publishAh, droga.
npm ERR! publish Failed PUT 402
npm ERR! code E402
npm ERR! You must sign up for private packages : @bamblehorse/tinyPermita-me explicar.
Scoped packages são automaticamente publicados de maneira privada, pois, além de serem úteis para usuários únicos como nós, eles também são utilizados por empresas para compartilhar código entre projetos. Se tivéssemos publicado um pacote normal, nossa jornada teria acabado aqui.
Tudo que precisamos mudar é dizer para o npm que, na verdade, queremos que todo mundo possa usar esse módulo – não o manter trancado nos cofres deles. Portanto, executamos o seguinte comando:
npm publish --access=publicDe repente, o sucesso!
+ @bamblehorse/tiny@1.0.0Recebemos um sinal de adição, o nome do nosso pacote e a versão.
Conseguimos — estamos no clube do npm.
Estou animado. Você deve estar animado também.
Você viu?
npm loves you (em português, o npm ama você)
Que fofo!
A primeira versão está disponível no npm!
Seguindo em frente
Se quisermos ser levados a sério como desenvolvedores e se quisermos que nosso pacote seja usado, precisaremos mostrar o código para as pessoas e dizer para elas como elas devem usar. Em geral, fazemos isso colocando nosso código em algum lugar público e adicionando um arquivo readme.
Também precisamos de algum código. É verdade, não temos código ainda.
O Github é um ótimo lugar para colocar o seu código. Vamos fazer um novo repositório.
README!
Eu me acostumei a escrever arquivos README (do inglês "read me" – em português, leia-me) ao invés de readme. Você não tem que fazer isso mais. É uma convenção divertida. Vamos adicionar algumas badges descoladas do shields.io para as pessoas saberem que somos superlegais e profissionais. Aqui está uma que permite as pessoas saberem a versão atual do nosso pacote:
A próxima badge é interessante. Ela falhou porque não temos nenhum código, na verdade. Deveríamos, realmente, escrever um pouco de código...
Licença para programar
O título é definitivamente uma referência a James Bond. Na verdade, eu me esqueci de adicionar uma licença. Uma licença permite que as pessoas saibam em quais situações elas podem usar seu código. Há várias licenças diferentes.
Existe uma página legal chamada insights em todo repositório do GitHub onde você pode checar várias estatísticas – incluindo os padrões da comunidade para o projeto. Vou adicionar minha licença por lá.
Então, você vai para esta página:
O código
Ainda não temos um código. Isso é um pouco constrangedor.
Vamos adicionar o código agora antes que percamos toda a credibilidade.
module.exports = function tiny(string) {
if (typeof string !== "string") throw new TypeError("Tiny wants a string!");
return string.replace(/\s/g, "");
};Aí está. Uma função minúscula (do inglês, tiny) que remove todos os espaços de uma string.
Então, tudo que um pacote do npm exige é um arquivo index.js. Esse é o ponto de entrada do seu pacote. Você pode fazer isso de diferentes maneiras à medida que o seu pacote fica mais complexo. Por agora, porém, isso é tudo de que precisamos.
Já chegamos lá?
Estamos bem perto. Provavelmente, deveríamos atualizar nosso package.json minimalista e adicionar algumas instruções ao nosso readme.md. Senão, ninguém saberia como usar nosso belíssimo código.
package.json
{
"name": "@bamblehorse/tiny",
"version": "1.0.0",
"description": "Removes all spaces from a string",
"license": "MIT",
"repository": "bamblehorse/tiny",
"main": "index.js",
"keywords": [
"tiny",
"npm",
"package",
"bamblehorse"
]
}Adicionamos:
- description: uma descrição curta do pacote
- repository: compatível com o GitHub — então, você pode escrever username/repo
- license: a licença da MIT, neste caso
- main: o ponto de entrada do pacote, relativo à pasta raiz
- keywords: uma lista de palavras-chave usadas para descobrir seu pacote em uma pesquisa no npm.
readme.md
@bamblehorse/tiny
Removes all spaces from a string.
Install
$ npm install @bamblehorse/tiny
Usage
const tiny = require("@bamblehorse/tiny");
tiny("So much space!");
//=> "Somuchspace!"
tiny(1337);
//=> Uncaught TypeError: Tiny wants a string!
// at tiny (<anonymous>:2:41)
// at <anonymous>:1:1
Adicionamos instruções sobre como instalar e usar o pacote. Legal!
Se você quer um bom modelo para seu readme, é só conferir pacotes populares na comunidade de código aberto (do inglês, open source) e usar os formatos deles para começar.
Conclusão
Vamos publicar nosso pacote espetacular.
Versão
Primeiramente, vamos atualizar a versão com o comando npm version.
Esse é um lançamento major. Então, escrevemos:
npm version majorO que nos retorna:
v2.0.0Publique!
Vamos rodar nosso novo comando favorito:
npm publishEstá pronto:
+ @bamblehorse/tiny@2.0.0Coisas legais
A Package Phobia dá um ótimo resumo do seu pacote do npm. Você também pode verificar cada arquivo em sites como o Unpkg.
Agradecimento
Foi uma jornada maravilhosa que acabamos de fazer juntos. Espero que você tenha aproveitado tanto quanto eu. Se puder, deixe uma estrela para o pacote que nós acabamos de criar aqui:
★ Github.com/Bamblehorse/tiny ★
