Como publicar automaticamente seu pacote NPM usando ações do GitHub

Automatizar seu processo de publicação de pacotes npm com integração e entrega contínuas (CI/CD) garante que cada lançamento passe por um portão de qualidade — seu conjunto de testes — antes da publicação. Ao mesmo tempo, você pode controlar exatamente o que acaba no pacote publicado final excluindo arquivos de teste. Neste guia, você aprenderá como configurar CI/CD para um pacote npm simples — um validador alfanumérico — para que cada novo lançamento do GitHub acione testes, atualize a versão do pacote e publique automaticamente um pacote limpo no npm.

Por que automatizar a publicação npm?

A publicação manual do npm pode ser demorada e propensa a erros, principalmente à medida que seu projeto cresce e ganha contribuidores. Ao automatizar o processo, você pode:

• Garanta a qualidade: execute testes automaticamente antes de publicar. Se os testes falharem, a nova versão não será lançada.
• Controle de versão consistente: a versão do pacote publicado sempre corresponde à tag de lançamento.
• Colaboração sem atrito: os colaboradores enviam o código, você cria uma versão e o pipeline faz o resto — não são necessárias permissões especiais do npm.

Pré-requisitos

1. Node.js e npm:
   • Clique aqui se você não tiver o NodeJS e o NPM instalados.
   • Confirme a instalação executando o código abaixo no seu terminal.

 node -v npm -v

2. Conta e repositório do GitHub:
   • Você precisa de um repositório GitHub para armazenar código e executar ações do GitHub.
3. Conta NPM e Token de acesso:
   • Cadastre-se ou faça login em npmjs.com e gere um token de acesso.
   • Adicione o token de acesso como um segredo no seu repositório GitHub para publicação automatizada.

Etapa 1: Configurar o projeto

Criaremos um pacote simples alphanumeric-validator que exporta uma função que verifica se uma string é alfanumérica.

1. Inicializar o Projeto

    mkdir alphanumeric-validator cd alphanumeric-validator npm init -y

2. Atualize package.json conforme necessário. Para o alphanumeric-validator , ficará assim.

 { "name": "alphanumeric-validator", "version": "1.0.0", "description": "Validates if a string is alphanumeric", "main": "index.js", "scripts": { "test": "jest" }, "keywords": ["alphanumeric", "validator"], "author": "Your Name", "license": "ISC" }

3. Implementar o Validador

 // index.js function isAlphaNumeric(str) { return /^[a-z0-9]+$/i.test(str); } module.exports = isAlphaNumeric;

Etapa 2: Adicionar e executar testes localmente

Os testes garantem que você não publique código quebrado.

1. Instalar Jest

    npm install --save-dev jest

2. Criar um arquivo de teste

    mkdir tests

3. Cole o código abaixo no arquivo tests/index.text.js .

    // 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); });

4. Executar testes

    npm test 

Testes passando? Ótimo. Agora, garantiremos que esses testes sejam executados no CI antes da publicação.

Etapa 3: Excluir módulos de nó do Git

Antes de publicar no Github, você quer excluir o node_modules . Você não quer fazer commit node_modules para controle de versão, pois ele contém um grande número de arquivos que podem ser regenerados pelo npm install .

Crie um arquivo .gitignore na raiz do seu projeto:

 echo "node_modules" >> .gitignore

Isso garante que node_modules não seja rastreado pelo git e não seja enviado ao seu repositório.

Etapa 4: Excluir testes do pacote publicado

Embora você execute testes durante o CI, não deseja que os arquivos de teste sejam incluídos no seu pacote npm publicado. Isso mantém o pacote limpo, tem um tamanho de pacote pequeno e garante que apenas os arquivos necessários sejam enviados aos usuários.

Crie um arquivo .npmignore na pasta raiz e adicione os nomes dos arquivos de teste.

 // .npmignore __tests__ *.test.js // captures all files in the directory with a .test.js extension

Isso garante que os arquivos de teste não sejam incluídos quando você executar npm publish .

Etapa 5: hospede seu código no GitHub

1. Crie um novo repositório GitHub:
   • Acesse https://github.com/new e crie um repositório alphanumeric-validator .

2. Empurre seu código

    git init git add . git commit -m "Initial commit" git remote add origin [email protected]:YOUR_USERNAME/alphanumeric-validator.git git push -u origin main 

Etapa 5: Publicação manual inicial no npm

• Antes de iniciar a automação, confirme se seu pacote pode ser publicado — veja aqui.
• Em seguida, adicione o sinalizador --access public para tornar seu pacote público e acessível aos usuários.

 npm login npm publish --access public 

• Visite https://www.npmjs.com/package/alphanumeric-validator para verificar se a versão inicial está ativa.

  
  

Etapa 6: Configurando o fluxo de trabalho do GitHub Actions

Você precisa configurar um fluxo de trabalho que seja executado em cada evento de lançamento para que, quando você criar um novo lançamento (como v1.0.1 ):

• O fluxo de trabalho verifica seu código.
• Instala dependências.
• Executa testes para garantir a qualidade.
• Atualiza package.json para a nova versão da tag release.
• Publica o pacote atualizado no npm sem incluir arquivos de teste.

O arquivo de fluxo de trabalho

Crie .github/workflows/publish.yml :

 name: Publish Package to npm # Trigger this workflow whenever a new release is published on: release: types: [published] # Grant write permissions to the repository contents so we can push version updates permissions: contents: write jobs: publish: runs-on: ubuntu-latest steps: # Step 1: Check out the repository's code at the default branch # This makes your code available for subsequent steps like installing dependencies and running tests. - uses: actions/checkout@v4 with: token: ${{ secrets.GITHUB_TOKEN }} ref: ${{ github.event.repository.default_branch }} # Step 2: Set up a Node.js environment (Node 20.x) and configure npm to use the official registry # This ensures we have the right Node.js version and a proper registry URL for installs and publishing. - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '20.x' registry-url: 'https://registry.npmjs.org' # Step 3: Install dependencies using npm ci # This ensures a clean, reproducible installation based on package-lock.json. - name: Install dependencies run: npm ci # Step 4: Run your test suite (using the "test" script from package.json) # If tests fail, the workflow will stop here and not publish a broken version. - name: Run tests run: npm test # Step 5: Update package.json to match the release tag # The release tag (eg, v1.0.1) is extracted, and npm version sets package.json version accordingly. # The --no-git-tag-version flag ensures npm doesn't create its own tags. # This step keeps package.json's version aligned with the release tag you just created. - name: Update package.json with release tag run: | TAG="${{ github.event.release.tag_name }}" echo "Updating package.json version to $TAG" npm version "$TAG" --no-git-tag-version # Step 6: Commit and push the updated package.json and package-lock.json back to the repo # This ensures your repository always reflects the exact version published. # We use the GITHUB_TOKEN to authenticate and the granted write permissions to push changes. - name: Commit and push version update run: | TAG="${{ github.event.release.tag_name }}" git config user.name "github-actions" git config user.email "[email protected]" git add package.json package-lock.json git commit -m "Update package.json to version $TAG" git push origin ${{ github.event.repository.default_branch }} env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Step 7: Publish the new version to npm # The NODE_AUTH_TOKEN is your npm access token stored as a secret. # npm publish --access public makes the package available to anyone on npm. - name: Publish to npm run: npm publish --access public env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Adicionando seu token NPM ao GitHub

• Visite https://www.npmjs.com/settings/:username/tokens/new (certifique-se de substituir :username pelo seu nome de usuário real)
• Digite o nome, selecione automação para o tipo e gere

• Você será redirecionado para a página de tokens, onde poderá copiar o token.

• Acesse Configurações > Segredos e variáveis > Ações no seu repositório GitHub.

• Clique em Novo Segredo do Repositório e adicione NPM_TOKEN .

  
  

  

Etapa 7: Criando uma nova versão

Digamos que você queira adicionar README.md para a versão v1.0.1 e já o tenha enviado:

1. Rascunhe um novo lançamento:
   • Vá para a seção Releases no seu repositório GitHub. [ https://github.com/username/repo/releases ]
   • Clique em Rascunhar uma nova versão .
   • Defina a "Versão da tag" como v1.0.1.
   • Clique em Publicar versão .

2. Fluxo de trabalho acionado: o evento de liberação é acionado. O fluxo de trabalho,
   • Verifica o código.
   • Instala dependências.
   • Executa testes. Se os testes falharem, o trabalho para e o pacote não será publicado.
   • Se os testes forem aprovados, ele atualiza o package.json para 1.0.1 .
   • Publica a versão 1.0.1 no npm, excluindo arquivos de teste.

3. Verificar no npm: Depois de um momento, visite a página do seu pacote npm para ver a nova versão ativa.

Conclusão

Integrar o GitHub Actions no seu fluxo de trabalho de publicação npm estabelece um ótimo pipeline de CI/CD. Com cada nova versão, uma série abrangente de testes é executada, o package.json é atualizado com a versão correta e um pacote simplificado é publicado no npm — livre de arquivos desnecessários como testes.

Essa abordagem economiza tempo, reduz erros humanos e aumenta a confiabilidade dos seus lançamentos, facilitando para os colaboradores verem seus trabalhos publicados sem problemas.

Agora, basta um único lançamento do GitHub para enviar um pacote totalmente testado e com a versão correta para o registro npm.