Pierwsze kroki

Ten przewodnik przeprowadzi Cię przez proces tworzenia pierwszego modułu Orbito – od pustego katalogu do działającego kodu zarejestrowanego w platformie.

Wymagania wstępne

Zanim zaczniesz, upewnij się, że masz zainstalowane:

• Node.js w wersji 18.13 lub nowszej
• npm (instalowany razem z Node.js)
• omm – CLI do publikacji i testowania modułów: npm i -g @orbito/omm. Paczki @orbito/* nie są na npmjs.org — najpierw ustaw ich rejestr (raz na komputer, bez tokenu), zob. Instalacja omm
• Konto w Orbito (my.orbi.do) z firmą, na której będziesz testować moduł — to samo konto loguje do repozytorium modułów (modules.orbito.pl)
• Namespace w repozytorium modułów (własny albo zaproszenie od jego właściciela) — patrz Konto i namespace'y

Tworzenie pierwszego modułu

1. Zainicjuj projekt

omm login                                # logowanie kontem Orbito (rdzeń + repozytorium modułów)
omm namespace create acme                # namespace na Twoje moduły (raz)
omm init "Mój moduł" --dir moj-modul     # karta modułu w repozytorium + szkielet modułu
cd moj-modul

omm init zakłada kartę modułu w Twoim namespace (kod modułu nadaje repozytorium: <namespace>/<slug nazwy>; przy kilku namespace'ach wskaż jeden przez --namespace) i tworzy katalog z przykładowym modułem: module.json, package.json, index.js, pages/hello.yaml i .gitignore. Jeśli karta już istnieje, podaj jej kod: omm init "Mój moduł" --code acme/moj-modul. Szczegóły: Nowy moduł.

2. Zainstaluj bibliotekę Orbito

Szkielet z omm init ma już @orbito/api-lib w zależnościach – wystarczy:

npm install

W projekcie zakładanym ręcznie dodaj bibliotekę komendą npm install @orbito/api-lib.

3. Utwórz plik wejściowy

Każdy moduł Orbito musi posiadać plik index.js w katalogu głównym. To od niego platforma rozpoczyna wykonywanie modułu. omm init tworzy przykładowy index.js; minimalny wygląda tak:

// index.js
const { Log, Core } = require('@orbito/api-lib');

// Rejestracja metody dostępnej dla platformy i innych modułów
Core.registerMethod('hello', async (params, ctx) => {
  Log.info('Wywołano metodę hello', { params });

  return {
    message: 'Cześć z modułu!'
  };
});

Log.info('Moduł uruchomiony');

4. Przetestuj we własnej firmie

Zanim udostępnisz moduł firmom, opublikuj go jako wersję roboczą (draft) i zainstaluj w swojej firmie w Orbito – moduł działa wtedy w kontenerze tak samo jak po publikacji, ale widzą go tylko członkowie Twojego namespace'u i firmy, którym nadasz dostęp. Instalacja draftu w Twojej firmie nadaje jej ten dostęp automatycznie.

omm company list          # Twoje firmy (sesję rdzenia zapisało już omm login)
omm company use <id>      # firma, na której testujesz

omm publish               # wersja robocza + build obrazu Dockera
omm install               # instalacja wersji z module.json w firmie
omm logs                  # logi modułu (--container: stdout/stderr kontenera)
omm call hello            # wywołanie metody hello z kroku 3

Po poprawce w kodzie wystarczy omm publish (nadpisuje draft tej samej wersji) i omm update (przeładowuje instancję z nowym obrazem) – wersji nie trzeba podbijać. Metody, strony i hooki modułu sprawdzisz też w panelu firmy. Szczegóły: Testowanie na własnej firmie.

5. Opublikuj moduł

Moduł publikujesz jedną komendą CLI omm:

omm publish --release  # publikacja w rejestrze – wersja widoczna dla firm

Przed publikacją ustaw w module.json wersję wyższą niż ostatnio opublikowana.

Szczegóły znajdziesz w sekcji Wdrożenie.

Kolejne kroki

• Struktura modułu – jak zorganizować pliki w projekcie
• Zależności npm – jakich bibliotek możesz używać
• Kontekst firmy i instancji – jak platforma izoluje dane firm i kolejnych instalacji tego samego modułu
• API biblioteki – pełna dokumentacja modułów Core, Log, Pages, DB