Lag din egen NPM-pakke!

Recap

NPM (node package manager) er et verktøy vi bruker for å håndtere pakker i prosjektene våre. En pakke kan sees på som et bibliotek som hjelper oss når vi koder. Dere har kanskje hørt om moment.js. Det er en pakke vi bruker for å håndtere tid og dato. Det abstraherer bort mye logikk, og gir oss i stedet enkle api-kall vi kan bruke.

Et eksempel:
moment().format(""MMM Do YY")
Hvis vi laster inn moment i prosjektet vårt, kan vi bruke moment sin format() metode for å formatere datoer.

Alle npm pakker må være et node prosjekt, altså må de ha en package.json fil. Denne filen inneholder ting som versjonsnummer og navn på pakken. Den autogenereres hvis man utfører kommandoen npm init fra prosjektmappen.

Du trenger:

• Innhold til pakken du skal lage
• npm CLI
• npm bruker

Innhold til pakken

Hva ønsker du å lage? En random-number-generator, en norwegian-id-validator? Det er mye som finnes fra før av, men det betyr ikke at det er optimalt for ditt bruk.

Moment pakken som nevnt over er en av de mest populære pakkene, men for applikasjoner hvor ytelse er svært viktig, kan den forårsake mye overhead fordi den har et ganske komplekst api og har en stor bundle size.

Lag prosjektet

Innholdet til pakken vi lager i dette eksempelet skal være en metode som logger "Hello World!".

$ mkdir hello-world   // Lager en mappe til prosjektet vårt
$ cd hello-world
$ npm init                     // Initialiserer prosjektet
$ touch index.js

Det er viktig at navnet man setter i package.json er unikt. https://remarkablemark.org/npm-package-name-checker/

Så legger vi til følgende kode i index.js

const greetings = () => {
    console.log("Hello World!")
}

module.exports = { greetings };

module.exports definerer hva som blir tilgjengelig fra pakken

NPM bruker

For å kunne publisere pakker til npm sitt pakke-bibliotek må vi ha en npm bruker.
Lag en bruker PS! Viktig at man verifiserer email for å få publisere pakker

$ npm whoami   // Sjekk om du allerede er innlogget

$ npm adduser    // For å logge inn

Publiser pakken!

$ npm publish
.. og verre var det ikke!

La oss bruke pakken

For å teste at pakken vi lagde fungerer kan vi lage et nytt prosjekt og importere pakken.

$ mkdir test-npm-package
$ cd mkdir test-npm-package
$ npm init
$ npm install hello-world
$ touch index.js

index.js:

import { greeting } from "hello-world"
greeting()

For at vi skal kunne bruke import i stedet for require for å importere pakken må vi spesifisere at prosjektet er av typen module i package.json. Test om det fungerte ved å kjøre node ./index.js

Auto-publish med github actions

Hvis vi ønsker å automatisere prosessen, kan vi laste opp prosjektet på github, og bruke github actions til å publisere.

Opprette github repo

1. Opprett et github repo
2. Initier prosjektet som et github repo og commit endringene

$ git init
$ git add .
$ git commit -m "First commit"

3. Legg til URL'en til remote repo, og push endringene

git remote add origin https://github.com/mariannemagnussen/hello-world.git
git branch -M main
git push -u origin main

Sett opp github actions

Github actions er et verktøy for å automatisere arbeidsflyten (CI). Det lar oss bygge, teste, og deploye kode rett fra github, i tillegg til mye annet.

For å lage en github action må vi opprette en workflow fil av typen YAML i prosjektet vårt. Det kan vi både gjøre lokalt og direkte på github. Det er viktig at filen ligger på følgende path for at github skal oppdage den: [root]/.github/workflows/npm-publish.yml

1. Opprett filen npm-publish.yml
2. Legg til følgende kode:

name: NPM Publish

on:
  release:
    types: [released]

jobs:
  Publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: 12
          registry-url: https://registry.npmjs.org/
      - run: npm install
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

La oss gå gjennom koden: | Felt | Beskrivelse | | ----------- | ----------- | | name | navnet på jobben | | on | når vi ønsker at jobben skal kjøres. Her sier vi at den skal kjøre på hver merge til main | | jobs | her legger vi hvilke jobber som skal utføres | | build | oppsett for jobben | | runs-on | hvilket operativsystem jobbene skal kjøres på | | steps | de ulike stegene jobben består av | | uses: | setter opp miljøet. actions/checkout@v2 kloner repoet actions/setup-node@v1 installerer node | | run | kommandoene / selve jobben | | env | variabler som trengs for å utføre jobben |

Siden vi nå ikke publiserer fra lokal maskin, må vi bruke et token for å autentifisere oss: secrets.NPM_TOKEN.

1. Gå til https://www.npmjs.com/settings/mariannemagnussen/tokens og generer et nytt token
2. Kopier tokenet!
3. Gå til settings i repoet på github --> secrets --> new repository secrets. Lagre tokenet der under navnet NPM_TOKEN.

Før vi tester om det funker må vi legge til endringene på git. For å få lov til å publisere en ny versjon må vi også bumpe versjonsnummeret i package.json.

Test om det funker

Fra repoet på github, trykk på create release. Skriv inn versjonen fra package.json på release version. Release title kan være det du ønsker. Publish release.

Hvis du nå går inn på github actions kan du se at den kjører jobben. Og hvis alt går som planlagt, blir den suksess og en ny versjon av pakken ligger på npm!

Fjern pakken

npm unpublish <package-name> -f