Como publicar uma biblioteca de código no NPM

Aprenda a criar uma biblioteca em javascript e publicar no NPM de graça!

Olá meus queridos, tudo bem com vocês?

Neste post vou mostrar como criar uma biblioteca simples em JavaScript e como publicar ela no NPM. Me deparei com esse desafio quando percebi que alguns dos meus códigos poderiam ser migrados para pequenos projetos.

Antes de tudo, se você gosta desse tipo de conteúdo aproveite para assinar nossa newsletter e ficar por dentro de todas as novidades do blog.

O que é uma biblioteca javascript?

Bibliotecas javascript são arquivos que facilitam o processo de desenvolvimento. Se você teve contato com projetos mais complexos, deve ter reparado que algumas soluções utilizam códigos de terceiros. Por exemplo, é muito comum utilizar plugin de slide para fazer carrossel de imagem em sites. Esse plugins são facilitadores, já imaginou ter que desenvolver toda a lógica de slide a cada novo projeto?

Códigos como plugins de slides, utilitários para manipular datas, strings, formulários etc… são publicado no NPM e podem ser usados diretamente no seu projeto.

O que é o NPM?

O NPM (Node Package Manager) é um poderoso gerenciador de pacotes utilizado para administrar as bibliotecas e frameworks utilizados em uma aplicação. O NPM vem junto com a instalação do NodeJS e é usado para compartilhar ferramentas, instalar módulos e gerenciar dependências.

Para desenvolvedores que trabalham diretamente com node é muito importante entender como essa ferramenta funciona.

Por que publicar uma biblioteca no NPM?

Imagine que você está trabalhando em um projeto novo. O protótipo apresenta um slide de fotos, é natural pensar em algum plugin que já faça esse slide de forma fácil. Em muitos casos era comum ter diversas chamadas de CDNs para baixar plugins desse tipo. O que acabava gerando problemas de performance no site. Além disso, era comum ter problemas com versionamentos. Alguns plugins como slick-slider funcionavam com versões específicas do JQuery.

Hoje esse gerenciamento ficou mais fácil com o NPM. Você pode publicar seus arquivos utilitários e gerenciar melhor os pacotes instalados no seu projeto, além de não precisar mais de CDNs. Podemos simplesmente instalar o plugin que queremos utilizar, e no final será gerado um arquivo único, contendo toda a lógica do seu projeto. Dessa forma, o seu site ou app carrega um único arquivo JS.

O que é necessário para publicar uma lib no NPM?

Primeiramente você precisa ter uma conta no npmjs.com. É aqui que vamos “hospedar” nossas bibliotecas. Faça sua conta e em seguida vamos fazer o login via terminal.

Para começar, verifique se o NodeJS  e o NPM estão instalados no seu computador. Você pode fazer isso utilizando o comando abaixo:

$ node -v
  v14.11.0
$ npm -v
  6.14.8

Se tudo estiver certo, você terá como resultado a versão do Node e do NPM.

Fazendo Login Via terminal

Com tudo instalado, agora você precisa fazer login no NPM via terminal. Para isso, digite no terminal o comando “npm login”

$ npm login;
Username: JohnDoe 
Password: ********

Basta digitar o UserName e Senha do seu perfil criado anteriormente. Se tudo correr bem, você terá logado com sucesso.

Construindo uma lib

Fizemos login no NPM e o Node está funcionando corretamente. É hora de começar a trabalhar no nosso projeto. Para esse exemplo, vamos fazer algo bem simples, criaremos uma função que retornar a quantidade de itens em um array.

Para começar, vamos criar uma pasta e navegar até ela utilizando o terminal. Em seguida, precisamos criar o arquivo “package.json”.  Esse arquivo é necessário pois contém metadados sobre o seu projeto. Você pode construir arquivo do zero ou gerar ele de forma automática utilizando o comando “$ npm init”.

{
  "name": "tamanho-do-array",
  "version": "1.0.0",
  "description": "Lib muito boa para pegar o tamanho do seu array 🤔",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "npm",
    "example",
    "basic"
  ],
  "author": "Raphael Corrêa",
  "license": "MIT",
}

Esses metadados ajudam a identificar o seu projeto além de disponibilizar uma base para que os usuários tenham mais detalhes sobre ele. Por exemplo, nosso projeto está na versão “1.0.0”. O nome do nosso projeto é “tamanho-do-array”. entre outras coisas…

Com o package.json criado, o próximo passo é criar o seu arquivo Js principal. No meu caso, vou criar um arquivo chamado index.js com o seguinte conteúdo.

/**
 * @param {array} arry - Aqui você passa o seu array
 * @returns {number} - Retorno da função sera um numero.
 */
export const TamanhoDoArray = (arry) => {
  return arry.length;
};

O arquivo contem uma função que recebe uma array. Essa função retorna o total de itens no seu array. Além disso, ela está sendo exportada, o que permite ser utilizada em outros arquivos usando import do JavaScript.

Também estou utilizando o JSDocs, é quase uma alternativa ao typescript. É perfeito para descrever melhor o seu código e não precisa de nenhuma dependência. Apenas escrever um comentário seguindo essa sintaxe.

Você pode utilizar sua função da seguinte forma em outro arquivo.

import { TamanhoDoArray } from "./index";

const meuArray = [1, 2, 3, 4];

const tamanho = TamanhoDoArray(meuArray);

console.log(tamanho);

Se tudo estiver certo é hora de publicar sua lib no NPM.

Como publicar uma lib no NPM?

Para publicar uma lib no NPM você precisa, antes de tudo, está logado via terminal na sua conta. Também é importante que o nome da sua lib seja único, ou seja, não pode haver uma outra lib com o mesmo nome. Eu não posso publicar uma lib chamada “react-dom” por exemplo.

Só para reforçar… você precisa de:

1. Está logado no NPM via terminal (Veja mais acima como fazer)
2. Ter um projeto com package.json devidamente preenchido e configurado.
3. O nome da sua lib precisa ser único (campo “name” no package.json)

Se tudo estiver certo você pode publicar seu pacote utilizando o comando “npm publish”.

Esse comando fará toda a publicação do seu pacote no NPMJS.com e a partir daí será possível instalar sua lib utilizando “npm install minha-lib” ou “yarn add minha-lib” em qualquer projeto node.

Versionamento da lib

É muito importante manter sua lib atualizada. Lembre-se de atualizar a versão no package.json sempre que publicar algo novo. Caso contrário será gerado um erro na hora da publicação.

O código da versão geralmente tem a seguinte semântica:

version 1.0.0

• Primeiro campo: Major (ou maior) acrescente +1 para alterações que impactam na compatibilidade do código. Ou seja, o que é utilizado na V1 não está disponível na V2 tornando as versões incompatíveis.
• Segundo campo: Minor (ou menor) acrescente +1 para alterações que adicionam mais funcionalidades mantendo a compatibilidade com versões anteriores.
• Terceiro campo: Patch (ou versão de correção) acrescente +1 caso a publicação da sua lib só tenham correções de bugs e erros.

Dicas e boas práticas

Você pode publicar libs para solucionar um problema específico e ajudar a comunidade ou simplesmente organizar os seu projetos pessoais. Independente do motivo é sempre bom seguir boas práticas de desenvolvimento. Aqui eu vou sitar algumas e dar algumas dicas para manter sua lib sempre atualizada e bem escrita.

• Crie um repositório para sua lib: É algo padrão, todo projeto precisa de um repositório para ter um versionamento de código. Dependendo dos seu objetivos, o seu repositório pode ser publico. Dessa forma a comunidade pode sugerir melhorias evoluindo ainda mais o seu projeto.
• Crie uma documentação: Eu sei que essa é uma etapa complicada, mas é importante criar uma documentação clara do seu código. É nela que você expõe detalhes importantes do seu projeto. Quais o métodos e funções estão disponíveis, o que cada coisa faz, que tipo de dado cada função recebe etc… Você pode fazer isso no reademe.md do seu repositório.
• Escreva um código de qualidade: Não basta está funcionando, seu código precisa ser bom o bastante para solucionar um problema e não gera outros.
• Escreva um código fácil de entender: Boas práticas de desenvolvimento e código limpo. Além disso, você pode usar padrões de projetos. Uma ótima lib para isso é o ESlint e o Prettier, ambos combinados automatizam padrões de escrita. Você pode usar também o husky JS para evitar commits de erros ou código fora do padrão.

Conclusão

Utilizar pacotes, módulos ou libs no seu projetos facilita muito o processo de desenvolvimento. Você pode ter soluções para vários problemas da comunidade bem ai no seu computador, esperando ser publicada no NPM.

Facilitar a vida é sempre bom. Espero ter ajuda de alguma forma. Se você gostaria de acrescentar ou mudar algo neste tutorial escreve aii nos comentários.

Outros links

• @devraphaelcorrea
• raphaelcorrea.dev