Cómo publicar automáticamente su paquete NPM mediante GitHub Actions

La automatización del proceso de publicación de paquetes de npm con integración y entrega continuas (CI/CD) garantiza que cada versión pase por un control de calidad (su conjunto de pruebas) antes de su publicación. Al mismo tiempo, puede controlar exactamente qué termina en el paquete publicado final al excluir los archivos de prueba. En esta guía, aprenderá a configurar CI/CD para un paquete npm simple (un validador alfanumérico) de modo que cada nueva versión de GitHub active pruebas, actualice la versión del paquete y publique automáticamente un paquete limpio en npm.

¿Por qué automatizar la publicación de npm?

La publicación manual de npm puede llevar mucho tiempo y ser propensa a errores, en especial a medida que el proyecto crece y gana colaboradores. Al automatizar el proceso, puede:

• Garantizar la calidad: ejecutar pruebas automáticamente antes de publicar. Si las pruebas fallan, no se publica la nueva versión.
• Versiones consistentes: la versión del paquete publicado siempre coincide con la etiqueta de lanzamiento.
• Colaboración sin fricciones: los colaboradores envían el código, usted crea una versión y el proceso hace el resto; no se requieren permisos npm especiales.

Prerrequisitos

1. Node.js y npm:
   • Haga clic aquí si no tiene NodeJS y NPM instalados.
   • Confirme la instalación ejecutando el siguiente código en su terminal.

 node -v npm -v

2. Cuenta y repositorio de GitHub:
   • Necesita un repositorio de GitHub para almacenar código y ejecutar Acciones de GitHub.
3. Cuenta NPM y token de acceso:
   • Regístrese o inicie sesión en npmjs.com y genere un token de acceso.
   • Agrega el token de acceso como secreto en tu repositorio de GitHub para publicación automatizada.

Paso 1: Configurar el proyecto

Crearemos un paquete alphanumeric-validator simple que exporta una función que verifica si una cadena es alfanumérica.

1. Inicializar el proyecto

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

2. Actualice package.json según sea necesario. Para el alphanumeric-validator , se verá así.

 { "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 el validador

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

Paso 2: Agregar y ejecutar pruebas localmente

Las pruebas garantizan que no publiques código roto.

1. Instalar Jest

    npm install --save-dev jest

2. Crear un archivo de prueba

    mkdir tests

3. Pegue el código a continuación en el archivo 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. Ejecutar pruebas

    npm test 

¿Las pruebas se han aprobado? Genial. Ahora, nos aseguraremos de que estas pruebas se ejecuten en CI antes de publicarlas.

Paso 3: Excluir módulos de nodo de Git

Antes de publicar en Github, conviene excluir node_modules . No conviene enviar node_modules al control de versiones, ya que contiene una gran cantidad de archivos que se pueden regenerar con npm install .

Crea un archivo .gitignore en la raíz de tu proyecto:

 echo "node_modules" >> .gitignore

Esto garantiza que node_modules no sea rastreado por git y no sea enviado a su repositorio.

Paso 4: Excluir pruebas del paquete publicado

Si bien ejecutará pruebas durante la integración continua, no desea que los archivos de prueba se incluyan en su paquete npm publicado. Esto mantiene el paquete limpio, tiene un tamaño de paquete pequeño y garantiza que solo se envíen los archivos necesarios a los usuarios.

Cree un archivo .npmignore en la carpeta raíz y agregue los nombres de los archivos de prueba.

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

Esto garantiza que los archivos de prueba no se incluyan cuando ejecute npm publish .

Paso 5: Aloje su código en GitHub

1. Crear un nuevo repositorio de GitHub:
   • Vaya a https://github.com/new y cree un repositorio alphanumeric-validator .

2. Empuja tu 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 la automatización, confirme que su paquete pueda publicarse: consulte aquí.
• Luego, agregue el indicador --access public para que su paquete sea público y accesible para los usuarios.

 npm login npm publish --access public 

• Visite https://www.npmjs.com/package/alphanumeric-validator para verificar que la versión inicial esté activa.

  
  

Paso 6: Configuración del flujo de trabajo de GitHub Actions

Debe configurar un flujo de trabajo que se ejecute en cada evento de lanzamiento para que cuando cree un nuevo lanzamiento (como v1.0.1 ):

• El flujo de trabajo verifica su código.
• Instala dependencias.
• Ejecuta pruebas para garantizar la calidad.
• Actualiza package.json a la nueva versión desde la etiqueta de lanzamiento.
• Publica el paquete actualizado en npm sin incluir archivos de prueba.

El archivo de flujo de trabajo

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

Cómo agregar su token NPM a GitHub

• Visita https://www.npmjs.com/settings/:username/tokens/new (asegúrate de reemplazar :username con tu nombre de usuario real)
• Ingrese el nombre, seleccione automatización para el tipo y genere

• Serás redirigido a la página de tokens, donde podrás copiar el token.

• Vaya a Configuración > Secretos y variables > Acciones en su repositorio de GitHub.

• Haga clic en Nuevo secreto de repositorio y agregue NPM_TOKEN .

  
  

  

Paso 7: Crear una nueva versión

Digamos que desea agregar README.md para la versión v1.0.1 y lo ha enviado:

1. Redactar un nuevo comunicado:
   • Vaya a la sección Lanzamientos en su repositorio de GitHub. [ https://github.com/username/repo/releases ]
   • Haga clic en Borrador de una nueva versión .
   • Establezca la "Versión de etiqueta" en v1.0.1.
   • Haga clic en Publicar lanzamiento .

2. Flujo de trabajo activado: se activa el evento de lanzamiento. El flujo de trabajo,
   • Comprueba el código.
   • Instala dependencias.
   • Ejecuta pruebas. Si las pruebas fallan, el trabajo se detiene y el paquete no se publicará.
   • Si las pruebas pasan, actualiza package.json a 1.0.1 .
   • Publica la versión 1.0.1 en npm, excluyendo los archivos de prueba.

3. Verificar en npm: Después de un momento, visita la página de tu paquete npm para ver la nueva versión en vivo.

Conclusión

La integración de GitHub Actions en el flujo de trabajo de publicación de npm establece una excelente secuencia de CI/CD. Con cada nueva versión, se ejecuta una serie completa de pruebas, se actualiza package.json con la versión correcta y se publica un paquete optimizado en npm, sin archivos innecesarios como pruebas.

Este enfoque ahorra tiempo, reduce los errores humanos y mejora la confiabilidad de sus lanzamientos, lo que hace que sea más fácil para los colaboradores ver su trabajo publicado sin problemas.

Ahora basta con un solo lanzamiento de GitHub para enviar un paquete completamente probado y con la versión correcta al registro npm.