Medusa.js: Was das Shopsystem im echten Betrieb kann

Medusa ist eine Commerce-Plattform auf Basis von Node.js und TypeScript, mit der Entwicklungsteams Onlineshops und andere Verkaufsanwendungen bauen. „Medusa.js“ ist der verbreitete Name aus der JavaScript-Welt, das Projekt selbst nennt sich schlicht Medusa. Du bekommst drei Dinge: fertige Commerce-Module für Produkte, Preise, Warenkorb, Bestellungen, Bestand und Zahlung, ein Framework für eigene API-Routen, Datenmodelle und Abläufe sowie einen Admin, in dem dein Team Produkte und Bestellungen bearbeitet.

Die Storefront, also der Shop, den deine Kunden sehen, ist eine eigene Anwendung. Medusa stellt dafür einen Starter auf Next.js bereit, du kannst aber jedes Frontend anbinden, das mit einer API sprechen kann. Nach der Installation hast du ein laufendes Backend und eine Ausgangsbasis, aber noch keinen Shop, der zu deinem Sortiment, deinen Preisen und deinen Abläufen passt. Diesen Teil baut dein Team oder deine Agentur.

Wir betreiben Medusa produktiv und schreiben diesen Artikel aus diesem Betrieb heraus. Deshalb geht es weniger um eine Funktionsliste als um drei Fragen: An welchen Stellen spart Medusa Arbeit, wo verursacht es Arbeit, und woran erkennst du vor der Entscheidung, auf welcher Seite dein Projekt landet?

Lizenz: Open Core

Der Kern von Medusa mit allen Commerce-Modulen steht unter der MIT-Lizenz und ist frei über npm verfügbar. Davon getrennt gibt es eine Enterprise Edition mit Rollen- und Rechteverwaltung. Für diese Bestandteile verlangt der Hersteller MedusaJS, Inc. einen kommerziellen Vertrag. Medusa selbst bezeichnet dieses Modell als Open Core. Für die meisten Shop-Projekte reicht der MIT-lizenzierte Kern, prüfe aber früh, ob du eine feingliedrige Rechteverwaltung für viele Admin-Nutzer brauchst.

Version: v2 ist eine Neuentwicklung

Die aktuelle Hauptversion ist Medusa v2, erschienen im Oktober 2024. Der Hersteller beschreibt sie als vollständige Neuentwicklung von Architektur und Funktionsumfang mit Änderungen, die nicht rückwärtskompatibel sind. Plugins aus v1 laufen unter v2 nicht. Wenn du Tutorials, Erweiterungen oder Referenzen einer Agentur prüfst, achte deshalb darauf, auf welche Version sie sich beziehen. Viele ältere Anleitungen im Netz beschreiben noch v1.

Berlin Blechdachhandel verkauft maßgefertigte Trapez- und Pfannenbleche, Sandwichpaneele und Kantteile aus eigener Produktion. Der alte Shop lief auf WordPress und WooCommerce, und an drei Stellen passte er nicht mehr zum Geschäft: Der Google-Shopping-Feed hing an einem Plugin, Gewerbepreise gab es nur auf Anfrage, weil B2B und B2C keine gemeinsame Preisliste hatten, und jede Dachbestellung wurde am Telefon aus Fläche, Profil, Kantteilen und Zubehör von Hand zusammengestellt.

Vor der Plattformwahl haben wir Shopify Plus geprüft. B2B-Preislisten und die Logik eines Dachkonfigurators hätten sich dort abbilden lassen, allerdings mit hohen laufenden Plattformkosten. Den Ausschlag für Medusa gab dann ein zweiter Punkt: Der Händler brauchte nicht nur einen Shop, sondern mehrere Anwendungen, die mit denselben Produkten, Preisen, Kunden und Beständen arbeiten.

Vier Anwendungen auf einer Datenbasis

Entstanden ist ein Backend auf Medusa v2 mit einer Storefront auf Next.js 15. Auf derselben Datenbasis laufen vier Anwendungen: der Shop, die Abholstation in Berlin-Pankow, die Tool-Time-App für das Team am Standort und das Rechnungsportal der Zentrale. Im Shop steckt ein 3D-Dachplaner. Er berechnet in fünf Schritten aus Dachmaßen, Profil und Farbe die komplette Stückliste aus dem echten Katalog, zeigt Dach und Kantteile in 2D und 3D und übergibt das Ergebnis in den Warenkorb oder als PDF-Angebot per Mail. Was wir im Einzelnen umgesetzt haben, beschreibt die Case Study zum Relaunch von Berlin Blechdachhandel.

Was an diesem Fall typisch für Medusa ist

Der Dachplaner ist das sichtbarste Stück des Projekts, aber er war nicht der Grund für Medusa. Ein Konfigurator lässt sich auch an andere Shopsysteme anschließen. Der Grund war, dass Gewerbepreise, Abholung, Lager am Standort und Rechnungsstellung keine Zusatzfunktionen eines Shops sind, sondern eigene Arbeitsabläufe des Händlers. In einem gehosteten System hätten sie als Apps und externe Werkzeuge um den Shop herum gelegen, jedes mit eigener Datenhaltung und eigenem Abgleich. Mit Medusa liegen sie in einem Backend, dessen Datenmodell wir selbst gestalten.

Das ist die Konstellation, in der Medusa seine Stärke ausspielt: Ein Unternehmen verkauft nicht nur online, sondern organisiert mehrere Kanäle und interne Abläufe um denselben Katalog. Wer einen Shop mit üblichem Checkout und Paketversand braucht, findet in diesem Projekt kein Argument für Medusa.

Medusa v2 teilt die Commerce-Funktionen in Module auf. Die offizielle Dokumentation führt über zwanzig Commerce-Module, darunter Produkt, Preis, Promotion, Warenkorb, Bestellung, Kunde, Bestand, Lagerort, Fulfillment, Zahlung, Steuer und Vertriebskanal. Jedes Modul verwaltet seine eigenen Daten. Wie die Module zusammenarbeiten, bestimmt den Alltag in einem Medusa-Projekt stärker als jede einzelne Funktion.

Module sind voneinander isoliert

Ein Modul kennt laut Dokumentation nur seine eigenen Services und Datenmodelle. Ein eigenes Modul kann also nicht in die Tabellen des Produktmoduls greifen oder dessen Klassen erweitern. Verbindungen entstehen über Module Links: Du legst ein eigenes Datenmodell an, etwa eine Kundennummer, und verknüpfst es mit dem Kunden aus dem Kundenmodul. Über Query fragst du anschließend Daten über die Modulgrenzen hinweg ab. In v1 wurden Entitäten und Services noch direkt erweitert, das ist in v2 nicht mehr vorgesehen. Für dein Team heißt das am Anfang mehr Konzeption, dafür bleibt nachvollziehbar, welche Daten zu welchem Modul gehören.

Workflows verbinden die Module

Wo mehrere Module zusammenarbeiten müssen, laufen die Schritte in Workflows. Ein Workflow ruft die Services der beteiligten Module nacheinander auf. Jeder Schritt kann eine Kompensationsfunktion haben, die seine Änderung zurücknimmt, wenn ein späterer Schritt scheitert. Medusa bildet auch die eigenen Kernabläufe so ab, und du kannst dich über Hooks in bestehende Workflows einklinken oder eigene schreiben. Ein Ablauf wie eine Abholung, der Bestellung, Bestand am Standort und Zeitfenster zusammenbringt, gehört deshalb in einen Workflow und nicht in einen einzelnen Service.

Hintergrundarbeit über Subscriber und Scheduled Jobs

Auf Ereignisse wie eine neue Bestellung reagieren Subscriber, wiederkehrende Aufgaben laufen als Scheduled Jobs nach einem Cron-Zeitplan. Die Dokumentation nennt als Beispiel einen täglichen Produktabgleich mit einem ERP. Bei Berlin Blechdachhandel gehören zu dieser Art Arbeit die Gewerbepreise, die stündlich aus der Preisliste der Zentrale übernommen werden, und die Pack-Mails, mit denen das Lager an der Abholstation von neuen Aufträgen erfährt.

Admin und Storefront

Der Medusa Admin wird vom Medusa-Server ausgeliefert. Du erweiterst ihn mit Widgets, die an festgelegten Stellen bestehender Seiten erscheinen, und mit eigenen Seiten, in der Dokumentation UI-Routen genannt. Die Storefront spricht über die Store-API mit dem Backend. Wie sich diese Trennung in eine Architektur aus austauschbaren Bausteinen einfügt, erklären wir im Ratgeber zum Aufbau eines Shops aus einzelnen Commerce-Bausteinen. Für Medusa reicht hier die Unterscheidung: Das Backend hält Daten und Regeln, alles Sichtbare liegt in der Storefront.

Medusa nimmt dir die Commerce-Grundlagen ab. Produkte mit Varianten, Preise, Warenkorb, Bestellungen, Bestand an mehreren Lagerorten und die Anbindung von Zahlungsanbietern sind vorhanden und über Admin und API nutzbar. Gewerbepreise lassen sich mit Preislisten abbilden, die nur für bestimmte Kundengruppen gelten. Für einen Händler mit Gewerbe- und Privatkunden ist das eine solide Grundlage und kein Sonderbau.

Alles, was diesen Händler von anderen unterscheidet, bringt Medusa nicht mit. Bei Berlin Blechdachhandel sind daraus 14 eigene Module entstanden, unter anderem für Produktinhalte, Angebote, Abholung, Kundennummern, ein Consent-Protokoll und den Chat. Dazu kommen das Rechnungsportal der Zentrale und die App für das Team am Standort als eigene Anwendungen.

Gewerbekunden: Preisliste aus dem Kern, Registrierung aus dem Projekt

Geschäftskunden registrieren sich per Kampagnencode und sehen danach Nettopreise für 73 Blech-Artikel. Die Preislogik selbst ist Medusa-Standard. Die Registrierung mit Code, die Zuordnung zur richtigen Kundengruppe und die eigene Kundennummer sind Projektarbeit. Prüfe bei deinem B2B-Fall genau, wo diese Grenze verläuft: Preislisten sind schnell eingerichtet, alles rund um die Identität des Geschäftskunden braucht Entwicklung.

Abholung: ein eigener Ablauf mit eigenem Bestand

Seit Juni 2026 holen Kunden Bleche und Zubehör in Pankow ab. Sie buchen einen Slot, bekommen einen Abholschein mit QR-Code und zahlen per Stripe oder bar vor Ort. Der Standort führt einen eigenen Bestand, das Lager bekommt Pack-Mails. Mehrere Lagerorte mit eigenem Bestand deckt Medusa über das Bestands- und das Lagerort-Modul ab. Zeitfenster, Abholschein, Barzahlung vor Ort und die Monatsabrechnung des Standorts gehören nicht zum Kern.

Rechnungen: wo Commerce aufhört

Die Zentrale erstellt Rechnungen in einem eigenen Portal: Lieferschein hochladen, Positionen zuordnen, festschreiben, versenden. Die Rechnungen enthalten ZUGFeRD-Daten, und vor dem Festschreiben gilt das Vier-Augen-Prinzip. Das ist kein Shop-Feature mehr, sondern Arbeit nah an der Buchhaltung. Für Medusa spricht, dass so ein Portal auf denselben Bestellungen und Kunden aufsetzen kann wie der Shop. Gleichzeitig ist es eigene Software mit eigener fachlicher Abnahme. Plane eine solche Anwendung als eigenes Teilprojekt, nicht als Erweiterung des Shops.

Querschnittsthemen werden zu deiner Aufgabe

Ein Protokoll, welche Einwilligung ein Besucher wann gegeben hat, installierst du bei einem gehosteten Shopsystem häufig als App. Bei Medusa ist es ein Modul, das jemand baut, testet und bei Updates mitzieht. Das gilt genauso für den Chat und für Produktinhalte, die über Name, Preis und Varianten hinausgehen. Keine dieser Aufgaben ist für sich schwierig. In der Summe machen sie aber den Unterschied zwischen einer Medusa-Demo und einem Shop, mit dem ein Händler täglich arbeitet.

Weil die Storefront eine eigene Anwendung ist, gehört alles, was Google und deine Kunden sehen, in dein Projekt: URLs, Metadaten, strukturierte Daten, Ladezeit und Weiterleitungen. Medusa liefert die Daten über die API. Wie die Seiten für Suchmaschinen aussehen, entscheidet die Storefront. Bei einem Umzug von WooCommerce ist das die Stelle mit dem größten Risiko für bestehende Rankings.

391 Alt-URLs, null harte 404

Beim Relaunch Ende April 2026 haben wir 391 Alt-URLs per Redirect auf die neuen Adressen übernommen, der Link-Audit meldet keine harten 404. Die Arbeit dafür liegt vor dem Umschalten: alle alten Adressen von Produkten, Kategorien und Inhalten erfassen, jeder ein inhaltlich passendes Ziel zuordnen und die Weiterleitungen dort hinterlegen, wo die Anfragen ankommen. Bei einer Next.js-Storefront ist das das Frontend, nicht das Medusa-Backend. Nach dem Livegang wird erneut gecrawlt, bis keine Adresse mehr ins Leere läuft.

Inhalte ziehen mit um

Mit dem Relaunch sind 83 Ratgeberartikel live gegangen. Für einen Händler, dessen Kunden vor einer Dachbestellung viel wissen wollen, gehören Inhalte zum Shop. In einem System mit getrennter Storefront musst du entscheiden, wo diese Inhalte gepflegt werden, wie sie in die Storefront kommen und wer sie ohne Entwickler veröffentlichen kann. Kläre das vor dem Umzug, sonst landen Texte als Code im Frontend und jede Korrektur wird zu einem Deployment.

Der Produktfeed kommt aus dem Shop

Der Google-Shopping-Feed hing vorher an einem WooCommerce-Plugin. Heute erzeugt der Shop einen eigenen Merchant-Feed direkt aus dem Katalog, und darauf laufen die Performance-Max-Kampagnen. Damit kommen Preis, Verfügbarkeit und Produktdaten im Feed aus derselben Quelle wie im Shop. Unter den Commerce-Modulen von Medusa ist kein Produktfeed für Google. Du baust ihn selbst oder nutzt eine Erweiterung, die zu deiner Medusa-Version passt.

Ladezeit ist Frontend-Arbeit

Eine Storefront auf Next.js ist nicht automatisch schnell. Bildformate, Caching und die Zahl der API-Abfragen pro Seite entscheiden über die Ladezeit. Ein aufwendiges Element wie ein 3D-Planer gehört so eingebunden, dass es nur dort geladen wird, wo es gebraucht wird, und die übrigen Produktseiten nicht ausbremst.

Ein Medusa-Shop ist eine Node.js-Anwendung mit Datenbank, und so musst du ihn auch betreiben. Medusa v2 setzt laut Installationsanleitung eine LTS-Version von Node.js voraus, derzeit 22.22 oder neuer, und eine laufende PostgreSQL-Datenbank. Für den Next.js-Starter nennt die Dokumentation zusätzlich eine Obergrenze für die Node-Version. Diese Angaben ändern sich mit neuen Versionen, prüfe sie deshalb vor jedem größeren Update in der Dokumentation.

Zwei Instanzen statt einer

Für die Produktion empfiehlt Medusa, dieselbe Anwendung zweimal zu starten: einmal im Server-Modus für API-Anfragen und den Admin, einmal im Worker-Modus für Hintergrundaufgaben wie Scheduled Jobs und Subscriber. So bremst ein langer Abgleich keine Kundenanfragen aus. Der Server speichert seine Sessions in Redis. Außerdem empfiehlt die Dokumentation für die Produktion die Redis-Varianten von Cache, Event-Bus, Workflow-Engine und Locking statt der Standards für die Entwicklung. Zu einem produktiven Medusa-Shop gehören also mindestens Server, Worker, PostgreSQL, Redis und die Storefront.

Medusa Cloud oder selbst betreiben

Medusa bietet mit Medusa Cloud einen gemanagten Betrieb mit automatischer Skalierung an und empfiehlt ihn selbst als bevorzugten Weg. Alternativ betreibst du Server, Worker, Datenbank und Redis bei einem Hoster deiner Wahl. Entscheidend ist weniger der Ort als die Zuständigkeit. Lege fest, wer es bemerkt und wer reagiert, wenn der Worker steht und Hintergrundaufgaben liegen bleiben, während der Shop nach außen normal aussieht.

Updates gehören zum Betrieb

Seit dem Start von v2 im Oktober 2024 erscheinen in kurzen Abständen neue Minor-Versionen. Plane Updates deshalb als festen Teil des Betriebs ein: in einer Testumgebung mit den eigenen Modulen prüfen, die Abläufe testen, die nur dein Shop hat, dann ausrollen. Je mehr eigene Module, desto wichtiger sind diese Tests. Wer einen Stand einfriert, vergrößert den Abstand zur aktuellen Version, und jedes spätere Update wird schwerer.

Wer das System trägt

Bei einem gehosteten Shop ist der Plattformanbieter für den Betrieb der Plattform zuständig. Bei Medusa sind es du, dein Hoster und dein Entwicklungsteam. Kläre vor dem Launch, wer Fehler annimmt, wer Zugriff auf Server und Datenbank hat und wo dokumentiert ist, welches eigene Modul welche Aufgabe übernimmt. Bei Berlin Blechdachhandel war der Relaunch deshalb kein Projektende, die Plattform wird laufend weiterentwickelt.

Nach Relaunch und mehreren Monaten Weiterentwicklung haben wir ein klares Bild davon, welche Entscheidungen im Projekt Berlin Blechdachhandel getragen haben. Die folgenden Punkte sind unsere Einschätzung aus diesem Projekt, keine allgemeine Regel für jedes Medusa-Vorhaben.

Eine Datenbasis für alle Anwendungen

Shop, Abholstation, Standort-App und Rechnungsportal arbeiten mit denselben Produkten, Preisen und Kunden. Das würden wir wieder so bauen. Jede weitere Anwendung mit eigener Kopie der Daten wäre ein zusätzlicher Abgleich, der irgendwann nicht mehr stimmt. Genau solche Brüche zwischen Plugin-Feed, Preisanfrage und Telefonkalkulation sollte der Relaunch beseitigen.

Eine führende Quelle für Preise

Die Gewerbepreise werden in der Preisliste der Zentrale gepflegt und stündlich übernommen, nicht im Shop. Damit ist klar, wo eine Preisänderung beginnt. Lege diese Hoheit für Preise, Bestand und Kundendaten fest, bevor die erste Schnittstelle entsteht. Später lässt sie sich nur mit viel Aufwand ändern.

Schrittweise live gehen

Der Shop ging Ende April 2026 live, die Abholstation kam im Juni dazu. Diese Reihenfolge würden wir wieder wählen: Erst läuft der Kern mit Katalog, Preisen und Bestellungen, dann kommt ein Ablauf mit eigenem Bestand, Zahlung vor Ort und eigener App für das Team hinzu. Jede Stufe wird unter echten Bedingungen stabil, bevor die nächste startet.

Kontrollen dort, wo Fehler nicht mehr zurückgehen

Rechnungen werden erst nach dem Vier-Augen-Prinzip festgeschrieben. In einem eigenen System entscheidest du selbst, wo solche Kontrollen sitzen. Setze sie an die Stellen, an denen sich ein Fehler nicht mehr mit einem Klick korrigieren lässt, und nicht flächendeckend an jeden Schritt.

Was du vor der Entscheidung prüfen solltest

• Welche Abläufe unterscheiden dein Geschäft vom Standard-Shop? Findest du keinen, brauchst du Medusa nicht.
• Gibt es mehrere Anwendungen oder Kanäle, die dieselben Daten brauchen?
• Hat dein Team oder deine Agentur Erfahrung mit TypeScript, Node.js und PostgreSQL im Produktivbetrieb?
• Wer betreibt Server, Worker und Redis, und wer spielt Updates ein?
• Gibt es deine Zahlungs-, Versand- und Feed-Anbindungen bereits für Medusa v2, oder baust du sie selbst?
• Reicht der Medusa Admin für alle Mitarbeitenden, oder braucht ein Team wie das an unserer Abholstation eine eigene Oberfläche?

Dieselben Fragen stehen bei uns am Anfang, wenn wir Onlineshops mit eigener Geschäftslogik konzipieren und entwickeln: zuerst der schwierigste Ablauf deines Geschäfts, dann die Plattform. Wer diesen Ablauf nicht beschreiben kann, entscheidet die Plattformfrage zu früh.

Medusa ist die falsche Wahl, wenn dein Verkauf im Wesentlichen aus Katalog, Warenkorb, Checkout und Paketversand besteht. Dann baust du mit Entwicklungsaufwand nach, was ein gehostetes System sofort mitbringt, und übernimmst zusätzlich den Betrieb.

Wenn der Shop nebenbei läuft

Ein kleines Team, das Produkte pflegt, Kampagnen steuert und Kunden betreut, hat selten Kapazität für Releases, Server und eigene Module. Ein System mit App-Store und Themes lässt so ein Team selbstständiger arbeiten, weil es neue Funktionen installieren kann, ohne einen Entwickler zu beauftragen.

Wenn nur das Design individuell sein soll

Für eine eigene Optik brauchst du kein eigenes Backend. Ein individuelles Theme oder ein eigenes Frontend auf einer SaaS-Plattform reicht dafür meist aus. Medusa lohnt sich erst, wenn die Logik hinter dem Shop abweicht: Preise, Abläufe, Kanäle oder die Verbindung zu internen Anwendungen.

Wenn die Planung beim Launch endet

Eigene Module brauchen Pflege, Medusa braucht Updates, Server brauchen Überwachung. Wer nur das erste Release plant und finanziert, hat nach einem Jahr ein System, an das sich niemand mehr herantraut. Rechne den Betrieb über mehrere Jahre in die Entscheidung ein, nicht nur den Aufbau.

Medusa oder Shopify

Shopify übernimmt Hosting, Updates, Checkout und die Sicherheit der Plattform und bietet ein großes App-Ökosystem. Dafür arbeitest du in den Grenzen, die Shopify für Datenmodell, Checkout und Erweiterungen setzt. Medusa gibt dir die Kontrolle über Datenmodell und Abläufe und verlangt dafür eigene Entwicklung und eigenen Betrieb. Bei Berlin Blechdachhandel haben B2B-Preislisten, Konfigurator und mehrere Anwendungen auf einer Datenbasis für Medusa gesprochen. Einem Händler mit einem Kanal, Standardversand und ohne Gewerbelogik würden wir in der Regel zu Shopify raten. Ab wann bei Shopify die Plus-Stufe nötig wird, klären wir im Ratgeber zur Frage, für welche Unternehmen sich Shopify Plus lohnt.