Czym jest Medusa.js v2 i jak zbudowana jest jej architektura?

Źródła sprawdzone 11 listopada 2026, na dokumentacji Medusy v2; najnowsze wydanie w tym dniu to v2.22.6.

Ten poradnik jest dla CTO, architekta albo product ownera, który słyszy o Medusie po raz pierwszy albo ocenia ją jako fundament nowego sklepu. Wyjaśnia, z czego składa się aplikacja Medusa v2, gdzie dopisuje się własną logikę i co trzeba wdrożyć obok niej.

Odpowiedź w skrócie: Medusa v2 to serwer Node.js z panelem administracyjnym, zbudowany z niezależnych modułów domenowych. Logikę biznesową, która dotyka kilku modułów albo systemów zewnętrznych, zapisuje się w workflowach, które potrafią wycofać wykonane kroki po błędzie. Sklep internetowy jest osobną aplikacją i łączy się z Medusą przez API.

Według opisu architektury Medusy żądanie ze sklepu albo panelu trafia najpierw do trasy API. Serwer działa na Express.js. Trasa uruchamia workflow, workflow korzysta z modułów, a moduły czytają i zapisują dane w bazie.

Medusa obsługuje wyłącznie PostgreSQL jako główną bazę danych. Inną bazę można podłączyć tylko we własnym module. Tabela pokazuje, gdzie w każdej warstwie dopisuje się własny kod.

Moduł to pakiet funkcji jednej domeny: modele danych (tabele) i serwis, który nimi zarządza. Po instalacji dostępne są moduły z listy modułów commerce, między innymi koszyk, zamówienie, produkt, cennik, promocje, magazyn, płatności, podatki, klient i użytkownik. Wyjątkami są moduł lojalnościowy, instalowany jako wtyczka, i moduł RBAC z Enterprise Edition. Funkcje modułów są wystawione przez gotowe trasy API.

Drugą grupę tworzą moduły infrastruktury. Odpowiadają za usługi techniczne, a dostawcę każdej z tych usług można wymienić:

• Event Module: publikowanie zdarzeń i subskrypcje (pub/sub).
• Workflow Engine Module: orkiestracja workflowów.
• Caching Module: pamięć podręczna dla danych kosztownych w obliczeniu.
• Locking Module: blokady przy dostępie kilku procesów do tych samych zasobów.
• File Module: przechowywanie plików, na przykład zdjęć produktów.
• Notification Module: wysyłka powiadomień do klientów i użytkowników.
• Analytics Module: przekazywanie zdarzeń do zewnętrznego narzędzia analitycznego.

Uwaga na nazwy: moduł lojalnościowy z listy modułów commerce wymaga instalacji wtyczki Loyalty Plugin (Medusa v2.14.0+) i według dokumentacji obsługuje karty podarunkowe. Nazwa modułu nie mówi jeszcze, czy pokrywa on Twój proces; trzeba sprawdzić opis jego funkcji.

Zasada izolacji modułów oznacza, że moduł nie widzi serwisów ani modeli danych innych modułów. Twój moduł nie może na przykład wywołać serwisu modułu produktu ani zdefiniować bezpośredniej relacji do jego tabel.

Dane z różnych modułów łączy się przez powiązania modułów (module links). Medusa tworzy dla każdego powiązania osobną tabelę, która przechowuje tylko identyfikatory połączonych rekordów, bez klucza obcego. Dane z kilku modułów pobiera się narzędziem Query.

Dla architekta wynika z tego prosta reguła: własne pojęcie biznesowe, na przykład markę albo umowę handlową, zapisujesz we własnym module i łączysz z produktem lub klientem powiązaniem. Nie zmieniasz tabel modułów rdzenia; według dokumentacji izolacja pozwala dołączyć własny moduł do aplikacji bez skutków ubocznych dla jej reszty.

Według dokumentacji workflowów workflow to seria kroków, która realizuje zadanie. W odróżnieniu od zwykłej funkcji Medusa śledzi przebieg każdego kroku, pozwala zdefiniować logikę wycofania i wykonywać długie działania asynchronicznie. Workflow uruchamia się z trasy API, subskrybenta zdarzenia albo zadania cyklicznego.

Wycofanie opisuje funkcja kompensacyjna kroku: jeśli krok utworzył rekord, a późniejszy krok zakończył się błędem, kompensacja usuwa ten rekord. Dzięki temu dane w Medusie i w systemach zewnętrznych nie zostają w stanie pośrednim.

Przykład hipotetyczny, a nie opis projektu klienta: hurtownia chce, żeby zamówienie ze sklepu trafiało do ERP. Workflow mógłby wyglądać tak:

1. Pobierz zamówienie z pozycjami i danymi klienta narzędziem Query.
2. Przemapuj dane na format ERP: kody towarów, jednostki, numer kontrahenta.
3. Utwórz dokument w ERP przez moduł integracji; kompensacja anuluje dokument, jeśli kolejny krok się nie uda.
4. Zapisz numer dokumentu ERP we własnym module i połącz go z zamówieniem powiązaniem modułów.
5. Zgłoś błąd osobie odpowiedzialnej, jeśli workflow się nie powiódł. To nie jest kolejny krok workflowu: po błędzie Medusa uruchamia kompensacje, a nie dalsze kroki, więc zgłoszenie obsługuje kod, który uruchomił workflow (subskrybent, trasa API albo zadanie cykliczne).

Medusa emituje zdarzenia przy operacjach rdzenia, na przykład order.placed po złożeniu zamówienia. Opis zdarzeń i subskrybentów pokazuje, jak obsłużyć je funkcją asynchroniczną w tym samym kodzie, bez osobnej aplikacji do webhooków.

Subskrybent działa poza głównym przepływem, więc nadaje się do działań pobocznych, takich jak e-mail z potwierdzeniem. Jeśli działanie jest niezbędne dla samego przepływu, dokumentacja kieruje do haków workflowu (workflow hooks).

Zadania cykliczne uruchamiają funkcję według wyrażenia cron, gdy aplikacja działa, na przykład do synchronizacji produktów z ERP. Działania, które mają ruszać przy wyłączonej aplikacji, dokumentacja zaleca jako własne skrypty CLI wywoływane przez harmonogram systemu.

Zdarzenia obsługuje Event Module. Domyślna wersja lokalna służy do developmentu; do produkcji dokumentacja wskazuje moduł oparty na Redis.

Panel Medusa Admin instaluje się razem z aplikacją. Według opisu panelu admina można dodawać do niego widżety na istniejących stronach i nowe strony, ale nie można zmienić układu, wyglądu ani treści istniejących stron. Przy dużych zmianach dokumentacja wskazuje budowę własnego panelu na Admin API.

Sklep internetowy jest osobną aplikacją. Punktem startu może być Next.js Starter Storefront, który od wersji v2.14.0 przy instalacji przez create-medusa-app trafia do jednego repozytorium (monorepo) z aplikacją Medusa. Możesz też zbudować własny frontend w dowolnej technologii.

Opis wdrożenia rozdziela aplikację Medusa (serwer i panel) i co najmniej jeden sklep, które wdraża się osobno; serwer łączy się z PostgreSQL i Redis. Na produkcji dokumentacja zaleca dwie instancje tej samej aplikacji: serwer do obsługi żądań i worker do zadań w tle, a hosting musi zapewniać co najmniej 2 GB RAM. Alternatywą jest zarządzany hosting Medusa Cloud.

Najpierw licencja: według pliku licencji w repozytorium Medusa jest dostępna na licencji MIT, z wyjątkiem materiałów Enterprise Edition, które wymagają osobnej umowy handlowej. Brak opłaty licencyjnej za rdzeń nie oznacza braku kosztów: płacisz za hosting, development i utrzymanie.

Decyzja zależy od tego, ile Twojego procesu wykracza poza standard sklepu i kto będzie utrzymywał kod. Tabela pokazuje warunki, a nie gotowy werdykt.

Jeśli sprzedajesz firmom i potrzebujesz cen kontraktowych, limitów kredytowych i podziału odpowiedzialności z ERP, rozwinięcie tego tematu znajdziesz w poradniku o Medusie dla sprzedaży firmowej.

Kolejność poniżej zmniejsza ryzyko, że architektura powstanie przed zrozumieniem procesu. Każdy krok kończy się dokumentem albo działającym fragmentem, który można sprawdzić.

Szacunek czasu i budżetu ma sens dopiero po krokach 1 i 2, bo zależy od liczby własnych modułów i integracji, a nie od samej Medusy.

1. Opisz proces sprzedaży: kto kupuje, jak powstaje cena, co dzieje się po zamówieniu, jakie są wyjątki.
2. Przypisz proces do modułów: co pokrywają moduły commerce, co wymaga własnego modułu, a co zostaje w ERP.
3. Zaprojektuj integracje jako workflowy: kroki, kompensacje i to, kto dostaje informację o błędzie.
4. Zbuduj najkrótszą ścieżkę zakupu od katalogu do zamówienia w ERP i sprawdź ją na danych testowych.
5. Przygotuj produkcję: osobny serwer i worker, Redis dla zdarzeń, kopie zapasowe bazy i monitoring.
6. Zaplanuj aktualizacje: kto i jak często sprawdza nowe wydania Medusy i testuje własne moduły po aktualizacji.