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: esegui automaticamente i test prima della pubblicazione. Se i test falliscono, la nuova versione non viene rilasciata. Garantisci la qualità: la versione del pacchetto pubblicata corrisponde sempre al tag di rilascio. Versionamento coerente: i collaboratori inviano il codice, tu crei una versione e la pipeline fa il resto, senza che siano richieste autorizzazioni npm speciali. Collaborazione senza intoppi: Prerequisiti Node.js e npm: qui se non hai installato NodeJS e NPM. Clicca Conferma l'installazione eseguendo il codice sottostante nel tuo terminale. node -v npm -v Account e repository GitHub: Per archiviare il codice ed eseguire GitHub Actions è necessario un repository GitHub. Account NPM e token di accesso: Registrati o accedi su e genera un token di accesso. npmjs.com Aggiungi il token di accesso come segreto nel tuo repository GitHub per la pubblicazione automatica. Passaggio 1: impostare il progetto Creeremo un semplice pacchetto che esporta una funzione che verifica se una stringa è alfanumerica. alphanumeric-validator Inizializzare il progetto mkdir alphanumeric-validator cd alphanumeric-validator npm init -y Per , apparirà così. Aggiorna package.json se necessario. 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" } 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. Installa Jest npm install --save-dev jest Crea un file di prova mkdir tests 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); }); 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 . Non vuoi sottoporre al controllo di versione, poiché contiene un gran numero di file che possono essere rigenerati da . node_modules node_modules npm install nella radice del tuo progetto: Crea un file .gitignore echo "node_modules" >> .gitignore In questo modo si garantisce che non venga tracciato da git e non venga trasferito al repository. node_modules 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 nella cartella radice e aggiungere i nomi dei file di prova. .npmignore // .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 Crea un nuovo repository GitHub: Vai su e crea un repository . https://github.com/new alphanumeric-validator Spingi il tuo codice 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 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 per rendere il tuo pacchetto pubblico e accessibile agli utenti. --access public npm login npm publish --access public Visita per verificare che la versione iniziale sia attiva. https://www.npmjs.com/package/alphanumeric-validator 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 alla nuova versione dal tag release. package.json 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 "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 }} Aggiungere il token NPM a GitHub Visita (assicurati di sostituire con il tuo nome utente effettivo) https://www.npmjs.com/settings/:username/tokens/new :username Inserisci il nome, seleziona l'automazione per il tipo e genera Verrai reindirizzato alla pagina dei token, dove potrai copiare il token. Vai su nel tuo repository GitHub. Impostazioni > Segreti e variabili > Azioni Fare clic su e aggiungere . Nuovo segreto del repository NPM_TOKEN Fase 7: Creazione di una nuova versione Supponiamo che tu voglia aggiungere per la versione e che tu l'abbia inviato: README.md v1.0.1 Bozza di una nuova versione: Vai alla sezione nel tuo repository GitHub. [ ] Releases 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 l'evento di rilascio viene attivato. Il flusso di lavoro, Workflow attivato: 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 su npm, esclusi i file di test. 1.0.1 dopo un momento, visita la pagina del tuo pacchetto npm per vedere la nuova versione live. Verifica su npm: 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 per inviare un pacchetto completamente testato e con la versione corretta al registro npm. una singola release di GitHub
