MedusaJS

MedusaJS ist ein quelloffenes, modulares Commerce-Backend auf Basis von Node.js und TypeScript. Es liefert die Geschäftslogik eines Onlineshops — Produkte, Warenkorb, Bestellungen, Preise, Zahlungen, Lager — als austauschbare Module mit REST- und GraphQL-Schnittstellen, überlässt das Frontend aber bewusst dir.

Was MedusaJS ist — und was es nicht ist

Medusa startete 2020 als Open-Source-Alternative zu geschlossenen Commerce-Plattformen und wurde mit Version 2.0 im Oktober 2024 vollständig neu aufgesetzt. Der Kern liegt unter der MIT-Lizenz auf GitHub, die technische Referenz steht in den offiziellen Docs.

Zwei Abgrenzungen helfen bei der Einordnung, weil sie die häufigsten Fehlerwartungen betreffen.

Medusa ist kein Shopsystem im klassischen Sinn. Es ist ein Commerce-Backend. Was die meisten unter „Shop“ verstehen — Startseite, Produktdetailseite, Checkout-Oberfläche — liefert Medusa nicht fertig aus. Stattdessen gibt es einen offiziellen Next.js-Starter, Community-Starter für weitere Frameworks und eine API-Schicht, an die du dein eigenes Frontend andockst. Wer einen sofort verkaufsfähigen Shop erwartet, bekommt ein Framework statt einer Plattform.

Medusa ist aber auch kein reines Headless-Produkt. Es bringt ein vollständiges Admin-Panel in React mit: Bestellverwaltung, Produktpflege, Promotions, Kundenkonten, Multi-Warehouse. Der Unterschied zu klassischen Suiten liegt nicht im Fehlen einer Oberfläche, sondern darin, welche Oberfläche fehlt — die für Endkundinnen und Endkunden.

In der Praxis konkurriert Medusa deshalb selten mit Baukastenlösungen, sondern mit API-first-Plattformen und maßgeschneiderten Composable-Stacks. Die Vergleichsklasse ist enterprise-orientiert, der Einstiegspunkt Open Source.

Die Architektur

Commerce-Module ohne harte Datenbankkopplung

Medusa zerlegt jede Geschäftsdomäne in ein eigenständiges Modul: Produkte, Carts, Orders, Payments, Pricing, Inventory, Promotions, Customers und weitere. Im Core sind rund zwanzig solcher Commerce-Module enthalten.

Die architektonisch entscheidende Eigenschaft: Zwischen diesen Modulen existieren keine Foreign-Key-Beziehungen auf Datenbankebene. Verknüpfungen werden über sogenannte Module Links abgebildet und zur Laufzeit aufgelöst. Was nach Theorie klingt, hat handfeste Folgen.

In einer klassischen Suite hängt der Kunde hart an der Bestellung, beide leben in derselben Datenbank mit Constraints. Wer die Kundendaten in ein CRM auslagern will, operiert am offenen Herzen. In Medusa lässt sich das Customer-Modul durch eine externe Anbindung ersetzen, ohne die Order-Tabellen anzufassen. Daraus ergeben sich zwei praktische Muster:

• Selektive Adoption. Ein Hersteller mit etabliertem PIM übernimmt nur das Order- und Pricing-Modul und lässt Produktdaten weiterhin aus dem bestehenden System fließen. Eine große Datenmigration ist keine Voraussetzung für den Start.
• Modul-Ersetzung. Reicht das mitgelieferte Preismodul nicht aus — etwa weil ein Staffelpreismodell mit vertragsindividuellen Konditionen gebraucht wird —, tauschst du es gegen eine eigene Implementierung, ohne den Rest des Systems zu berühren.

Für gewachsene Mittelstands-Stacks mit ERP, PIM und eigenem Auftragsmanagement ist das die relevanteste Eigenschaft des Frameworks überhaupt. Klassische Suiten verlangen häufig, dass du dich ganz auf ihr Datenmodell einlässt — oder gar nicht.

Die Workflow-Engine

Mehrstufige Geschäftsprozesse laufen in Medusa nicht als lose Kette von Event-Handlern, sondern über eine eingebaute Workflow-Engine. Ein Workflow besteht aus benannten Schritten; jeder Schritt kann eine Kompensationslogik mitbringen, die bei einem Fehler die bereits ausgeführten Schritte zurücknimmt. Dazu kommen konfigurierbare Wiederholungen bei transienten Fehlern und Idempotenz-Garantien, damit derselbe Workflow bei Mehrfach-Trigger nicht doppelt läuft.

Der Effekt ist im Betrieb spürbar: Ein fehlgeschlagener Zahlungs-Callback hinterlässt keinen halb reservierten Bestand, und ein zweimal ausgelöstes Webhook-Event erzeugt keine Doppelbestellung. Genau diese Klasse von Fehlern kostet in selbstgebauten Integrationen erfahrungsgemäß die meiste Zeit.

Storefront, Admin und Hosting strikt getrennt

Die drei Ebenen sind bewusst entkoppelt:

Diese Trennung ist kein Selbstzweck. Sie sorgt dafür, dass ein Frontend-Team in seinem Tempo arbeiten kann, ohne bei jedem Deployment das Commerce-Backend mitzuziehen — und umgekehrt.

Wofür sich MedusaJS eignet

Das Framework spielt seine Stärken dort aus, wo Standardprozesse nicht reichen:

• Individuelle Commerce-Logik. Konfiguratoren, Abo- und Verbrauchsmodelle, mehrstufige Freigaben im B2B-Bestellprozess — alles, was in einer Suite nur über Plugin-Stapel oder Core-Eingriffe geht.
• Bestehende Systemlandschaft. Wenn ERP, PIM oder OMS führend bleiben sollen und der Shop sich einfügen muss statt umgekehrt.
• Eigene Entwicklungsmannschaft. Ein Team, das TypeScript und Node.js ohnehin beherrscht, arbeitet ohne Technologiebruch.
• Mehrere Kanäle auf einer Basis. Web-Shop, App und Marktplatz-Anbindung teilen sich dieselbe Geschäftslogik über die API-Schicht.

Wofür es eher nicht passt

Ehrlichkeit an dieser Stelle spart teure Umwege:

• Schneller Standard-Shop. Wer ein überschaubares Sortiment möglichst zügig online bringen will, ist mit einer fertigen Plattform schneller und günstiger.
• Kein Entwicklungsteam. Ohne eigene oder fest eingekaufte Entwicklungskapazität wird ein Framework zur Dauerabhängigkeit.
• Erwartung eines Plugin-Ökosystems. Die Zahl fertiger Erweiterungen liegt deutlich unter der etablierter Shopsysteme. Vieles, was dort ein Marktplatz-Modul ist, ist hier Eigenentwicklung.
• Deutsche Spezialanforderungen von der Stange. Rechnungsformate, Zahlarten und branchenspezifische Compliance sind machbar, aber selten fertig verfügbar.

Lizenzmodell: MIT-Kern mit Open-Core-Rand

Medusa als „einfach MIT, also frei“ abzuspeichern, greift seit 2026 zu kurz. Das Projekt ist auf ein Open-Core-Modell umgestellt: Der Kern bleibt MIT-lizenziert, einzelne Bausteine sind laut der Enterprise-Lizenzdatei im Repository jedoch ausgenommen und brauchen einen kommerziellen Vertrag.

Betroffen sind unter anderem zwei Funktionen, die im B2B-Umfeld regelmäßig gebraucht werden: feingranulare Rollen und Rechte im Admin sowie die Anbindung an ein Firmen-Identity-Management über einen OIDC-Auth-Provider. Generische Authentifizierung und die normale Nutzer- und Einladungsverwaltung bleiben ausdrücklich MIT.

Für eine Kalkulation heißt das: Steht im Lastenheft, dass die Buchhaltung keine Preise ändern darf und dass sich das Team per Firmen-Login anmeldet, landest du in der kommerziellen Edition — auch wenn der Kern kostenlos bleibt. Zur Fairness gehört die Entwarnung, dass die Änderung nur nach vorn wirkt und keine Rechte an bereits veröffentlichten Versionen entzieht.

Strategisch ist das der übliche Weg erfolgreicher Open-Source-Firmen und kein Alarmsignal. Wer aber auf fünf Jahre plant, sollte die Frage in die Bewertung aufnehmen, welche Funktionen in dieser Zeit aus dem freien Kern in die kommerzielle Edition wandern könnten.

Ein realistischer Einstieg

Der bewährte Weg ist nicht der Big Bang, sondern ein abgestufter Zuschnitt: zuerst ein Proof of Concept, der die kritischste Integration gegen das führende Zielsystem prüft — typischerweise ERP oder PIM. Dann ein MVP mit dem tatsächlich nötigen Funktionsumfang. Erst danach die Ausbaustufen wie B2B-Komponenten oder weitere Verkaufskanäle.

Die häufigste Fehleinschätzung besteht darin, den Proof of Concept zu überspringen und direkt mit dem MVP zu starten. Wer das tut, baut Architekturentscheidungen ein, die sich später nur mit Schmerzen revidieren lassen — meist genau an der Schnittstelle, die man zuerst hätte prüfen sollen.

Kosten realistisch einschätzen

Open Source heißt nicht kostenlos. Auch ohne Lizenzgebühr fallen reale Kosten in vier Bereichen an: Hosting und Betrieb, Entwicklung des Frontends und der Integrationen, laufende Wartung und Updates sowie gegebenenfalls die kommerziellen Enterprise-Bausteine. Wer Medusa gegen eine Suite rechnet, muss diese vier Blöcke gegen die dortigen Lizenz- und Anpassungskosten stellen — ein reiner Vergleich von Lizenzpreisen führt in die Irre.

Abgrenzung zu Nachbarbegriffen

Headless Commerce beschreibt das Prinzip der Trennung von Backend und Frontend. Medusa ist eine konkrete Implementierung dieses Prinzips, aber nicht mit ihm identisch — es bringt ja ein eigenes Admin mit.

Composable Commerce geht einen Schritt weiter und meint den Aufbau eines Stacks aus mehreren spezialisierten Diensten. Medusas Modularität ist dafür eine gute Grundlage, ersetzt aber nicht die Architekturarbeit, die ein solcher Stack verlangt.

Shopsystem im klassischen Sinn liefert Frontend, Backend und Betrieb als Paket. Genau das tut Medusa bewusst nicht.

Ökosystem und Reifegrad

Medusa gehört gemessen an der Aufmerksamkeit auf GitHub zu den sichtbarsten Open-Source-Commerce-Projekten und hat mit Version 2.0 einen harten Schnitt hinter sich. Das ist Chance und Risiko zugleich: Die Architektur ist aufgeräumt und konsequent, aber ältere Tutorials, Blogbeiträge und Community-Plugins beziehen sich teilweise noch auf die erste Generation. Wer recherchiert, sollte deshalb immer prüfen, auf welche Hauptversion sich eine Quelle bezieht — Codebeispiele aus der 1.x-Zeit laufen in 2.x nicht unverändert.

Der Reifegrad unterscheidet sich außerdem stark nach Bereich. Die Kernmodule rund um Produkte, Warenkorb und Bestellung sind gut dokumentiert und breit im Einsatz. Randthemen wie länderspezifische Steuerlogik, Rechnungsformate oder die Anbindung an deutsche Zahlungs- und Versanddienstleister sind dagegen häufig Eigenleistung oder Community-Arbeit. Das ist bei einem Framework erwartbar, muss aber in der Projektplanung als eigener Aufwandsblock auftauchen und nicht als Nebensache.

Praktisch bewährt hat sich, vor der Entscheidung eine kurze Inventur zu machen: Welche Integrationen braucht das Projekt zwingend, für welche davon gibt es einen offiziellen oder aktiv gepflegten Community-Baustein, und was bleibt Eigenbau? Diese Liste ist aussagekräftiger als jeder allgemeine Vergleich zweier Systeme, weil sie den tatsächlichen Abstand zwischen Anspruch und Auslieferungszustand sichtbar macht.

Häufige Fragen

Ist MedusaJS kostenlos? Der MIT-lizenzierte Kern ja. Einzelne Enterprise-Funktionen wie feingranulares Rollenmanagement und SSO sind lizenzpflichtig, und Hosting, Entwicklung und Wartung fallen ohnehin an.

Welche Technologien muss mein Team beherrschen? Node.js und TypeScript für das Backend, PostgreSQL als Datenbank, Redis für Caching und Queues sowie ein Frontend-Framework für die Storefront — in den meisten Projekten Next.js.

Kann ich Medusa neben einem bestehenden Shop betreiben? Ja, das ist einer der typischen Einstiege. Über die Modulstruktur lässt sich zunächst ein einzelner Kanal oder eine einzelne Domäne abbilden, während das Altsystem weiterläuft.

Wie steht es um die Update-Fähigkeit? Weil Erweiterungen über Module und Workflows statt über Core-Eingriffe erfolgen, bleiben Updates grundsätzlich beherrschbar. Voraussetzung ist Disziplin: Wer die vorgesehenen Erweiterungspunkte umgeht, verliert diesen Vorteil wie in jedem anderen System auch.

Eignet sich Medusa für B2B? Ja — Firmenkonten, Bestellfreigaben und kundenindividuelle Preise sind gängige Anwendungsfälle. Achte dabei aber früh auf die lizenzpflichtigen Bausteine, weil Rollenmodelle und Firmen-Login in B2B-Projekten fast immer dazugehören.

Wie groß muss ein Projekt sein, damit sich Medusa rechnet? Eine feste Umsatzschwelle gibt es nicht. Der bessere Indikator ist der Anteil der Prozesse, die vom Standard abweichen. Wenn ein Shop im Wesentlichen Katalog plus Checkout ist, gewinnt fast immer die fertige Plattform. Sobald Preisfindung, Freigabeprozesse oder die Anbindung an führende Bestandssysteme das Projekt prägen, kippt die Rechnung zugunsten eines Frameworks — weil dort genau der Teil billig wird, der in der Suite teuer ist.