Medusa.js
Otwarty silnik e-commerce dla sklepów, których reguły nie mieszczą się w gotowej platformie.
E-commerceUżywam od 2025 · Wyróżniony projekt: CAS Marketplace (w zespole Code & Pepper)
- Kategoria
- E-commerce
- Używam od
- 2025
- Wyróżniony projekt
- CAS Marketplacew zespole Code & Pepper
W praktyce
Po Medusę sięgam wtedy, gdy sklep ma logikę, której gotowa platforma nie udźwignie bez obejść: wielu sprzedawców, cenniki B2B albo własny koszyk. W CAS Marketplace była silnikiem całego marketplace'u, a sam storefront powstał osobno, w Next.js.
Czym jest Medusa.js?
Medusa.js to otwartoźródłowy silnik e-commerce napisany w Node.js i TypeScripcie. Działa w modelu headless: dostarcza API do produktów, koszyka, zamówień, płatności i magazynu, a warstwę, którą widzi klient, buduje się osobno, najczęściej w Next.js.
Od wersji 2 całość składa się z modułów. Każdy obszar, od cenników po realizację zamówień, to osobny moduł z własnym modelem danych w PostgreSQL. Można go rozszerzyć albo zastąpić własnym, bez forkowania rdzenia.
- Licencja
- MIT
- Język
- TypeScript, Node.js
- Baza danych
- PostgreSQL
- Model
- Headless, modułowy
Jak pracuję z Medusa.js
Zaczynam od modelu danych, nie od wyglądu sklepu. Kolejność ma znaczenie, bo każdą z tych decyzji najtaniej podjąć przed startem sprzedaży.
Model danych
Ustalam, co jest standardowym modułem Medusy, co wymaga własnego, a co załatwi link między modułami.
Workflowy
Logikę biznesową zamykam w workflowach z krokami kompensującymi, żeby nieudana płatność w Stripe nie zostawiała zamówienia w połowie drogi.
Storefront i treści
Sklep buduję w Next.js. Treści marketingowe trzymam poza silnikiem, zwykle w Payload CMS, i łączę oba źródła po stronie serwera.
Kiedy tak, a kiedy nie
Medusa opłaca się wtedy, gdy płacisz za elastyczność, z której naprawdę skorzystasz.
Sprawdza się, gdy
- Marketplace z wieloma sprzedawcami i podziałem płatności.
- B2B z cennikami dla konkretnych klientów i zamówieniami na fakturę.
- Sklep, który ma być częścią większego produktu, a nie osobną wyspą.
- Zespół, który chce mieć kod i dane u siebie.
Nie sprawdza się, gdy
- Prosty sklep z kilkudziesięcioma produktami i standardową dostawą.
- Nikt po Twojej stronie nie zajmie się utrzymaniem po wdrożeniu.
- Start za dwa tygodnie przy małym budżecie.
W tych przypadkach szybciej i taniej wyjdzie Shopify.
Medusa czy Shopify?
Obie platformy sprzedają dobrze. Różnią się tym, kto odpowiada za kod i ile wolno w nim zmienić.
| Kryterium | Medusa.js | Shopify |
|---|---|---|
| Czas do startu | Dłuższy, zależy od zakresu wdrożenia | Krótki, sklep rusza po konfiguracji |
| Koszty stałe | Hosting i baza danych, bez prowizji platformy | Abonament, przy zewnętrznej bramce także prowizja |
| Własna logika | Własne moduły i workflowy w kodzie | Aplikacje i funkcje w granicach platformy |
| Checkout | W całości własny | Konfigurowalny, głębsze zmiany w Shopify Plus |
| Wielu sprzedawców | Mercur na Medusie | Zewnętrzne aplikacje marketplace |
| Utrzymanie | Po Twojej stronie albo u wykonawcy | Po stronie Shopify |
| Kod i dane | U Ciebie, na licencji MIT | Na platformie, dostęp przez API |
Wybierz Medusę, gdy
reguły sklepu są Twoją przewagą: nietypowe cenniki, wielu sprzedawców, własny proces zamówienia. Zapłacisz więcej na starcie, ale nie będziesz obchodzić ograniczeń wtyczkami.
Wybierz Shopify, gdy
chcesz sprzedawać szybko, a proces zakupowy jest typowy. Jeśli platforma zacznie uwierać, późniejsza migracja będzie tańsza niż przedwczesna budowa własnego silnika.
W CAS Marketplace wybrałem Mercur na Medusie, bo projekt wymagał wielu sprzedawców z prowizjami i podziałem zamówień.
Pułapki z praktyki
Reguły dostawy są sprawdzane dwa razy
Z projektu CAS Marketplace
Medusa v2 ocenia reguły opcji dostawy w dwóch osobnych workflow: raz przy wyświetlaniu listy opcji i drugi raz, gdy klient jakąś wybiera. Własny kontekst reguły, na przykład wartość koszyka dla darmowej dostawy, trzeba przekazać do obu, inaczej opcja widnieje w checkoucie, a przy wyborze kończy się ogólnym błędem 400. Progi zapisuję jako wartości z częścią dziesiętną, np. 60.00, bo samo 60 porównywarka najpierw próbuje odczytać jako datę.
Obejście żyje dłużej niż błąd
Z projektu CAS Marketplace
Subskrybent dodany jako obejście błędu, na przykład przy przechwytywaniu płatności, potrafi działać dalej po tym, jak Medusa naprawi problem u siebie, i wtedy dubluje zdarzenia order.placed, a z nimi maile z potwierdzeniem zamówienia. Dlatego każde obejście dostaje link do zgłoszenia, warunek na wersję albo flagę i przegląd przy każdej aktualizacji. Wersje minor w v2 potrafią wprowadzać zmiany łamiące zgodność, więc przypinam wersje i czytam changelog przed podbiciem.
Tryb deweloperski to nie produkcja
Z projektu CAS Marketplace
Lokalnie Medusa v2 używa szyny zdarzeń, silnika workflow i cache trzymanych w pamięci procesu, więc zdarzenia asynchroniczne i cache przy wielu instancjach zachowują się inaczej niż na produkcji. Dlatego takie ścieżki sprawdzam lokalnie na Redisie, zanim trafią na serwer. Po dodaniu linków między modułami uruchamiam migracje i synchronizację linków, bo bez tego linki po cichu nie działają.
Często zadawane pytania
Rozważasz Medusę do swojego sklepu?
Napisz, co sprzedajesz i jak ma działać sprzedaż. Powiem wprost, czy Medusa ma tu sens, czy szybciej dojdziesz do celu na Shopify.