Jak stworzyć bibliotekę i dodać do NPM?

Tym razem zrobimy coś innego, odbiegającego od reszty kursów. Na przykładzie mojej biblioteki pokażę wam jak stworzyć i dodać coś swojego do NPM. Chyba każda osoba pisząca w Javascript ma pojęcie czym jest środowisko Node.JS i zbudowany (początkowo tylko dla niego) manager bibliotek JS. NPM jest obecnie największym na świecie tego typu managerem i osobiście wychodzę z założenia, że jeśli nie ma czegoś w NPM, to nie da się tego zrobić :) Zaczynajmy!

«!–more–></!–more–>

# Joeyify - automatyczny słownik synonimów

Dzięki bibliotece, którą stworzyłem możemy zastosować w tekście automatyczny słownik synonimów, czyli tzw. Thesaurus. Moja biblioteka została stworzona dla żartu, zainspirowana sceną z serialu "Friends", dlatego też zamienia automatycznie każde napotkane słowo na synonim. Poza celami humorystycznymi, biblioteka nie ma zastosowań, ale zdecydowałem że jest świetnym przykładem do opisu - jak dodać bibliotekę do NPM.

Więcej informacji na temat biblioteki można znaleźć na jej stronie - Joeyify w NPM

# Konfiguracja biblioteki JavaScript

Pierwszym krokiem będzie utworzenie pliku package.json - wystarczy tylko w konkretnym folderze za pomocą CMD użyć komendy npm init. W terminalu pojawi się wiele pytań, na które możemy udzielić informacji, bądź pominąć za pomocą przycisku enter.

Po inicjalizacji npm należałoby teraz zainstalować biblioteki, z których wasza biblioteka będzie korzystać. W moim przypadku jest to znaleziona w NPM biblioteka "Thesaurus". Biblioteki dodajemy za pomocą komendy CMD - npm install [package_name] --save, czyli w moim przypadku npm install thesaurus --save.

Czy jest różnica między bibliotekami potrzebnymi do uruchomienia naszej biblioteki, a tymi wykorzystywanymi do jej budowy?

Biblioteki, które dodajemy tylko dla siebie i ludzi, którzy będą uczestniczyli w naszym projekcie dodajemy za pomocą npm install [package_name] --save-dev. Dzięki temu, użytkownik, który będzie chciał użyć Joeyify w swoim projekcie, nie pobierze niepotrzebnych bibliotek.

W moim przypadku jako devDependencies dodałem biblioteki do testowania - Mocha i Chai. A tak wygląda finalny plik package.json mojej biblioteki:

Pamiętaj także, żeby dodać do folderu plik .gitignore zawierający w treści - /node_modules. Dzięki temu zamiast całych bibliotek do NPM i do GitHub dodany będzie tylko plik package.json

# Jak stworzyć bibliotekę JavaScript?

Gdy nasza biblioteka jest już skonfigurowana, należy zabrać się za stworzenie jej funkcjonalności. Przedstawię pliki biblioteki Joeyify, które dostępne są w repozytorium na GitHubie - Joeyify GitHub

Jako że biblioteka jest niewielka i bardzo prosta - całe jej ciało znajduje się w zaledwie jednym pliku - joeyify.js. Na samym jego początku musimy zaimportować biblioteki, które będą nam potrzebne. W moim przypadku dodaję Thesaurus - const thesaurus = require("thesaurus");.
W tym momencie możemy używać zmiennej thesaurus do wywoływania biblioteki.

Następnym krokiem jest stworzenie funkcji, która będzie zawierała cały kod biblioteki. Funkcja ta musi być przypisana do module.exports, żeby można było się do niej odwoływać z innego pliku.

Moja biblioteka składa się z funkcji pomocniczych i wartości zwracanej. Na początku biblioteka przyjmuje argument text, który zawiera przekazany tekst i zwraca mapowany wynik. Jeśli nie znasz jeszcze funkcji map, to zapraszam do jednego z wcześniejszych postów na tym blogu - https://www.idaszak.com/article/2017/05/31/podstawy-programowania-funkcyjnego-3-map-i-filter.

Nie będę zagłębiał się w szczegóły implementacji biblioteki, jako że nie jest to programistyczne arcydzieło i zarazem nie to jest istotą tego postu. Jeśli chcesz upewnić się, czy twoja biblioteka działa, spróbuj zwrócić dowolną wartość w return

Plik JavaScript zwracający wartość string - "testowy moduł".

Teraz spróbujemy odebrać tą wartość w pliku, który skorzysta z biblioteki.

Zgodnie z przykładem ze strony NPM Joeyify, wystarczy stworzyć nowy plik, w którym użyjemy const joeyify = require("./joeyify");. W momencie wywołania zmiennej joeyify, powinna pokazać się ta zwracana wartość, lub jeśli korzystasz z mojej biblioteki to wywołanie powinno wyglądać w taki sposób:

Wystarczy teraz tylko użyć komendy node [nazwa_pliku].js z plikiem wykorzystującym bibliotekę. Jak widać, Joeyify wyszukuje słów, pomijając znaki interpunkcyjne i zamienia je na przypadkowe synonimy.

# Jak napisać testy jednostkowe?

W przypadku tworzenia biblioteki, warto upewnić się czy poszczególne jej elementy działają zgodnie z założeniem. Odpowiemy sobie na pytanie - w jaki sposób napisać testy w Node.js. Wykorzystałem jeden z najpopularniejszych zestawów narzędzi do testowania czyli Mocha + Chai.

Utworzyłem w projekcie folder test, w którym umieściłem plik joeyify.spec.js z testami biblioteki. Cały test można znaleźć w repozytorium Joeyify, a poniższy przykład ograniczyłem do jednego testu:

Biblioteka Chai, pozwala na trzy style pisania testów - Assert, BDD - expect lub should. W powyższym przykładzie skorzystałem z should stylu Behaviour Driven Development. Dodałem je za pomocą var should = require('chai').should();.

BDD polega na tworzeniu "opowieści" w testach za pomocą tekstu. Przykładowy test może nazywać się - "#Synonyms - dot is unchanged", ale warto tworzyć jeszcze bardziej opisowe nazwy, żeby można było łatwiej zidentyfikować testy.

Następnie dodaję moją bibliotekę, żeby testy mogły ją wykonywać - var joeyify = require('../joeyify');. Blok describe() Zaczyna zestaw testów rozpoczynających się blokiem it(). joeyify('.').should.equal('.'); - Przekazuje w nim jako parametr string "." i oczekuje że biblioteka zwróci go bez zmian, jako że Joeyify powinien ignorować znaki interpunkcyjne.

Testy uruchamiamy komendą terminala - "npm test". Poniżej screen z wykonanymi wszystkimi testami biblioteki:

wykonane testy jednostkowe

# Dodajemy bibliotekę do NPM

W tym momencie, biblioteka jest już skończona i gotowa do opublikowania w NPM. Na początek jednak, musimy wrzucić je do repozytorium GIT. Pisałem już na ten temat w poście Github w 2 minuty, ale wspomnę o tym skrótowo:

Na naszym koncie GitHub musimy stworzyć repozytorium, a następnie użyć kolejno komend:

git add . - dodajemy wszystkie pliki biblioteki
git commit -m "initial commit" - nazywamy wersje projektu
git remote add origin https://github.com/[nick github]/[nazwa repozytorium].git - podpinamy projekt pod repozytorium
git push -u origin master - wypychamy kod na GitHub

W momencie gdy nasz kod jest już publicznie dostępny w serwisie GitHub, możemy zająć się publikacją biblioteki w NPM.

Załóż konto na stronie https://www.npmjs.com/ i zaloguj się w terminalu za pomocą npm login. Nazwę biblioteki jak i wszystkie informacje muszą być dodane w pliku package.json. Musimy stworzyć także plik readme.md w którym opisane jest zastosowanie biblioteki, przykłady użycia i informacje dla ludzi, którzy mieliby ochotę pomóc w jej rozwoju.

Finalny krok! w terminalu wpisz npm publish.

Twoja biblioteka powinna teraz być opublikowana na stronie https://npmjs.com/package/[nazwa biblioteki].

Z poziomu terminala spróbuj zrobić npm install [nazwa biblioteki] i upewnij się że wszystko działa poprawnie.

# Podsumowanie

Gratulacje! masz już pierwszą bibliotekę w NPM. Jeżeli wystąpiły problemy, to spójrz do dokumentacji NPM https://docs.npmjs.com/. Możesz teraz obserwować na stronie bliblioteki w NPM - liczniki pobrań, albo czekać na zgłoszenia ewentualnych bugów w serwisie GitHub :)