Ako automaticky publikovať svoj balík NPM pomocou akcií GitHub

Automatizácia vášho procesu publikovania balíkov npm s nepretržitou integráciou a doručovaním (CI/CD) zaisťuje, že každé vydanie prejde pred zverejnením bránou kvality – vašou testovacou súpravou. Vylúčením testovacích súborov môžete zároveň presne kontrolovať, čo skončí v konečnom zverejnenom balíku. V tejto príručke sa dozviete, ako nastaviť CI/CD pre jednoduchý balík npm – alfanumerický validátor – aby každé nové vydanie GitHubu spustilo testy, aktualizovalo verziu balíka a automaticky zverejnilo čistý balík na npm.

Prečo automatizovať publikovanie npm?

Manuálne publikovanie npm môže byť časovo náročné a náchylné na chyby, najmä keď váš projekt rastie a získava prispievateľov. Automatizáciou procesu môžete:

• Zabezpečenie kvality: Pred zverejnením automaticky spustite testy. Ak testy zlyhajú, nová verzia nebude vydaná.
• Konzistentné vytváranie verzií: Zverejnená verzia balíka sa vždy zhoduje so značkou vydania.
• Bezchybná spolupráca: Prispievatelia zašlú kód, vy vytvoríte vydanie a o zvyšok sa postará kanál – nevyžadujú sa žiadne špeciálne povolenia npm.

Predpoklady

1. Node.js a npm:
   • Kliknite sem, ak nemáte nainštalované NodeJS a NPM.
   • Potvrďte inštaláciu spustením kódu nižšie vo vašom termináli.

 node -v npm -v

2. Účet a úložisko GitHub:
   • Na ukladanie kódu a spúšťanie akcií GitHub potrebujete úložisko GitHub.
3. NPM účet a prístupový token:
   • Zaregistrujte sa alebo prihláste na npmjs.com a vygenerujte prístupový token.
   • Pridajte prístupový token ako tajný do svojho úložiska GitHub na automatické zverejňovanie.

Krok 1: Nastavte projekt

Vytvoríme jednoduchý balík alphanumeric-validator , ktorý exportuje funkciu, ktorá kontroluje, či je reťazec alfanumerický.

1. Inicializujte projekt

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

2. Podľa potreby aktualizujte package.json . Pre alphanumeric-validator to bude vyzerať takto.

 { "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. Implementujte Validator

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

Krok 2: Pridajte a spustite testy lokálne

Testovanie zaisťuje, že nezverejníte poškodený kód.

1. Nainštalujte Jest

    npm install --save-dev jest

2. Vytvorte testovací súbor

    mkdir tests

3. Vložte nižšie uvedený kód do súboru 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. Spustiť testy

    npm test 

Úspešné testy? Skvelé. Teraz zabezpečíme spustenie týchto testov v CI pred zverejnením.

Krok 3: Vylúčte moduly uzlov z Git

Pred publikovaním na Github chcete vylúčiť node_modules . Nechcete zaviazať node_modules do správy verzií, pretože obsahuje veľké množstvo súborov, ktoré je možné vygenerovať pomocou npm install .

Vytvorte súbor .gitignore v koreňovom adresári vášho projektu:

 echo "node_modules" >> .gitignore

To zaisťuje, že node_modules nie je sledovaný git a nebude poslaný do vášho úložiska.

Krok 4: Vylúčte testy zo zverejneného balíka

Aj keď budete počas CI spúšťať testy, nechcete, aby boli testovacie súbory súčasťou vášho publikovaného balíka npm. Vďaka tomu je balík čistý, má malú veľkosť balíka a používateľom sa doručujú iba potrebné súbory.

Vytvorte súbor .npmignore v koreňovom priečinku a pridajte názvy testovacích súborov.

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

To zaisťuje, že testovacie súbory nebudú zahrnuté pri spustení npm publish .

Krok 5: Hostite svoj kód na GitHub

1. Vytvorte nové úložisko GitHub:
   • Prejdite na https://github.com/new a vytvorte úložisko alphanumeric-validator .

2. Push Your Code

    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 

Krok 5: Počiatočné manuálne publikovanie do npm

• Pred spustením automatizácie sa uistite, že váš balík môže byť zverejnený – pozri tu.
• Potom pridajte --access public , aby bol váš balík verejný a prístupný používateľom.

 npm login npm publish --access public 

• Navštívte https://www.npmjs.com/package/alphanumeric-validator a overte, či je pôvodná verzia aktívna.

  
  

Krok 6: Nastavenie pracovného postupu akcií GitHub

Musíte nakonfigurovať pracovný postup, ktorý sa spustí pri každej udalosti vydania, aby pri vytváraní nového vydania (napríklad v1.0.1 ):

• Pracovný postup skontroluje váš kód.
• Inštaluje závislosti.
• Vykonáva testy na zabezpečenie kvality.
• Aktualizuje package.json na novú verziu zo značky vydania.
• Zverejní aktualizovaný balík do npm bez zahrnutia testovacích súborov.

Súbor pracovného postupu

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

Pridanie tokenu NPM na GitHub

• Navštívte https://www.npmjs.com/settings/:username/tokens/new (Uistite sa, že ste nahradili :username vaším skutočným používateľským menom)
• Zadajte názov, pre typ vyberte automatizáciu a vygenerujte

• Budete presmerovaní na stránku tokenov, kde môžete token skopírovať.

• Prejdite do Nastavenia > Tajomstvá a premenné > Akcie vo svojom úložisku GitHub.

• Kliknite na Nový tajný kľúč úložiska a pridajte NPM_TOKEN .

  
  

  

Krok 7: Vytvorenie nového vydania

Povedzme, že chcete pridať README.md pre vydanie v1.0.1 a stlačili ste ho:

1. Návrh nového vydania:
   • Prejdite do sekcie Vydania vo svojom úložisku GitHub. [ https://github.com/username/repo/releases ]
   • Kliknite na položku Návrh nového vydania .
   • Nastavte „Verzia značky“ na v1.0.1.
   • Kliknite na položku Publikovať vydanie .

2. Spustený pracovný postup: Spustí sa udalosť uvoľnenia. pracovný postup,
   • Skontroluje kód.
   • Inštaluje závislosti.
   • Spustí testy. Ak testy zlyhajú, úloha sa zastaví a balík nebude zverejnený.
   • Ak testy prebehnú úspešne, aktualizuje súbor package.json na 1.0.1 .
   • Zverejňuje verziu 1.0.1 do npm, s výnimkou testovacích súborov.

3. Overiť na npm: Po chvíli navštívte svoju stránku balíka npm a pozrite si novú verziu naživo.

Záver

Integrácia akcií GitHub do vášho pracovného postupu publikovania npm vytvára skvelý kanál CI/CD. S každým novým vydaním sa spustí komplexná séria testov, súbor package.json sa aktualizuje správnou verziou a do npm sa publikuje zjednodušený balík – bez nepotrebných súborov, ako sú testy.

Tento prístup šetrí čas, znižuje ľudské chyby a zvyšuje spoľahlivosť vašich vydaní, vďaka čomu prispievatelia ľahšie uvidia, ako ich práca plynulo funguje.

Jediné vydanie GitHubu je teraz všetko, čo je potrebné na odoslanie plne otestovaného balíka so správnou verziou do registra npm.