Come pubblicare automaticamente il tuo pacchetto NPM utilizzando le azioni GitHub

L'automazione del processo di pubblicazione del tuo pacchetto npm con integrazione e distribuzione continue (CI/CD) garantisce che ogni release passi attraverso un quality gate, la tua suite di test, prima della pubblicazione. Allo stesso tempo, puoi controllare esattamente cosa finisce nel pacchetto finale pubblicato escludendo i file di test. In questa guida, imparerai come impostare CI/CD per un semplice pacchetto npm, un validatore alfanumerico, in modo che ogni nuova release di GitHub attivi i test, aggiorni la versione del pacchetto e pubblichi automaticamente un pacchetto pulito su npm.

Perché automatizzare la pubblicazione npm?

La pubblicazione manuale di npm può richiedere molto tempo ed essere soggetta a errori, in particolare man mano che il progetto cresce e acquisisce collaboratori. Automatizzando il processo, puoi:

• Garantisci la qualità: esegui automaticamente i test prima della pubblicazione. Se i test falliscono, la nuova versione non viene rilasciata.
• Versionamento coerente: la versione del pacchetto pubblicata corrisponde sempre al tag di rilascio.
• Collaborazione senza intoppi: i collaboratori inviano il codice, tu crei una versione e la pipeline fa il resto, senza che siano richieste autorizzazioni npm speciali.

Prerequisiti

1. Node.js e npm:
   • Clicca qui se non hai installato NodeJS e NPM.
   • Conferma l'installazione eseguendo il codice sottostante nel tuo terminale.

 node -v npm -v

2. Account e repository GitHub:
   • Per archiviare il codice ed eseguire GitHub Actions è necessario un repository GitHub.
3. Account NPM e token di accesso:
   • Registrati o accedi su npmjs.com e genera un token di accesso.
   • Aggiungi il token di accesso come segreto nel tuo repository GitHub per la pubblicazione automatica.

Passaggio 1: impostare il progetto

Creeremo un semplice pacchetto alphanumeric-validator che esporta una funzione che verifica se una stringa è alfanumerica.

1. Inizializzare il progetto

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

2. Aggiorna package.json se necessario. Per alphanumeric-validator , apparirà così.

 { "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. Implementare il validatore

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

Passaggio 2: aggiungere ed eseguire i test localmente

I test garantiscono che non verrà pubblicato codice non funzionante.

1. Installa Jest

    npm install --save-dev jest

2. Crea un file di prova

    mkdir tests

3. Incolla il codice sottostante nel file 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. Eseguire test

    npm test 

I test sono stati superati? Ottimo. Ora, ci assicureremo che questi test vengano eseguiti in CI prima della pubblicazione.

Passaggio 3: escludere i moduli Node da Git

Prima di pubblicare su Github, vuoi escludere node_modules . Non vuoi sottoporre node_modules al controllo di versione, poiché contiene un gran numero di file che possono essere rigenerati da npm install .

Crea un file .gitignore nella radice del tuo progetto:

 echo "node_modules" >> .gitignore

In questo modo si garantisce che node_modules non venga tracciato da git e non venga trasferito al repository.

Passaggio 4: escludere i test dal pacchetto pubblicato

Mentre eseguirai i test durante la CI, non vuoi che i file di test siano inclusi nel tuo pacchetto npm pubblicato. Questo mantiene il pacchetto pulito, ha una dimensione di bundle ridotta e assicura che solo i file necessari vengano spediti agli utenti.

Creare un file .npmignore nella cartella radice e aggiungere i nomi dei file di prova.

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

In questo modo si garantisce che i file di test non vengano inclusi quando si esegue npm publish .

Passaggio 5: ospita il tuo codice su GitHub

1. Crea un nuovo repository GitHub:
   • Vai su https://github.com/new e crea un repository alphanumeric-validator .

2. Spingi il tuo codice

    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 

Passaggio 5: Pubblicazione manuale iniziale su npm

• Prima di avviare l'automazione, verifica che il tuo pacchetto possa essere pubblicato : vedi qui.
• Aggiungi quindi il flag --access public per rendere il tuo pacchetto pubblico e accessibile agli utenti.

 npm login npm publish --access public 

• Visita https://www.npmjs.com/package/alphanumeric-validator per verificare che la versione iniziale sia attiva.

  
  

Passaggio 6: impostazione del flusso di lavoro di GitHub Actions

È necessario configurare un flusso di lavoro che venga eseguito a ogni evento di rilascio in modo che quando si crea una nuova versione (ad esempio v1.0.1 ):

• Il flusso di lavoro verifica il codice.
• Installa le dipendenze.
• Esegue test per garantirne la qualità.
• Aggiorna package.json alla nuova versione dal tag release.
• Pubblica il pacchetto aggiornato su npm senza includere i file di test.

Il file del flusso di lavoro

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

Aggiungere il token NPM a GitHub

• Visita https://www.npmjs.com/settings/:username/tokens/new (assicurati di sostituire :username con il tuo nome utente effettivo)
• Inserisci il nome, seleziona l'automazione per il tipo e genera

• Verrai reindirizzato alla pagina dei token, dove potrai copiare il token.

• Vai su Impostazioni > Segreti e variabili > Azioni nel tuo repository GitHub.

• Fare clic su Nuovo segreto del repository e aggiungere NPM_TOKEN .

  
  

  

Fase 7: Creazione di una nuova versione

Supponiamo che tu voglia aggiungere README.md per la versione v1.0.1 e che tu l'abbia inviato:

1. Bozza di una nuova versione:
   • Vai alla sezione Releases nel tuo repository GitHub. [ https://github.com/username/repo/releases ]
   • Fare clic su Crea una bozza di una nuova versione .
   • Impostare la "Versione tag" su v1.0.1.
   • Fare clic su Pubblica comunicato .

2. Workflow attivato: l'evento di rilascio viene attivato. Il flusso di lavoro,
   • Controlla il codice.
   • Installa le dipendenze.
   • Esegue i test. Se i test falliscono, il lavoro si arresta e il pacchetto non verrà pubblicato.
   • Se i test vengono superati, package.json viene aggiornato alla 1.0.1 .
   • Pubblica la versione 1.0.1 su npm, esclusi i file di test.

3. Verifica su npm: dopo un momento, visita la pagina del tuo pacchetto npm per vedere la nuova versione live.

Conclusione

L'integrazione di GitHub Actions nel tuo flusso di lavoro di pubblicazione npm stabilisce un'ottima pipeline CI/CD. Con ogni nuova release, viene eseguita una serie completa di test, package.json viene aggiornato con la versione corretta e un pacchetto semplificato viene pubblicato su npm, privo di file non necessari come i test.

Questo approccio consente di risparmiare tempo, riduce gli errori umani e aumenta l'affidabilità delle release, consentendo ai collaboratori di vedere il proprio lavoro pubblicato senza problemi.

Ora è sufficiente una singola release di GitHub per inviare un pacchetto completamente testato e con la versione corretta al registro npm.