Como publicar automaticamente o teu paquete NPM usando accións de GitHub

A automatización do seu proceso de publicación de paquetes npm con integración e entrega continuas (CI/CD) garante que cada versión pase por unha porta de calidade, a súa suite de probas, antes da publicación. Ao mesmo tempo, pode controlar exactamente o que acaba no paquete final publicado excluíndo os ficheiros de proba. Nesta guía, aprenderás a configurar CI/CD para un paquete npm simple (un validador alfanumérico) para que cada nova versión de GitHub desencadee probas, actualice a versión do paquete e publique automaticamente un paquete limpo en npm.

Por que automatizar a publicación npm?

A publicación manual de npm pode ser lento e propensa a erros, especialmente a medida que o teu proxecto crece e gaña colaboradores. Ao automatizar o proceso, pode:

• Asegurar a calidade: executa probas automaticamente antes de publicalas. Se as probas fallan, a nova versión non se publica.
• Versionado coherente: a versión do paquete publicado sempre coincide coa etiqueta de versión.
• Colaboración sen fricción: os colaboradores envían código, ti creas unha versión e a canalización fai o resto; non son necesarios permisos especiais de npm.

Requisitos previos

1. Node.js e npm:
   • Fai clic aquí se non tes NodeJS e NPM instalados.
   • Confirma a instalación executando o seguinte código no teu terminal.

 node -v npm -v

2. Conta e repositorio de GitHub:
   • Necesitas un repositorio de GitHub para almacenar código e executar accións de GitHub.
3. Conta NPM e token de acceso:
   • Rexístrese ou inicie sesión en npmjs.com e xera un token de acceso.
   • Engade o token de acceso como segredo no teu repositorio de GitHub para a publicación automatizada.

Paso 1: configurar o proxecto

Crearemos un paquete alphanumeric-validator sinxelo que exporta unha función comprobando se unha cadea é alfanumérica.

1. Iniciar o Proxecto

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

2. Actualiza package.json segundo sexa necesario. Para o alphanumeric-validator , terá este aspecto.

 { "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;

Paso 2: Engade e executa probas localmente

As probas garanten que non publiques códigos rotos.

1. Instala Jest

    npm install --save-dev jest

2. Crear un ficheiro de proba

    mkdir tests

3. Pega o seguinte código no ficheiro 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. Realiza probas

    npm test 

Probas aprobadas? Genial. Agora, asegurarémonos que estas probas se executen en CI antes de publicalas.

Paso 3: Exclúe os módulos de nodos de Git

Antes de publicar en Github, quere excluír node_modules . Non quere comprometer node_modules ao control de versións, xa que contén un gran número de ficheiros que se poden rexenerar mediante npm install .

Crea un ficheiro .gitignore na raíz do teu proxecto:

 echo "node_modules" >> .gitignore

Isto garante que git non rastrexa node_modules e que non será enviado ao teu repositorio.

Paso 4: excluír probas do paquete publicado

Aínda que realizará probas durante CI, non quere que os ficheiros de proba se inclúan no paquete npm publicado. Isto mantén o paquete limpo, ten un pequeno tamaño de paquete e garante que só se envíen aos usuarios os ficheiros necesarios.

Crea un ficheiro .npmignore no cartafol raíz e engade os nomes dos ficheiros de proba.

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

Isto garante que os ficheiros de proba non estean incluídos cando executa npm publish .

Paso 5: Aloxa o teu código en GitHub

1. Crea un novo repositorio de GitHub:
   • Vaia a https://github.com/new e cree un repositorio alphanumeric-validator .

2. Empuxe o teu 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 

Paso 5: Publicación manual inicial en npm

• Antes de iniciar a automatización, confirma que se pode publicar o teu paquete ; consulta aquí.
• A continuación, engade a marca --access public para que o seu paquete sexa público e accesible para os usuarios.

 npm login npm publish --access public 

• Visita https://www.npmjs.com/package/alphanumeric-validator para verificar que a versión inicial estea activa.

  
  

Paso 6: configurar o fluxo de traballo de accións de GitHub

Debe configurar un fluxo de traballo que se executa en cada evento de lanzamento para que cando cree unha nova versión (como v1.0.1 ):

• O fluxo de traballo comproba o teu código.
• Instala dependencias.
• Realiza probas para garantir a calidade.
• Actualiza package.json á nova versión desde a etiqueta release.
• Publica o paquete actualizado en npm sen incluír ficheiros de proba.

O ficheiro de fluxo de traballo

Crear .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 }}

Engadindo o teu token NPM a GitHub

• Visita https://www.npmjs.com/settings/:username/tokens/new (Asegúrate de substituír :username polo teu nome de usuario real)
• Introduza o nome, seleccione a automatización para o tipo e xera

• Serás redirixido á páxina de tokens, onde podes copiar o token.

• Vaia a Configuración > Segredos e variables > Accións no repositorio de GitHub.

• Fai clic en Novo segredo do repositorio e engade NPM_TOKEN .

  
  

  

Paso 7: Creación dunha nova versión

Digamos que quere engadir README.md para a versión v1.0.1 e que o impulsou:

1. Elaborar unha nova versión:
   • Vaia á sección Lanzamentos do repositorio de GitHub. [ https://github.com/username/repo/releases ]
   • Fai clic en Borrador dunha nova versión .
   • Establece a "Versión da etiqueta" na v1.0.1.
   • Fai clic en Publicar versión .

2. Fluxo de traballo desencadeado: desenvólvese o evento de lanzamento. O fluxo de traballo,
   • Comproba o código.
   • Instala dependencias.
   • Realiza probas. Se as probas fallan, o traballo detense e o paquete non se publicará.
   • Se as probas pasan, actualiza package.json a 1.0.1 .
   • Publica a versión 1.0.1 en npm, excluíndo os ficheiros de proba.

3. Verificar en npm: despois dun momento, visita a páxina do teu paquete npm para ver a nova versión en directo.

Conclusión

A integración de GitHub Actions no teu fluxo de traballo de publicación npm establece unha excelente canalización de CI/CD. Con cada nova versión, realízase unha serie completa de probas, package.json actualízase coa versión correcta e publícase un paquete simplificado en npm, sen ficheiros innecesarios como probas.

Este enfoque aforra tempo, reduce os erros humanos e mellora a fiabilidade das túas versións, facilitando que os colaboradores vexan o seu traballo en directo sen problemas.

Agora só é necesario unha única versión de GitHub para enviar un paquete totalmente probado e con versións adecuadas ao rexistro npm.