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: execute testes automaticamente antes de publicar. Se os testes falharem, a nova versão não será lançada. Garanta a qualidade: a versão do pacote publicado sempre corresponde à tag de lançamento. Controle de versão consistente: 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. Colaboração sem atrito: Pré-requisitos Node.js e npm: Clique se você não tiver o NodeJS e o NPM instalados. aqui Confirme a instalação executando o código abaixo no seu terminal. node -v npm -v Conta e repositório do GitHub: Você precisa de um repositório GitHub para armazenar código e executar ações do GitHub. Conta NPM e Token de acesso: Cadastre-se ou faça login em e gere um token de acesso. npmjs.com 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 que exporta uma função que verifica se uma string é alfanumérica. alphanumeric-validator Inicializar o Projeto mkdir alphanumeric-validator cd alphanumeric-validator npm init -y Para o , ficará assim. Atualize package.json conforme necessário. alphanumeric-validator { "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" } 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. Instalar Jest npm install --save-dev jest Criar um arquivo de teste mkdir tests 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); }); 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 . Você não quer fazer commit para controle de versão, pois ele contém um grande número de arquivos que podem ser regenerados pelo . node_modules node_modules npm install na raiz do seu projeto: Crie um arquivo .gitignore echo "node_modules" >> .gitignore Isso garante que não seja rastreado pelo git e não seja enviado ao seu repositório. node_modules 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 na pasta raiz e adicione os nomes dos arquivos de teste. .npmignore // .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 Crie um novo repositório GitHub: Acesse e crie um repositório . https://github.com/new alphanumeric-validator Empurre seu código git init git add . git commit -m "Initial commit" git remote add origin git@github.com: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 para tornar seu pacote público e acessível aos usuários. --access public npm login npm publish --access public Visite para verificar se a versão inicial está ativa. https://www.npmjs.com/package/alphanumeric-validator 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 para a nova versão da tag release. package.json 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 "github-actions@github.com" 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 (certifique-se de substituir pelo seu nome de usuário real) https://www.npmjs.com/settings/:username/tokens/new :username 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 no seu repositório GitHub. Configurações > Segredos e variáveis > Ações Clique em e adicione . Novo Segredo do Repositório NPM_TOKEN Etapa 7: Criando uma nova versão Digamos que você queira adicionar para a versão e já o tenha enviado: README.md v1.0.1 Rascunhe um novo lançamento: Vá para a seção no seu repositório GitHub. [ ] Releases 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 o evento de liberação é acionado. O fluxo de trabalho, Fluxo de trabalho acionado: 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 no npm, excluindo arquivos de teste. 1.0.1 Depois de um momento, visite a página do seu pacote npm para ver a nova versão ativa. Verificar no npm: 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 para enviar um pacote totalmente testado e com a versão correta para o registro npm. um único lançamento do GitHub
