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:
# 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 bibliotekigit commit -m "initial commit"
- nazywamy wersje projektugit remote add origin https://github.com/[nick github]/[nazwa repozytorium].git
- podpinamy projekt pod repozytoriumgit 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 :)