Tworzymy własną bibliotekę w npm!

Ostatnio napisałem dość przydatną funkcję, którą fajnie by było się podzielić. Dodajmy więc ją do rejestru npm, tak by każdy programista mógł skorzystać z jej dobroci

W ostatnim wpisie napisaliśmy funkcję w JS, która dodaje nowe zdarzenia swipe do dokumentu. Podobnie napisanego gotowego rozwiązania w sieci nie znalazłem, toteż chciałbym pomóc innym programistom szukającym rozwiązania na szybko i podzielić się z nimi swoim kodem. Świetnie do tego spiszę się npm - menadżer pakietów w Node.js, dzięki któremu zainstalujemy bibliotekę za pomocą jednego szybkiego polecenia npm install. O npm przeczytasz więcej tutaj Przejdźmy zatem do pracy.

Co potrzebujemy?

Pierwszym krokiem do stworzenia własnej biblioteki jest oczywiście kod, który chcemy udostępnić dla innych. Wiąże się to z tym, że wybrana przez nas licencja będzie musiała być bardzo otwarta dla wszystkich potencjalnych użytkowników kodu. Ale do tego przejdziemy później.

Ponadto, musimy mieć konto w rejestrze npm (można się zarejestrować na oficjalnej stronie menadżera) oraz konto na jednym z portali do obsługi gita (post będzie opisany na przykładzie GitHuba). I to w zasadzie wszystko.

npm init

Zacznijmy od stworzenia katalogu, który będzie zawierał kod oraz wszystko inne, co potrzebne do opublikowania tego kodu. Tutaj pierwsza ważna rzecz - zastanówmy się w tym miejscu, jaką nazwę chcemy wybrać dla biblioteki. Npm to ogromny rejestr z ponad półtora milionem dostępnych do pobrania paczek. Jest więc bardzo prawdopodobne, że prosta i przystępna nazwa będzie już zajęta - a to oznacza, że nie będzie można dodać nowej biblioteki do rejestru. Ja po ówczesnym sprawdzeniu, czy nikt inny nie stworzył wcześniej takiej paczki, wybrałem nazwę swipe-touch-events. Stworzyłem więc katalog o takim samym łancuchu, a do niego wrzuciłem plik index.js ze wcześniej napisanym kodem.

zdjęcie tematyczne
katalog biblioteki
//swipe-touch-events/index.js

(function (element = document, threshold = 50) {
  let startingX = 0;
  let startingY = 0;
  let movementX = 0;
  let movementY = 0;
  let target;

  const updateMovement = (e) => {
    const { clientX, clientY } = e.touches[0];

    movementX = startingX - clientX;
    movementY = startingY - clientY;
  };

  element.addEventListener('touchstart', (e) => {
    const { clientX, clientY } = e.touches[0];
    target = e.target;

    startingX = clientX;
    startingY = clientY;

    document.addEventListener('touchmove', updateMovement);
  });

  document.addEventListener('touchend', (e) => {
    document.removeEventListener('touchmove', updateMovement);

    let eventType;

    if (movementX > threshold && movementX >= movementY) eventType = 'swipeleft';
    else if (movementY > threshold && movementY >= movementX) eventType = 'swipeup';
    else if (movementX < -threshold && movementX <= movementY) eventType = 'swiperight';
    else if (movementY < -threshold && movementY <= movementX) eventType = 'swipedown';
    else return;

    const event = new Event(eventType, { bubbles: true });
    target.dispatchEvent(event);
  });
})();

Mamy przygotowany katalog. Na tym etapie trzeba będzie uwierzytelnić swoje konto w npm. Wpiszemy więc w konsoli:

npm login

VSCode poprosi nas wtedy o wpisanie loginu do konta oraz hasła, a następnie opcjonalnego maila. Ważnym jest tutaj, żeby mieć aktywowane konto na npm - bez tego nie zrobimy nic w rejestrze! Po udanej autoryzacji możemy już pracować z rejestrem. Zanim jednak to, najpierw zainicjujemy nowy moduł npm. Do tego celu wpiszmy:

npm init

i wybierzmy kolejno wszystkie opcje dla naszego pakietu:

package name: (swipe-touch-events)
version: (1.0.0)
description: Javascript based library that allow use swipe-touch events on DOM
entry point: (index.js)
test command:
git repository:
keywords: javascript, js, events, DOM, html, es6, swipe, touch
author: Damian Kalka
license: (ISC)

Wszystkie te informacje są wykorzystywane przez npm jako metadane w rejestrze. Możemy je zmieniać w każdym momencie, więc test command, git repository i license będziemy mogli zmienić za chwilę. Jeśli nie jesteś pewny co wybrać, wciśnij enter przy opcji - wtedy zostanie wybrana wartość domyślna.

Repozytorium

Ważnym jest, by do załączonego kodu przypisać zdalne repozytorium. Nie jest to wymagane, ale stanowi istotny element dokumentacji, więc zalecam to zrobić. Przed tym musimy zautoryzować konto na jednym z portali do obsługi gita (np. GitHub, GitLab, BitBucket) z naszym VSC. Kiedy już to zrobimy, przejdziemy do utworzenia repozytorium.

zdjęcie tematyczne
tworzenie repozytorium na GitHubie

Podczas tworzenia repo wybierzmy opcje dodania README.md, w której umieścimy dokumentację dotyczącą kodu oraz wybierzmy licencję. Ja wybrałem licencję MIT, która jest jedną z najbardziej wolnych licencji i jedynym warunkiem na używanie kodu jest przechowywanie informacji o autorze w źródle oraz zachowanie warunków licencji. Dobierz licencję do własnych preferencji.

Teraz dodajemy adres zdalnego repo do projektu za pomocą konsoli i w pliku package.json.

//package.json
// ...
"repository": {
    "type": "git",
    "url": "https://github.com/kalkson/swipe-touch-events"
  },
// ...
git init
git remote add origin https://github.com/kalkson/swipe-touch-events

I zamieśćmy kod na repo:

git pull origin main
git checkout main
git add .
git commit -m '1.0.0 release'
git push origin main

Publikowanie

Ostatnim krokiem do stworzenia pierwszej biblioteki jest użycie polecenia:

npm publish

I lada moment paczka pojawi się w rejestrze na npm (dostępna pod linkiem https://www.npmjs.com/package/swipe-touch-events) - udało się stworzyć pierwszą publiczną bibliotekę, która może pomóc innym! :) Jeśli wszystko poszło pomyślnie, możemy zainstalować moduł dzięki poleceniu:

npm install swipe-touch-events

i zaimportować go za pomocą:

import 'swipe-touch-events';

Jeśli nie wiesz jak działa napisana przeze mnie biblioteka swipe-touch-events, przeczytaj o niej na dokumentacji w npm tutaj lub przeczytaj poprzedni wpis na blogu gdzie tłumaczyłem krok po kroku w jaki sposób ją pisałem i jaki problem rozwiązuje. A tymczasem, do zobaczenia!

© Damian Kalka 2021
Wszelkie prawa zastrzeżone