Jak automaticky publikovat svůj balíček NPM pomocí akcí GitHub

Automatizace vašeho procesu publikování balíčků npm s nepřetržitou integrací a doručováním (CI/CD) zajišťuje, že každé vydání projde před zveřejněním bránou kvality – vaší testovací sadou. Vyloučením testovacích souborů zároveň můžete přesně řídit, co skončí ve finálním publikovaném balíčku. V této příručce se dozvíte, jak nastavit CI/CD pro jednoduchý balíček npm – alfanumerický validátor – tak, aby každé nové vydání GitHubu spustilo testy, aktualizovalo verzi balíčku a automaticky publikovalo čistý balíček do npm.

Proč automatizovat publikování npm?

Ruční publikování npm může být časově náročné a náchylné k chybám, zvláště když váš projekt roste a získává přispěvatele. Automatizací procesu můžete:

• Zajištění kvality: Před publikováním automaticky spusťte testy. Pokud testy selžou, nová verze nebude vydána.
• Konzistentní verzování: Publikovaná verze balíčku vždy odpovídá značce vydání.
• Bezproblémová spolupráce: Přispěvatelé odešlou kód, vy vytvoříte vydání a o zbytek se postará kanál – nejsou vyžadována žádná zvláštní oprávnění npm.

Předpoklady

1. Node.js a npm:
   • Pokud nemáte nainstalované NodeJS a NPM, klikněte sem .
   • Potvrďte instalaci spuštěním kódu níže ve vašem terminálu.

 node -v npm -v

2. Účet a úložiště GitHub:
   • K ukládání kódu a spouštění akcí GitHubu potřebujete úložiště GitHub.
3. Účet NPM a přístupový token:
   • Zaregistrujte se nebo se přihlaste na npmjs.com a vygenerujte přístupový token.
   • Přidejte přístupový token jako tajný do svého úložiště GitHub pro automatizované publikování.

Krok 1: Nastavte projekt

Vytvoříme jednoduchý balíček alphanumeric-validator , který exportuje funkci kontrolující, zda je řetězec alfanumerický.

1. Inicializujte projekt

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

2. Podle potřeby aktualizujte package.json . U alphanumeric-validator to bude vypadat 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: Přidejte a spusťte testy lokálně

Testování zajišťuje, že nezveřejníte poškozený kód.

1. Nainstalujte Jest

    npm install --save-dev jest

2. Vytvořte testovací soubor

    mkdir tests

3. Vložte níže uvedený kód do souboru 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. Spustit testy

    npm test 

Absolvování testů? Velký. Nyní zajistíme, aby byly tyto testy spuštěny v CI před publikováním.

Krok 3: Vyloučení modulů uzlů z Gitu

Před publikováním na Github chcete vyloučit node_modules . Nechcete odevzdat node_modules do správy verzí, protože obsahuje velké množství souborů, které lze obnovit pomocí npm install .

Vytvořte soubor .gitignore v kořenovém adresáři vašeho projektu:

 echo "node_modules" >> .gitignore

To zajišťuje, že node_modules nebude sledován git a nebude odeslán do vašeho úložiště.

Krok 4: Vyloučení testů z publikovaného balíčku

I když budete během CI spouštět testy, nechcete, aby byly testovací soubory součástí vašeho publikovaného balíčku npm. Balíček tak zůstává čistý, má malou velikost balíčku a zajišťuje, že uživatelům budou odeslány pouze nezbytné soubory.

Vytvořte soubor .npmignore v kořenové složce a přidejte názvy testovacích souborů.

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

Tím zajistíte, že při spuštění npm publish nebudou zahrnuty testovací soubory.

Krok 5: Hostujte svůj kód na GitHubu

1. Vytvořte nové úložiště GitHub:
   • Přejděte na https://github.com/new a vytvořte úložiště 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čáteční ruční publikování na npm

• Před zahájením automatizace se ujistěte, že váš balíček může být publikován – viz zde.
• Poté přidejte --access public , aby byl váš balíček veřejný a přístupný uživatelům.

 npm login npm publish --access public 

• Navštivte https://www.npmjs.com/package/alphanumeric-validator a ověřte, zda je původní verze aktivní.

  
  

Krok 6: Nastavení pracovního postupu akcí GitHub

Je třeba nakonfigurovat pracovní postup, který se spouští při každé události vydání, takže když vytvoříte nové vydání (například v1.0.1 ):

• Pracovní postup zkontroluje váš kód.
• Nainstaluje závislosti.
• Provádí testy pro zajištění kvality.
• Aktualizuje package.json na novou verzi ze značky vydání.
• Publikuje aktualizovaný balíček do npm bez zahrnutí testovacích souborů.

Soubor pracovního postupu

Vytvořte soubor .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 }}

Přidání vašeho tokenu NPM na GitHub

• Navštivte https://www.npmjs.com/settings/:username/tokens/new (Ujistěte se, že jste nahradili :username svým skutečným uživatelským jménem)
• Zadejte název, pro typ vyberte automatizaci a vygenerujte

• Budete přesměrováni na stránku tokenů, kde můžete token zkopírovat.

• Přejděte do Nastavení > Tajemství a proměnné > Akce ve svém úložišti GitHub.

• Klikněte na Nový tajný klíč úložiště a přidejte NPM_TOKEN .

  
  

  

Krok 7: Vytvoření nové verze

Řekněme, že chcete přidat README.md pro vydání v1.0.1 a vložili jste to:

1. Návrh nového vydání:
   • Přejděte do sekce Vydání v repozitáři GitHubu. [ https://github.com/username/repo/releases ]
   • Klikněte na možnost Navrhnout nové vydání .
   • Nastavte "Verze značky" na v1.0.1.
   • Klikněte na Publikovat vydání .

2. Workflow Triggered: Spustí se událost uvolnění. pracovní postup,
   • Zkontroluje kód.
   • Nainstaluje závislosti.
   • Spouští testy. Pokud testy selžou, úloha se zastaví a balíček nebude publikován.
   • Pokud testy projdou, aktualizuje package.json na 1.0.1 .
   • Zveřejňuje verzi 1.0.1 do npm, s výjimkou testovacích souborů.

3. Ověřit na npm: Po chvíli navštivte svou stránku balíčku npm a uvidíte novou verzi živě.

Závěr

Integrace akcí GitHub do vašeho pracovního postupu publikování npm vytváří skvělý kanál CI/CD. S každým novým vydáním se spustí komplexní série testů, soubor package.json se aktualizuje správnou verzí a do npm se publikuje zjednodušený balíček – bez zbytečných souborů, jako jsou testy.

Tento přístup šetří čas, omezuje lidské chyby a zvyšuje spolehlivost vašich vydání, takže přispěvatelům usnadňuje bezproblémový provoz jejich práce.

Jediné vydání GitHubu nyní stačí k odeslání plně otestovaného balíčku se správnou verzí do registru npm.