Hur du automatiskt publicerar ditt NPM-paket med hjälp av GitHub-åtgärder

Att automatisera din npm-paketpubliceringsprocess med kontinuerlig integrering och leverans (CI/CD) säkerställer att varje utgåva passerar genom en kvalitetsgrind – din testsvit – innan publicering. Samtidigt kan du styra exakt vad som hamnar i det slutgiltiga publicerade paketet genom att utesluta testfiler. I den här guiden lär du dig hur du ställer in CI/CD för ett enkelt npm-paket – en alfanumerisk validator – så att varje ny GitHub-utgåva utlöser tester, uppdaterar paketversionen och automatiskt publicerar ett rent paket till npm.

Varför automatisera npm-publicering?

Manuell npm-publicering kan vara tidskrävande och felbenägen, särskilt när ditt projekt växer och får bidragsgivare. Genom att automatisera processen kan du:

• Säkerställ kvalitet: Kör automatiskt tester innan publicering. Om testerna misslyckas släpps inte den nya versionen.
• Konsekvent versionering: Den publicerade paketversionen matchar alltid releasetaggen.
• Friktionsfritt samarbete: Bidragsgivare skickar in kod, du skapar en release och pipelinen gör resten – inga speciella npm-behörigheter krävs.

Förutsättningar

1. Node.js & npm:
   • Klicka här om du inte har NodeJS och NPM installerat.
   • Bekräfta installationen genom att köra koden nedan i din terminal.

 node -v npm -v

2. GitHub-konto och arkiv:
   • Du behöver ett GitHub-förråd för att lagra kod och köra GitHub-åtgärder.
3. NPM-konto och åtkomsttoken:
   • Registrera dig eller logga in på npmjs.com och generera en åtkomsttoken.
   • Lägg till åtkomsttoken som en hemlighet i ditt GitHub-förråd för automatiserad publicering.

Steg 1: Konfigurera projektet

Vi skapar ett enkelt alphanumeric-validator som exporterar en funktion som kontrollerar om en sträng är alfanumerisk.

1. Initiera projektet

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

2. Uppdatera package.json vid behov. För den alphanumeric-validator kommer det att se ut så här.

 { "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. Implementera valideraren

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

Steg 2: Lägg till och kör tester lokalt

Testning säkerställer att du inte publicerar trasig kod.

1. Installera Jest

    npm install --save-dev jest

2. Skapa en testfil

    mkdir tests

3. Klistra in koden nedan i filen 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. Kör tester

    npm test 

Godkänd test? Stor. Nu ska vi se till att dessa tester körs i CI innan de publiceras.

Steg 3: Exkludera nodmoduler från Git

Innan du publicerar till Github vill du utesluta node_modules . Du vill inte commit node_modules till versionskontroll, eftersom den innehåller ett stort antal filer som kan återskapas av npm install .

Skapa en .gitignore -fil i roten av ditt projekt:

 echo "node_modules" >> .gitignore

Detta säkerställer att node_modules inte spåras av git och inte kommer att skickas till ditt arkiv.

Steg 4: Uteslut tester från det publicerade paketet

Även om du kommer att köra tester under CI, vill du inte att testfilerna inkluderas i ditt publicerade npm-paket. Detta håller paketet rent, har en liten buntstorlek och säkerställer att endast de nödvändiga filerna skickas till användarna.

Skapa en .npmignore fil i rotmappen och lägg till testfilnamnen.

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

Detta säkerställer att testfilerna inte ingår när du kör npm publish .

Steg 5: Värd din kod på GitHub

1. Skapa ett nytt GitHub-förråd:
   • Gå till https://github.com/new och skapa ett arkiv alphanumeric-validator .

2. Tryck på din kod

    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 

Steg 5: Initial manuell publicering till npm

• Innan du startar automatiseringen, bekräfta att ditt paket kan publiceras – se här.
• Lägg sedan till flaggan --access public för att göra ditt paket offentligt och tillgängligt för användare.

 npm login npm publish --access public 

• Besök https://www.npmjs.com/package/alphanumeric-validator för att verifiera att den ursprungliga versionen är live.

  
  

Steg 6: Konfigurera arbetsflödet för GitHub Actions

Du måste konfigurera ett arbetsflöde som körs på varje releasehändelse så att när du skapar en ny release (som v1.0.1 ):

• Arbetsflödet kontrollerar din kod.
• Installerar beroenden.
• Kör tester för att säkerställa kvalitet.
• Uppdaterar package.json till den nya versionen från releasetaggen.
• Publicerar det uppdaterade paketet till npm utan att inkludera testfiler.

Arbetsflödesfilen

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

Lägga till din NPM-token till GitHub

• Besök https://www.npmjs.com/settings/:username/tokens/new (se till att du ersätter :username med ditt faktiska användarnamn)
• Ange namnet, välj automatisering för typen och generera

• Du kommer att omdirigeras till sidan för tokens, där du kan kopiera token.

• Gå till Inställningar > Hemligheter och variabler > Åtgärder i ditt GitHub-förråd.

• Klicka på New Repository Secret och lägg till NPM_TOKEN .

  
  

  

Steg 7: Skapa en ny version

Låt oss säga att du vill lägga till README.md för version v1.0.1 och du har drivit den:

1. Utkast till en ny release:
   • Gå till avsnittet Releases i din GitHub-repo. [ https://github.com/username/repo/releases ]
   • Klicka på Utkast till en ny version .
   • Ställ in "Tagversion" till v1.0.1.
   • Klicka på Publicera release .

2. Arbetsflöde utlöst: Releasehändelsen utlöses. Arbetsflödet,
   • Kollar koden.
   • Installerar beroenden.
   • Kör tester. Om testerna misslyckas stoppas jobbet och paketet publiceras inte.
   • Om testerna blir godkända uppdaterar den package.json till 1.0.1 .
   • Publicerar version 1.0.1 till npm, exklusive testfiler.

3. Verifiera på npm: Efter en stund, besök din npm-paketsida för att se den nya versionen live.

Slutsats

Att integrera GitHub Actions i ditt npm-publiceringsarbetsflöde etablerar en fantastisk CI/CD-pipeline. Med varje ny release körs en omfattande serie tester, package.json uppdateras med rätt version och ett strömlinjeformat paket publiceras till npm – fritt från onödiga filer som tester.

Det här tillvägagångssättet sparar tid, minskar mänskliga fel och förbättrar tillförlitligheten för dina utgåvor, vilket gör det lättare för bidragsgivare att se sitt arbete gå live sömlöst.

En enda GitHub-version är nu allt som krävs för att skicka ett fullt testat, korrekt versionerat paket till npm-registret.