Como publicar um pacote no npm: um guia passo a passo

Publicar pacotes no NPM (Node package manager) não é apenas uma forma de compartilhar seu trabalho com outros desenvolvedores, mas também de se destacar na comunidade de desenvolvimento. Imagine criar uma solução reutilizável que possa ser integrada a diversos projetos pelo mundo todo, economizando tempo e esforço de outros programadores.

Neste artigo, você aprenderá, passo a passo, como configurar, publicar e manter seu próprio pacote no NPM, tornando suas contribuições acessíveis e aumentando sua visibilidade como desenvolvedor.

Pré-requisitos

Antes de começar, certifique-se de que tenha:

• O NPM instalado. Você pode baixá-lo em nodejs.org ou utilizar o NVM (Node version manager).
• Uma conta criada no npmjs.com

Execute os comandos abaixo no terminal para verificar que a instalação do Node.js e do NPM foram bem-sucedidas.

node -v
npm -v

Se a instalação estiver correta, o terminal exibirá a versão de cada.
O resultado será parecido com o abaixo:

$ v20.18.0 # node -v
$ 10.8.2 # npm -v

Configurando o projeto

Comece criando uma pasta com o nome que você deseja para o pacote. No meu caso escolhi "string-reverser-jm".

mkdir string-reverser-jm # cria a pasta via terminal
cd string-reverser-jm # acessa a pasta via terminal

Inicialize o NPM:

npm init

Ao executar o comando acima, o terminal fará algumas perguntas para criar o arquivo package.json.
Segue explicação de cada item que precisamos ter preenchido.

• name: Um identificador exclusivo para o pacote.
• version: Utilize versionamento semântico para indicar alterações.
• description: Uma breve explicação sobre o que o pacote faz.
• main: O arquivo do ponto de entrada, por exemplo, index.js.
• keywords: Palavras-chave para categorizar e facilitar que outros desenvolvedores encontrem o pacote.
• author: Adicione detalhes relevantes do autor.
• license: A licença define como o código pode ser usado, modificado e distribuído por outros. A licença mais comum é a MIT, que é permissiva e permite grande liberdade de uso, desde que seja fornecido o aviso de direitos autorais original.

Caso termine as perguntas e o NPM tenha criado o arquivo sem alguma dessas informações, abra o arquivo criado em um editor e adicione o que estiver faltando.

Exemplo:

{
  "name": "string-reverser-jm",
  "version": "1.0.0",
  "description": "A simple utility to reverse strings, useful for demonstrations and small projects.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"No test specified\" && exit 1"
  },
  "author": "Juliana Macedo <contact@starcoders.info> (https://www.starcoders.info)",
  "keywords": [
    "string",
    "reverse",
    "utility"
  ],
  "license": "MIT"
}

Escrevendo o código

Crie o arquivo index.js na raiz do projeto.

function reverseString(str) {
  if (typeof str !== "string") {
    throw new TypeError("Expected a string as input");
  }
  return str.split("").reverse().join("");
}

module.exports = reverseString;

Testando o pacote

Para testar o pacote antes de publicá-lo, vamos utilizar o comando npm link

No diretório do pacote, execute o comando:

npm link

No projeto onde deseja testar o pacote, execute o comando:

npm link string-reverser-jm

Importe e use o pacote no seu projeto de teste para garantir que está funcionando:

const reverseString = require("string-reverser-jm");
console.log(reverseString("Hello, world!")); // Output: '!dlrow ,olleH'

Para remover os links criados, basta executar o comando npm unlink string-reverser-jm no diretório do projeto de teste e depois npm unlink no diretório do pacote.

Preparando o pacote para publicação

Primeiro, crie um repositório Git para o pacote e vincule-o ao NPM. Isso aumenta a transparência e confiança ao disponibilizar o código-fonte, facilita colaborações e contribuições da comunidade, e permite automação com CI/CD para um gerenciamento e manutenção mais eficientes.

Para vincular ao NPM, copie o endereço https do repositório e adicione-o ao package.json:

{
  "name": "string-reverser-jm",
  "version": "1.0.0",
  "description": "A simple utility to reverse strings, useful for demonstrations and small projects.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"No test specified\" && exit 1"
  },
  "author": "Juliana Macedo <contact@starcoders.info> (https://www.starcoders.info)",
  "keywords": [
    "string",
    "reverse",
    "utility"
  ],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/Jullymac/string-reverser-jm.git"
  }
}

• .gitignore: Crie um arquivo .gitignore para excluir pastas e arquivos, como node_modules e .env, do versionamento.
• .npmignore: Crie um arquivo .npmignore para especificar quais arquivos e pastas não devem ser incluídos no pacote NPM.
• README.md: Crie um arquivo com informações sobre o pacote.

Publicando o pacote

Faça login no NPM usando seus dados de acesso:

npm login

Execute o comando abaixo para publicar o pacote:

npm publish

Pronto, em breve o pacote estará disponível no registro do NPM!
https://www.npmjs.com/package/string-reverser-jm

Atualizando o pacote

Ao fazer atualizações ou correções de bugs, aumente o número da versão no package.json de acordo com o versionamento semântico utilizando um dos comandos abaixo:

npm version patch   # Para correções
npm version minor   # Para novas funcionalidades que são compatíveis com versões anteriores
npm version major   # Para alterações significativas, que podem não ser compatíveis com versões anteriores

E depois, publique a versão atualizada:

npm publish

Problemas frequentes:

• Package Name Already Taken: Se a publicação falhar porque já existe um pacote com o mesmo nome, escolha outro nome, um que ainda não tenha sido usado.
• Authentication Errors: Certifique-se que está logado e tem todas as permissões necessárias para publicar.
• Version Conflicts: Se tentar publicar sem atualizar o número da versão, o NPM rejeitará sua publicação. Use npm version para aumentar a versão.