Predpokladám, že každý kto sa s npm už stretol, vie minimálne nainštalovať, použiť a odinštalovať package. Preto preskočím úvod a prejdem rovno k tomu, ako dostať vlastný modul do databázy npm, aby bol verejne dostupný. Ak by sme chceli, aby bol modul privátny, teda dostupný len určitým ľudom, musíme si zriadiť platené konto.

Súbor package.json

V skutočnosti môžeme publikovať každý priečinok, ktorý obsahuje súbor package.json. Tento súbor určite väčšina developerov pozná. Je to súbor, ktorý obsahuje informácie o aplikácii alebo module. Musí však obsahovať minimálne:

• name - názov modulu
• version - verziu modulu

name

Názov modulu musí byť jedinečný, aby nekolidoval s iným názvom v npm registri a mal by dodržiavať npm policy. Je možné názov package aj prefixovať, tak ako v našom prípade - @odyzeo/pluralize. Ak sa však pokúsime publikovať takýto modul, dostaneme error:

npm ERR! publish Failed PUT 402
npm ERR! code E402
npm ERR! You must sign up for private packages : @odyzeo/pluralize

Error nastane z dôvodu, že scoped (prefixované) moduly sú automaticky privátne, a teda platené. BTW platené konto stojí momentálne 7$/mesiac pre jednotlivca.

My však chceme, aby bol náš modul verejný. Náš príkaz bude tak pri publikovaní vyzerať nasledovne (spoiler alert).

npm publish —access=public

version

Verzia nášho modulu. Pri každom publikovaní musí byť iná a vo formáte major.minor.patch:

major - ak robíme nekompatibilné zmeny s predchádzajúcimi verziami
minor - robíme zmeny funkcionality so spätnou kompatibilitou
patch - fixujeme bugy so spätnou kompatibilitou

https://semver.org/

Súbor package.json vytvoríme buď manuálne, alebo jednoduchšie, príkazom:

npm init

Defaultný package.json, ktorý sa predvyplní obsahom priečinku, v ktorom sa nachádzame, vytvoríme príkazom:

npm init -y

Keď postupne prejdeme celým procesom, vznikne nám niečo takéto:

• description - stručný popis modulu
• main - východzí súbor modulu
• scripts - príkazy, ktoré pomáhajú pri developovaní
• test - príkazy na spustenie testov
• keywords - kľučové slová, podľa ktorých vieme náš modul vyhľadať
• repository - odkaz na repozitár, k tomu sa ešte dostaneme
• author - autor modulu
• licence - licencia, pod ktorou sa modul môže používať

Dôležitá je aj časť dependencies, ktorá obsahuje zoznam modulov s verziami, ktoré sú potrebné pre správne fungovanie modulu. Prípadne devDependencies, zoznam modulov potrebných pre vývoj modulu, ktoré avšak nie sú potrebné pre jeho používanie. Náš mini modul je čistý, a preto nepotrebuje žiadne závislosti :)

Vytvorenie konta

Aby sme mohli modul publikovať, musíme mať vytvorené konto v npm registri. To si vytvoríme ľahko, zaregistrovaním na stránkach https://www.npmjs.com/signup, alebo v termináli priíkazom:

npm adduser

Ak už konto máme, prihlásime sa príkazom:

npm login

Na stránke https://www.npmjs.com/~username nájdeme svoj npm profil ak username nahradíme svojim loginom.

Súbor .gitignore

Všetky súbory v priečinku, v ktorom sa nachádzame, budú publikované, takže ak sa za niektoré hanbíme a nechceme ich svetu ukázať, zahrnieme ich do .gitignore súboru. Viac na stránkach git basics.

Chcelo by to nejaký kód

Pre ukážku publikovania modulu do npm si napíšeme pár riadkov zbytočného kódu. Nie je to žiaden prelomový startup, len nám to vráti správny slovenský tvar množného čísla zadaného slova. Určite vám hneď napadne x lepších riešení, ale kód v našom prípade nehrá rolu. Takže len pre ukážku:

Dokumentácia v readme.md

Aj keď do dokumentácie sa nám developerom veľmi nechce, vždy ich s obľubou čítame. Aby sme uľahčili život tým, ktorí budú modul používať, je rozumné tento súbor vytvoriť. Prípona .md hovorí, že je súbor napisaný v jazyku Markdown. Určite si už každý developer čítal readme, takže má predstavu, že by mal obsahovať inštrukcie, čo daný modul robí, ako sa inštaluje a ako sa používa.

Tento súbor sa zobrazuje na úvodnej stránke modulu na stránkach npm a takisto aj v git repozitári ... git čo?

Git

Každý pozná, videl, zvíťazil. Je pekné prepojiť package priamo s git repozitárom. Aby nám ostatní developeri mohli hejtovať kód. Ten sa väčšinou nachádza na GitHub-e a s naším modulom sa prepojí veľmi jednoducho, pridaním pár riadkov do súboru package.json:

"repository": {
  "type": "git",
  "url": "https://github.com/odyzeo/pluralize.git"
},

Poďme publikovať!

Ak je náš modul odladený, otestovaný a pripravený uzrieť svetlo sveta, spustíme príkaz:

npm publish

V našom prípade:

npm publish —access=public

To je všetko. Na stránke npm nájdete svoj modul s aktuálnou verziou:

@odyzeo/pluralize

npm nám pošle pochvalný email, že náš modul je úspešne publikovaný a pripravený na použitie.

Collaborators alebo spolupracovníci

Ak na module pracuje viac zodpovedných(!) developerov, pridáme im práva publikovať modul nasledovným príkazom:

npm owner add [username]

Ďalšie verzie

Ako sme už spomínali, každé publikovanie packagu musí obsahovať unikátnu verziu. Samozrejme sa nám nechce meniť verzie ručne, a preto nám npm vytvoril príkaz:

npm version [major|minor|patch]

Takto nám vznikne commit, ktorý inkrementuje verziu modulu v súbore package.json. Zmeny stačí už len push-núť a modul publikovať s novou verziou.

git push
npm publish

Changelog

Best practice je zmeny v každej verzii popísať, aby developeri vedeli, ako sme náš modul vylepšili. A hlavne, čo sme fixli. S tým nám vie pomôcť časť Releases na GitHub-e, kde si to vieme vyklikať a hlavne otagovať verziu, aby sme sa vedeli v projektoch odvolať na konkrétnu a niekomu sme nerozbili projekt upraveným kódom.

Prečo toto všetko?

Ako frontend programátori dookola zobrazujeme, filtrujeme a transformujeme dáta. Po pár projektoch zistíme, že robíme to isté, a tak namiesto kopírovania kúskov kódu a zliepania z projektu do projektu, je lepšie obetovať pár chvíľ a ten opakovaný kúsok kódu vyabstrahovať do prepoužiteľnej funkcionality v podobe samostatného modulu. Koleso už bolo vynájdené mnohokrát, nájdeme ho v npm.

Ďakujem za pozornosť. Veľa hviezdičiek a málo issues prajem.