Hoe om u NPM-pakket outomaties met GitHub-aksies te publiseer

Die outomatisering van jou npm-pakketpubliseringsproses met deurlopende integrasie en aflewering (CI/CD) verseker dat elke vrystelling deur 'n kwaliteithek – jou toetssuite – gaan voor publikasie. Terselfdertyd kan jy presies beheer wat in die finale gepubliseerde pakket beland deur toetslêers uit te sluit. In hierdie gids sal jy leer hoe om CI/CD op te stel vir 'n eenvoudige npm-pakket - 'n alfanumeriese valideerder - sodat elke nuwe GitHub-vrystelling toetse aktiveer, die pakketweergawe opdateer en outomaties 'n skoon pakket na npm publiseer.

Waarom outomatiseer npm-publisering?

Handmatige npm-publisering kan tydrowend en foutgevoelig wees, veral namate jou projek groei en bydraers kry. Deur die proses te outomatiseer, kan jy:

• Verseker kwaliteit: Voer outomaties toetse uit voordat dit gepubliseer word. As toetse misluk, word die nuwe weergawe nie vrygestel nie.
• Konsekwente weergawe: Die gepubliseerde pakketweergawe pas altyd by die vrystellingmerker.
• Wrywinglose samewerking: Bydraers dien kode in, jy skep 'n vrystelling, en die pyplyn doen die res - geen spesiale npm-toestemmings word vereis nie.

Voorvereistes

1. Node.js & npm:
   • Klik hier as jy nie NodeJS en NPM geïnstalleer het nie.
   • Bevestig installasie deur die kode hieronder in jou terminaal uit te voer.

 node -v npm -v

2. GitHub-rekening en -bewaarplek:
   • Jy het 'n GitHub-bewaarplek nodig om kode te stoor en GitHub-aksies uit te voer.
3. NPM-rekening en toegangsteken:
   • Registreer of meld aan by npmjs.com en genereer 'n toegangsteken.
   • Voeg die toegangsteken as 'n geheim by jou GitHub-bewaarplek vir outomatiese publisering.

Stap 1: Stel die projek op

Ons sal 'n eenvoudige alphanumeric-validator skep wat 'n funksie uitvoer wat kontroleer of 'n string alfanumeries is.

1. Inisialiseer die projek

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

2. Dateer package.json op soos nodig. Vir die alphanumeric-validator sal dit so lyk.

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

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

Stap 2: Voeg toetse plaaslik by en voer dit uit

Toets verseker dat jy nie gebroke kode publiseer nie.

1. Installeer Jest

    npm install --save-dev jest

2. Skep 'n toetslêer

    mkdir tests

3. Plak die kode hieronder in die tests/index.text.js -lêer.

    // 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. Doen toetse

    npm test 

Slaag toetse? Groot. Nou sal ons verseker dat hierdie toetse in CI uitgevoer word voordat dit gepubliseer word.

Stap 3: Sluit nodemodules uit van Git

Voordat u na Github publiseer, wil u die node_modules uitsluit. Jy wil nie node_modules verbind tot weergawebeheer nie, aangesien dit 'n groot aantal lêers bevat wat deur npm install herskep kan word.

Skep 'n .gitignore lêer by die wortel van jou projek:

 echo "node_modules" >> .gitignore

Dit verseker dat node_modules nie deur git nagespoor word nie en nie na jou bewaarplek gedruk sal word nie.

Stap 4: Sluit toetse uit die gepubliseerde pakket uit

Terwyl jy toetse sal uitvoer tydens CI, wil jy nie hê dat die toetslêers by jou gepubliseerde npm-pakket ingesluit word nie. Dit hou die pakket skoon, het 'n klein bondelgrootte en verseker dat slegs die nodige lêers aan gebruikers gestuur word.

Skep 'n .npmignore lêer in die wortelgids en voeg die name van die toetslêer by.

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

Dit verseker dat die toetslêers nie ingesluit word wanneer jy npm publish laat loop nie.

Stap 5: Hou jou kode op GitHub aan

1. Skep 'n nuwe GitHub-bewaarplek:
   • Gaan na https://github.com/new en skep 'n alphanumeric-validator bewaarplek.

2. Druk jou kode

    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 

Stap 5: Aanvanklike Handmatige Publiseer na npm

• Voordat u die outomatisering begin, bevestig dat u pakket gepubliseer kan word —sien hier.
• Voeg dan die --access public vlag by om jou pakket publiek en toeganklik vir gebruikers te maak.

 npm login npm publish --access public 

• Besoek https://www.npmjs.com/package/alphanumeric-validator om te verifieer dat die aanvanklike weergawe regstreeks is.

  
  

Stap 6: Stel die GitHub Actions-werkvloei op

Jy moet 'n werkvloei opstel wat op elke vrystellinggebeurtenis loop, sodat wanneer jy 'n nuwe vrystelling skep (soos v1.0.1 ):

• Die werkvloei kyk na jou kode.
• Installeer afhanklikhede.
• Voer toetse uit om kwaliteit te verseker.
• Dateer package.json op na die nuwe weergawe vanaf die vrystellingmerker.
• Publiseer die opgedateerde pakket na npm sonder om toetslêers in te sluit.

Die werkvloeilêer

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

Voeg jou NPM-token by GitHub

• Besoek https://www.npmjs.com/settings/:username/tokens/new (Maak seker jy vervang :username met jou werklike gebruikersnaam)
• Voer die naam in, kies outomatisering vir die tipe en genereer

• Jy sal na die tokens-bladsy herlei word, waar jy die token kan kopieer.

• Gaan na Instellings > Geheime en veranderlikes > Aksies in jou GitHub-bewaarplek.

• Klik New Repository Secret en voeg NPM_TOKEN by.

  
  

  

Stap 7: Skep 'n nuwe vrystelling

Kom ons sê jy wil README.md byvoeg vir v1.0.1 vrystelling, en jy het dit gedruk:

1. Stel 'n nuwe vrystelling op:
   • Gaan na die Vrystellings -afdeling in jou GitHub-repo. [ https://github.com/username/repo/releases ]
   • Klik Konsep 'n nuwe vrystelling .
   • Stel die "Tag weergawe" na v1.0.1.
   • Klik Publiseer vrystelling .

2. Werkvloei geaktiveer: Die vrystellinggebeurtenis begin. Die werkstroom,
   • Kyk na die kode.
   • Installeer afhanklikhede.
   • Doen toetse. As toetse misluk, stop die werk en sal die pakket nie gepubliseer word nie.
   • As toetse slaag, dateer dit package.json op na 1.0.1 .
   • Publiseer die 1.0.1 weergawe na npm, toetslêers uitgesluit.

3. Verifieer op npm: Besoek na 'n oomblik jou npm-pakketbladsy om die nuwe weergawe regstreeks te sien.

Gevolgtrekking

Deur GitHub-aksies in u npm-publiseringswerkvloei te integreer, word 'n wonderlike CI/CD-pyplyn geskep. Met elke nuwe vrystelling word 'n omvattende reeks toetse uitgevoer, package.json word met die korrekte weergawe opgedateer, en 'n vaartbelynde pakket word na npm gepubliseer—vry van onnodige lêers soos toetse.

Hierdie benadering bespaar tyd, verminder menslike foute en verhoog die betroubaarheid van jou vrystellings, wat dit makliker maak vir bydraers om te sien dat hul werk naatloos aan die gang kom.

'N Enkele GitHub-vrystelling is nou al wat nodig is om 'n volledig getoetste, behoorlik weergawe-pakket na die npm-register te stuur.