Automatizar a publicação de pacotes NPM com ações do GitHub melhora a qualidade do código, garante versões consistentes e facilita a colaboração no desenvolvimento. Este guia ensina o processo completo, incluindo configurações de CI/CD e práticas recomendadas para evitar a inclusão de arquivos desnecessários no pacote final. Aprenda a usar testes automáticos, configurar repositórios do GitHub e gerenciar tokens de acesso para a publicação.
Automatizar a publicação do seu pacote NPM usando ações do GitHub é uma maneira eficaz de garantir que cada lançamento passe por um controle de qualidade rigoroso. Neste guia abrangente, você aprenderá como implementar CI/CD para seu pacote NPM, garantindo que cada novo lançamento no GitHub desencadeie testes, atualize a versão do pacote e publique automaticamente uma versão limpa. Essa automação não só economiza tempo, mas também minimiza erros e melhora a colaboração entre a equipe de desenvolvimento, permitindo um fluxo de trabalho mais eficiente e organizado.
Introdução à Automação da Publicação de Pacotes NPM
A automação da publicação de pacotes NPM é um aspecto fundamental no desenvolvimento de software moderno. Isso se deve à necessidade de implementar processos que garantam agilidade, qualidade e eficiência no ciclo de vida do desenvolvimento.
Publicar manualmente pacotes pode ser uma tarefa repetitiva e sujeita a erros, especialmente à medida que os projetos crescem e envolvem múltiplos colaboradores. A automação permite que os desenvolvedores se concentrem em escrever código, enquanto as tarefas operacionais são geridas por ferramentas como o GitHub Actions.
O GitHub Actions facilita a criação de fluxos de trabalho que são ativados por eventos, como lançamentos de novas versões. Isso assegura que, a cada nova subida de código, um conjunto de ações seja executado automaticamente, como a execução de testes e a publicação do pacote atualizado no registro do NPM, tudo sem intervenção manual.
Ao ativar esses fluxos de trabalho, é possível garantir que todas as versões publicadas atendam a padrões de qualidade estabelecidos, uma vez que cada lançamento passa por um controle de qualidade rigoroso. Dessa forma, é essencial que as práticas de automação sejam implementadas desde os estágios iniciais do desenvolvimento para maximizar os benefícios ao longo do ciclo de vida do software.
Neste contexto, entender como configurar essas automações, desde a preparação do ambiente até os detalhes da execução dos pipelines, é crucial para qualquer desenvolvedor que deseje implementar uma estratégia de publicação eficiente e profissional.
Por que Automatizar a Publicação de Pacotes?
A automação na publicação de pacotes NPM traz diversos benefícios significativos. Um dos principais motivos para considerar essa prática é a segurança da qualidade. Ao implementar testes automáticos que são executados antes de cada publicação, você assegura que somente versões que passaram por um controle rigoroso cheguem aos usuários finais. Se algo não está funcionando corretamente nos testes, a nova versão não será lançada, evitando assim a propagação de erros.
Outro aspecto importante é o gerenciamento consistente de versões. Com a automação, a versão publicada do pacote corresponde sempre à tag de lançamento no GitHub, o que elimina a confusão sobre qual versão está em uso e previne problemas de versionamento que podem surgir ao atualizar pacotes nas dependências de projetos.
A automação também cria um ambiente de colaboração sem fricções. Quando os colaboradores submetem seu código, eles não precisam se preocupar com permissões especiais ou processos complexos de publicação. Em vez disso, uma simples ação de criar um novo lançamento é suficiente para que o pipeline faça todo o trabalho, desde os testes até a publicação, tornando o processo muito mais eficiente.
Título
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut elit tellus, luctus nec ullamcorper mattis, pulvinar dapibus leo.
Por último, a automação reduz o tempo e o esforço manual envolvidos na publicação. Isso é particularmente benéfico em projetos grandes onde várias alterações cortadas são feitas com frequência. Com uma configuração de CI/CD bem estabelecida, a equipe pode se concentrar em funcionalidades e melhorias, sabendo que o processo de publicação será tratado automaticamente.
Pré-requisitos para a Automação
Para configurar a automação na publicação de pacotes NPM, é essencial atender a alguns pré-requisitos. O primeiro deles é ter o Node.js e o npm instalados em seu ambiente de desenvolvimento. Essas ferramentas são fundamentais, pois o npm é o gerenciador de pacotes para o Node.js, permitindo que você instale e gerencie dependências do seu projeto.
Após a instalação, você pode confirmar se tudo está funcionando corretamente executando os seguintes comandos no terminal:
node -v
npm -vCaso os comandos retornem a versão instalada, você está pronto para seguir em frente.
Outro requisito é ter uma conta no GitHub e um repositório onde seu código será mantido. Isso é essencial porque as ações do GitHub, que serão utilizadas para automatizar o processo, são executadas diretamente a partir deste ambiente. Uma vez que o repositório esteja criado, você poderá armazenar todo o seu código-fonte e configurar workflows para a automação.
Além do GitHub, é necessário ter uma conta no npm. Esta conta permitirá que você publique seus pacotes na plataforma NPM. Após criar a conta, é importante gerar um token de acesso. Este token é um código secreto que permite que o GitHub acesse sua conta do npm de forma segura durante o processo de publicação.
Por fim, adicione o token de acesso como um segredo em seu repositório do GitHub. Essa configuração é crucial para garantir que as ações de publicação tenham as permissões necessárias para executar tarefas na sua conta do npm enquanto mantém a segurança dos seus dados.
Passo a Passo para Configurar o Projeto
Configurar o projeto para automação na publicação de pacotes NPM envolve alguns passos simples. Vamos detalhar cada um deles a seguir:
1. Inicialize o Projeto
Comece criando um novo diretório para o seu projeto e navegue até ele usando o terminal:
mkdir alphanumeric-validator
cd alphanumeric-validatorEm seguida, execute o comando abaixo para inicializar um novo projeto e gerar um arquivo package.json padrão:
npm init -yEsse comando cria um arquivo package.json com as configurações padrão, onde você poderá ajustar as informações do seu pacote posteriormente.
2. Atualize o arquivo package.json
Agora, você deve editar o package.json para incluir informações importantes sobre o seu projeto, como o nome, versão e descrição. O conteúdo do arquivo pode ficar semelhante a este:
{
"name": "alphanumeric-validator",
"version": "1.0.0",
"description": "Validates if a string is alphanumeric",
"main": "index.js",
"scripts": {
"test": "jest"
},
"keywords": ["alphanumeric", "validator"],
"author": "Seu Nome",
"license": "ISC"
}Lembre-se de substituir o autor pelo seu nome e ajustar qualquer outra informação que você achar necessária.
3. Implemente a função Validadora
Crie um arquivo index.js que exporte uma função para validar se uma string é alfanumérica. O conteúdo do arquivo pode ser:
// index.js
function isAlphaNumeric(str) {
return /^[a-z0-9]+$/i.test(str);
}
module.exports = isAlphaNumeric;Com isso, a função isAlphaNumeric será disponível para uso em outros arquivos e testes.
4. Crie e Execute os Testes Localmente
É importante que você configure testes para garantir que seu código esteja funcionando corretamente. Primeiro, instale o Jest como uma dependência de desenvolvimento:
npm install --save-dev jestDepois, crie uma pasta tests e adicione um arquivo de teste chamado index.test.js com o seguinte código:
// tests/index.test.js
const isAlphaNumeric = require('../index');
test('valid alphanumeric strings return true', () => {
expect(isAlphaNumeric('abc123')).toBe(true);
});
test('invalid strings return false', () => {
expect(isAlphaNumeric('abc123!')).toBe(false);
});Em seguida, você pode executar os testes usando:
npm testSe todos os testes passarem, seu código está funcionando conforme o esperado.
5. Exclua Módulos do Git
Para evitar que a pasta node_modules seja rastreada pelo Git, crie um arquivo .gitignore no diretório raiz do seu projeto e adicione o seguinte:
node_modulesDessa forma, a pasta que contém as dependências não será incluída nas versões do seu código no repositório.
6. Exclua Testes do Pacote Publicado
Para manter o pacote limpo e liberar espaço, é importante que os arquivos de teste não sejam incluídos na publicação final. Para isso, crie um arquivo .npmignore no diretório raiz e adicione os seguintes conteúdos:
__tests__
*.test.jsAssim, quando for feito o comando de publicação, esses arquivos não serão enviados ao registro do NPM.
Seguindo esses passos, você terá seu projeto preparado para automação de publicação, garantindo qualidade e eficiência em todo o processo.
Executando Testes Locais
Executar testes localmente é uma parte fundamental do desenvolvimento de software, pois isso ajuda a garantir que seu código esteja funcionando corretamente antes de ser publicado. Aqui estão os passos detalhados para executar testes locais em seu projeto:
1. Instale o Jest
Jest é um framework de testes popular para JavaScript que facilita a criação e execução de testes. Para instalá-lo, você deve utilizar o seguinte comando:
npm install --save-dev jestEste comando adicionará o Jest como uma dependência de desenvolvimento no seu projeto, permitindo que você o utilize apenas para testes sem afetar o seu pacote final.
2. Crie um Arquivo de Teste
Após a instalação, o próximo passo é criar um arquivo de teste. Crie uma nova pasta chamada tests no diretório do seu projeto. Dentro dessa pasta, crie um arquivo chamado index.test.js.
No arquivo index.test.js, você deve incluir testes para a função que deseja validar. Aqui está um exemplo de como esse arquivo pode ser estruturado:
// tests/index.test.js
const isAlphaNumeric = require('../index');
test('valid alphanumeric strings return true', () => {
expect(isAlphaNumeric('abc123')).toBe(true);
});
test('invalid strings return false', () => {
expect(isAlphaNumeric('abc123!')).toBe(false);
});Neste exemplo, dois testes são definidos: um que verifica se uma string alfanumérica válida retorna verdadeiro e outro que valida uma string inválida.
3. Execute os Testes
Com seus testes configurados, você pode agora executá-los localmente. Para isso, utilize o seguinte comando no terminal:
npm testEsse comando executará todos os testes definidos no seu projeto. O Jest irá informar no terminal quantos testes foram executados, quantos passaram e quantos falharam. Se todos os testes forem bem-sucedidos, você verá uma saída indicando que não houve falhas.
Esse processo de execução de testes locais é crucial para identificar problemas antes que o código seja publicado. Isso não apenas ajuda a garantir que seu código funcione como esperado, mas também aumenta a confiabilidade do seu pacote NPM final.
Excluindo Módulos do Git
Manter o repositório do Git limpo e organizado é vital para o bom gerenciamento do seu projeto. Um dos passos importantes nesse sentido é excluir a pasta node_modules, que contém todas as dependências instaladas do seu projeto. Aqui estão os passos para fazer isso:
1. Crie um Arquivo .gitignore
O primeiro passo para impedir que a pasta node_modules seja rastreada pelo Git é criar um arquivo chamado .gitignore. Esse arquivo deve ser colocado no diretório raiz do seu projeto.
Para criar o arquivo, você pode usar o seguinte comando no terminal:
touch .gitignore2. Adicione node_modules ao .gitignore
Depois de criar o arquivo .gitignore, é necessário adicionar a linha node_modules a ele. Isso informa ao Git para ignorar essa pasta em todos os commits futuros. Você pode abrir o arquivo com um editor de texto e adicionar o seguinte conteúdo:
node_modulesSalve o arquivo após fazer essa alteração.
3. Remova node_modules do Controle de Versão
Se a pasta node_modules já estava sendo rastreada pelo Git antes de você criar o .gitignore, será necessário removê-la do controle de versão. Para fazer isso, utilize o seguinte comando no terminal:
git rm -r --cached node_modulesEsse comando removerá a pasta do índice do Git, mas não a excluirá do seu sistema de arquivos local.
4. Faça um Commit das Alterações
Depois de ter modificado o arquivo .gitignore e removido a pasta node_modules do controle de versão, você deve fazer um novo commit para registrar essas alterações. Utilize os seguintes comandos no terminal:
git add .gitignore
git commit -m "Remover node_modules e adicionar ao .gitignore"Dessa forma, você terá realizado a exclusão da pasta do repositório Git, ajudando a manter seu projeto mais leve e organizado.
Publicando Manualmente no NPM
Publicar seu pacote no NPM (Node Package Manager) é uma etapa crucial para compartilhar seu trabalho com a comunidade. Aqui estão os passos a seguir para realizar uma publicação manualmente:
1. Verifique o package.json
Antes de enviar seu pacote, é importante garantir que todas as informações no seu arquivo package.json estejam corretas. Isso inclui o nome do pacote, versão, descrição, autor e licenciamento. O nome do seu pacote deve ser único no NPM, caso contrário, você não conseguirá publicá-lo.
2. Faça Login na sua Conta do NPM
Para publicar um pacote, você precisa estar autenticado na sua conta do NPM. Se você ainda não fez login, use o seguinte comando no terminal:
npm loginVocê será solicitado a fornecer seu nome de usuário, senha e endereço de email associado à sua conta.
3. Execute o Comando de Publicação
Após verificar o package.json e fazer login, você pode publicar seu pacote usando o comando:
npm publishIsso enviará seu pacote para o registro do NPM. Se tudo estiver configurado corretamente, você verá mensagens de sucesso indicando que a publicação foi concluída.
4. Verifique a Publicação
Após publicar, é essencial confirmar se seu pacote está disponível no NPM. Você pode fazer isso visitando a URL https://www.npmjs.com/package/[seu-nome-do-pacote], substituindo [seu-nome-do-pacote] pelo nome do seu pacote. Verifique se as informações exibidas estão corretas.
5. Atualizando o Pacote
Se você precisar atualizar seu pacote no futuro, lembre-se de alterar a versão no package.json antes de publicar novamente. O NPM usa o versionamento semântico, então, para fazer uma atualização, você deve aumentar a versão de acordo com as mudanças feitas no código.
Esses passos garantem que seu pacote seja publicado no NPM de forma manual, permitindo que outros desenvolvedores possam instalá-lo e utilizá-lo em seus projetos.
Configurando o Workflow de Ações do GitHub
Configurar um workflow de ações do GitHub é uma maneira eficiente de automatizar o processo de publicação do seu pacote NPM. Siga os passos abaixo para definir essa configuração:
1. Crie o Diretório de Ações
O primeiro passo é criar um diretório específico para suas ações. Navegue até o seu repositório e crie a pasta .github/workflows:
mkdir -p .github/workflowsEssa pasta armazenará todos os arquivos de configuração do workflow.
2. Crie o Arquivo de Workflow
Dentro do diretório workflows, crie um arquivo YAML chamado publish.yml. Este arquivo conterá as etapas necessárias para o seu workflow.
A estrutura básica desse arquivo pode ser parecida com a seguinte:
name: Publish to NPM
on:
push:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v2
- name: Set up Node.js
uses: actions/setup-node@v2
with:
node-version: '14'
- name: Install dependencies
run: npm install
- name: Run tests
run: npm test
- name: Publish to NPM
run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
Nesse exemplo, o workflow é acionado em um push para a branch main. Ele realiza uma série de etapas, como verificar o código, configurar o Node.js, instalar dependências, executar testes e, finalmente, publicar no NPM.
3. Adicione o Token de Acesso
Para que o GitHub Actions possa publicar no NPM, é necessário um token de acesso. Vá para as configurações do seu repositório e clique em Secrets. Crie um novo segredo chamado NPM_TOKEN, inserindo o token gerado na sua conta do NPM. Esse token permite que as ações tenham autorização para publicar o pacote.
4. Faça um Push das Alterações
Após configurar o arquivo publish.yml e adicionar o segredo, você deve adicionar e fazer o commit das alterações no seu repositório:
git add .github/workflows/publish.yml
git commit -m "Configurar workflow de publicação"
git push origin mainAgora, sempre que houver um push na branch main, o GitHub Actions executará o workflow automaticamente.
Esses passos permitirão que você configure um workflow eficiente no GitHub Actions, automatizando a publicação do seu pacote NPM sempre que houver atualizações.
Adicionando seu Token NPM ao GitHub
Adicionar seu token NPM ao GitHub é uma etapa essencial para permitir que as ações no GitHub publiquem seu pacote NPM de forma segura. Aqui está um guia passo a passo para realizar essa configuração:
1. Gere um Token de Acesso NPM
Antes de tudo, você precisa obter um token de acesso NPM. Faça login na sua conta NPM através do terminal usando:
npm loginApós logar, você pode gerar um token na sua conta NPM. Acesse as configurações da sua conta em npmjs.com e vá até a seção de Tokens de Acesso. Clique em criação de token e selecione a opção que melhor se adequa ao seu uso (geralmente, a opção de Read and Publish é suficiente).
2. Copie o Token Gerado
Após criar o token, copie-o; você precisará dele para a próxima etapa. Guarde-o em um local seguro, pois ele permite acesso ao seu registro NPM.
3. Acesse Seu Repositório no GitHub
Vá até a página do repositório onde você deseja configurar o acesso NPM. Na parte superior do repositório, clique em Settings (Configurações).
4. Navegue até a Seção de Segredos
Dentro das configurações, localize a seção chamada Secrets na barra lateral esquerda. Clique na opção Actions para adicionar um novo segredo que será utilizado nas ações do GitHub.
5. Adicione um Novo Segredo
Clique em New repository secret. Na caixa de diálogo que aparece, você deve inserir um nome para o seu segredo. Utilize NPM_TOKEN como o nome. Em seguida, cole o token que você copiou anteriormente no campo de valor.
6. Salve o Segredo
Após preencher os campos necessários, clique em Add secret para salvar. Este segredo agora estará disponível para uso em seus workflows de ações do GitHub.
Com esses passos, você terá configurado o token NPM no GitHub, permitindo que seu workflow de ações publique pacotes no registro do NPM de maneira segura e automatizada.
Criando um Novo Lançamento
Criar um novo lançamento no GitHub é uma forma eficaz de marcar versões importantes do seu projeto e compartilhar com os usuários. Siga os passos abaixo para criar um novo lançamento:
1. Acesse Seu Repositório
Primeiro, entre na sua conta do GitHub e navegue até o repositório onde você deseja criar o lançamento. Você pode encontrar sua lista de repositórios na sua página de perfil.
2. Vá até a Aba de Releases
Na página do repositório, clique na aba Releases, que geralmente está localizada na parte superior, logo abaixo do nome do repositório. Essa aba mostra os lançamentos existentes, se houver.
3. Clique em Draft a New Release
Na página de Releases, você verá um botão chamado Draft a new release. Clique nesse botão para iniciar o processo de criação de um novo lançamento.
4. Escolha a Versão e a Branch
Na nova página, escolha a versão do seu lançamento no campo Tag version. Você pode criar uma nova tag ou usar uma existente. Se estiver criando uma nova tag, geralmente deve seguir o formato de versionamento semântico, como v1.0.0. Também é importante selecionar a branch onde o lançamento estará baseado, normalmente main ou master.
5. Adicione um Título e Descrição
Na seção Release title, insira um título descritivo para o seu lançamento. Em seguida, na caixa de Description, forneça detalhes sobre as mudanças ou melhorias incluídas neste lançamento. Você pode usar formatação Markdown para destacar informações importantes.
6. Publique o Lançamento
Depois de preencher todas as informações, você tem a opção de Publish release ou Save draft. Se você estiver pronto para tornar o lançamento público, clique em Publish release. Caso contrário, você pode optar por salvar como um rascunho e finalizá-lo mais tarde.
Após a publicação, o novo lançamento ficará visível na aba de Releases do seu repositório. Os usuários poderão ver as notas do lançamento e baixar a nova versão do seu pacote, se aplicável.
Perguntas Frequentes
O que é a publicação automática de pacotes NPM?
É o processo de usar ferramentas como GitHub Actions para publicar automaticamente pacotes NPM sempre que há uma nova versão.
Por que devo automatizar a publicação do meu pacote NPM?
A automação garante qualidade, gerenciamento consistente de versões e um fluxo de trabalho mais eficiente para a equipe.
Quais são os pré-requisitos para configurar a automação?
Você precisará ter Node.js, npm, uma conta no GitHub e uma conta no npm com um token de acesso.
Como posso rodar testes localmente antes da publicação?
Você pode usar ferramentas como Jest para criar e executar testes durante o desenvolvimento.
O que devo incluir no meu .gitignore?
Inclua o diretório node_modules para evitar que sejam rastreados pelo git.
Como configurar as ações do GitHub para publicação automática?
Crie um arquivo de workflow que defina os passos necessários para verificar o código, instalar dependências, rodar testes e publicar o pacote.
