Von Medusa zu einem eigenen Shop wechseln

Was Medusa ist, und warum dir schon jetzt mehr gehört als den meisten

Medusa ist eine quelloffene Commerce Plattform, die du selbst betreibst. Der Kern ist eine Node.js Anwendung in TypeScript, aufgebaut als Monorepo aus Commerce und Infrastruktur Modulen, und zum Bauen und Betreiben braucht es eine aktuelle Node Laufzeit.¹ Lizenziert ist das Ganze unter der freizügigen MIT Lizenz, nur die rollenbasierte Zugriffskontrolle der Enterprise Edition steckt hinter einer eigenen kommerziellen Vereinbarung.² Du installierst es, du deployst es, und es liest und schreibt in eine PostgreSQL Datenbank, die auf einer Infrastruktur liegt, die du kontrollierst.³ Dieser eine Umstand verändert den ganzen Charakter dieses Artikels.

Der Großteil der Migrationsserie dreht sich darum, Daten aus einer Plattform zu befreien, die nicht loslassen will. Shopify gibt dir CSV Dateien und behält den Rest. Wix exportiert kaum etwas. Medusa ist der umgekehrte Fall. Die Datenbank gehört dir längst, das Admin gehört dir, und niemand kann deinen Shop abdrehen oder die Miete erhöhen. Ich tue also nicht so, als wärst du gefangen, denn das bist du nicht. Die ehrliche Frage lautet hier anders: Wenn dir das alles schon gehört, ist Medusa dann noch das Richtige, oder wäre deinem Unternehmen mit einem ausgereiften Shop auf Ruby on Rails besser gedient, für den ein Mensch von Anfang bis Ende geradesteht?

Ich baue auf Solidus, einem quelloffenen Commerce Framework auf Rails, du weißt also, wo ich stehe. Genau deshalb bin ich hier besonders fair. Medusa ist ein starkes, modernes, aktiv entwickeltes Projekt, und viele Unternehmen sollten darauf bleiben. Dieser Artikel ist für jene, die ihren Stack angeschaut und festgestellt haben, dass die Passung nicht stimmt.

Wenn du das Prinzip Eigentum in voller Länge willst, steht es in wem deine Geschäftsdaten wirklich gehören, und die ganze Serie beginnt bei was sich beim Umzug eines Shops überträgt und was nicht.

Wer auf Medusa bleiben soll

Die Fairness stelle ich nach vorne, denn sie ist die Glaubwürdigkeit für alles Weitere.

Bleib auf Medusa, wenn dein Team wirklich gern Node.js und TypeScript schreibt und du die Leute hast, die ein Framework aktuell halten. Medusa 2 kam im Oktober 2024 und war ein kompletter architektonischer Neubau des Projekts, mit Brüchen gegenüber der 1.x Reihe.⁴ Dieser Neubau hat eine deutlich stärkere Plattform hervorgebracht, aber er sagt dir auch etwas über die Form des Engagements: Das ist ein junges, schnell bewegtes Framework, und es gut zu besitzen heißt, ein Node Team zu halten, das den Releases folgt und das Modell versteht.

Bleib, wenn dir dieses Modell gefällt. Medusa 2 besteht aus isolierten Modulen. Jedes Modul besitzt seine eigenen Daten und stellt einen Service bereit, und die Module werden bewusst getrennt gehalten, damit keines mit einem direkten Fremdschlüssel in die Tabellen eines anderen greift. Um etwa ein Produkt mit einem eigenen Datensatz zu verbinden, definierst du einen Modul Link, und Medusa legt die Verknüpfung in einer eigenen Verbindungstabelle ab statt als gewöhnliche Beziehung.⁵ Das ist ein durchdachtes Design, das Integrationen sauber hält. Es ist zugleich eine bestimmte Art, über Commerce Daten zu denken, und manche Teams lieben sie, während andere darin mehr Umweg sehen, als ihr Shop braucht.

Bleib, wenn headless wirklich das ist, was du willst. Medusa liefert ein Backend und ein Admin, und dein Storefront ist eine eigene Anwendung, die du baust und betreibst, meist in einem JavaScript Framework. Wenn du eine einzige eigene Anwendung willst, die Storefront, Admin und API gemeinsam bedient, ist das eine andere Architektur, und es ist jene, die ich baue.

Keiner dieser Gründe zu bleiben handelt von Lock in. Deine Daten gehören dir so oder so. Es geht um Passung. Wenn drei davon auf dich zutreffen, ist der ehrliche Rat, diesen Artikel zu schließen und den Medusa Shop weiter zu verbessern, den du ohnehin besitzt.

Die Realität von Export und API: Postgres, die Admin API und CSV

Weil dir Datenbank und API gehören, ist der Datenzugang auf Medusa so gut, wie er nur sein kann. Hier gibt es keine Rettungsaktion, und das ist das schönste Problem, das eine Migration haben kann.

Du hast drei saubere Wege zu deinen Daten, und ein echter Umzug nutzt meist alle drei.

Der erste ist die PostgreSQL Datenbank selbst. Sie gehört dir, auf deiner eigenen Infrastruktur, und ein gewöhnlicher Dump gibt dir jede Tabelle: Produkte, Varianten, Preise, Kunden, Bestellungen, Positionen, Adressen und alles, was deine eigenen Module gespeichert haben.³ Für den Großteil eines Katalogs und die gesamte Bestellhistorie ist das direkte Lesen der Datenbank der vollständigste und schnellste Weg.

Der zweite ist die Admin API. Medusa stellt eine REST Admin API unter dem Pfad /admin bereit, abgesichert über ein Bearer Token, einen API Schlüssel oder eine Session, und sie deckt Produkte, Kunden, Bestellungen und den Rest der Verwaltung ab.⁶ Eine API ist das richtige Werkzeug, wenn du Datensätze in einer Form willst, die die Anwendung versteht, mit aufgelösten Preisen und Beziehungen, statt roher Zeilen. Sie ist auch der Weg, einen wiederholbaren Export zu skripten, den du am Umzugstag erneut laufen lässt.

Der dritte ist der eingebaute CSV Import und Export für Produkte. Jede Zeile steht für eine Produktvariante, Medusa liefert eine Vorlage, und dasselbe Format geht in beide Richtungen, ein Produktkatalog zieht also über eine Datei um, die du lesen, prüfen und vergleichen kannst.⁷ Für Produkte ist das oft die sauberste Brücke in einen neuen Shop.

Passwörter sind das Einzige, was nicht mitreist, und das gilt überall, es ist kein Mangel von Medusa. Sie liegen als Einweg Hashes, lassen sich also nicht in Passwörter zurückrechnen und mitnehmen. Entweder prüfst du den alten Hash einmal beim ersten Anmelden, oder du bittest, einfacher, jede Kundin um ein Zurücksetzen. Beide Wege, und wie du das Zurücksetzen als ruhigen Neustart statt als Support Feuer gestaltest, beschreibe ich in Kundenkonten und Adressen migrieren.

Der Umzug von Medusa weg ist also kein Problem der Datenrettung. Es ist ein Neubau des Backends: dieselben gut strukturierten Daten landen in einer Rails Anwendung, und die Geschäftslogik wird in Solidus und Ruby neu geschrieben statt in Medusa Modulen und TypeScript.

Der ehrliche Grund zu wechseln ist Passung, nicht Lock in

Wenn die Daten sauber herauskommen, warum überhaupt wechseln? Vier ehrliche Gründe, von denen keiner lautet, Medusa sei eine schwache Plattform.

Der erste ist Ökosystem und Sprache. Ruby on Rails ist zwanzig Jahre alt, und Solidus ist ein ausgereiftes Commerce Framework darauf, unter der BSD Lizenz mit drei Klauseln.⁸ Für ein Unternehmen, das das Ökosystem von Rails will, seine Konventionen, seinen riesigen Pool an Entwicklern und seine lange Bilanz an Shops im Produktivbetrieb, ist der Wechsel von Node zu Rails eine vernünftige strategische Entscheidung. Es geht nicht darum, dass eine Sprache besser ist. Es geht darum, dass du jene willst, für die dein Unternehmen im kommenden Jahrzehnt einstellen und bauen wird.

Der zweite ist ein verantwortlicher Erbauer. Auf Medusa ist es laufende Arbeit, ein junges Framework aktuell zu halten, seine Releases zu beobachten und seine Architektur weiterzutragen, und das will meist ein Team, das Node gut kennt. Manche Unternehmen hätten lieber einen Menschen, der den ganzen Shop entwirft, baut, testet und wartet und dafür geradesteht, als eine Framework Roadmap und die Spezialisten, um sie zu verfolgen. In diesem Modell arbeite ich: Ich baue den Solidus Shop, ich führe den Umzug durch, und der maßgeschneiderte Code gehört dir mit vollständiger Bezahlung.

Der dritte ist die Erwartung an Reife und Stabilität. Medusa bewegt sich rasch, und der Sprung von 1.x auf 2 war ein Neubau. Wenn du eine Plattform willst, bei der eine Hauptversion alle paar Jahre geplante, schrittweise Wartung ist statt eines Neubaus, dann folgt Solidus strenger semantischer Versionierung mit einem langsamen, über Deprecations geführten Pfad, und diese Vorhersehbarkeit ist viel wert für jemanden, der die Rechnungen unterschreibt.

Der vierte ist das Drumherum an Diensten. Ein produktives Medusa Deployment stützt sich meist auf mehr als Postgres: Redis für Event Bus, Caching, Locking und die Workflow Engine, einen Dateidienst wie S3, einen Benachrichtigungsdienst für E Mail und ein getrennt deploytes Storefront.³ Das ist eine sinnvolle Architektur, und das verwaltete Medusa Cloud gibt es genau dafür, dir das zu betreiben. Aber wenn du lieber eine kleinere Betriebsfläche besitzt, eine einzige Rails Anwendung mit PostgreSQL und einer Warteschlange für Hintergrundjobs, deployt so, wie ich alles deploye, dann ist diese Einfachheit ein legitimer Wunsch.

Achte darauf, was keiner davon ist. Keiner lautet "Medusa sperrt dich ein" oder "du kommst nicht an deine Daten". Alle handeln von Passung. Sei ehrlich zu dir, welcher davon tatsächlich auf dein Unternehmen zutrifft, denn wenn keiner greift, sollst du bleiben.

Vier Dinge, die du zuerst klärst

Ein Medusa Umzug verläuft meist ruhig, aber vier Bereiche tragen das Risiko. Sprich sie im ersten Gespräch an, nicht in der letzten Woche.

Zahlungen und gespeicherte Karten. Medusa wickelt Zahlungen über Modul Provider ab, Stripe ist der häufige, und die sensiblen Kartendaten liegen beim Gateway, nie in deiner Medusa Datenbank. Das ist eine gute Nachricht für eine Migration. Wenn dein neuer Solidus Shop sich mit demselben Stripe Konto verbindet, bleiben die gespeicherten Karten und ihre Token genau dort, wo sie sind, und deine Kundschaft merkt nichts. Wechselst du das Gateway, ist das der harte Fall, und die Regeln sind dieselben wie bei jeder Plattform. Ich lege sie in Zahlungstoken und gespeicherte Karten migrieren dar.

Abonnements und wiederkehrende Zahlungen. Der Medusa Kern liefert keine Abo Maschine, wenn du also auf wiederkehrender Basis verkaufst, hast du diese Logik selbst gebaut, in eigenen Modulen, Workflows und einem geplanten Job, oder einen Anbieter angeflanscht. Das heißt, es gibt echte Geschäftslogik zu verstehen und neu auszudrücken, und es kann aktive Mandate und Token bei einem Gateway geben, die Sorgfalt brauchen. Die Konzepte, und was sich überträgt und was nicht, stehen in Abonnements und wiederkehrende Zahlungen migrieren.

Eigene Module halten deine Logik. Die Stärke von Medusa ist, dass du dein besonderes Geschäft vermutlich in seinen Modulen und Workflows abgebildet hast. Dieselbe Logik ist die Arbeit des Umzugs. Jedes eigene Modul, jeder Workflow, jede maßgeschneiderte Regel muss verstanden und als Rails und Solidus Code neu gebaut werden, mit Tests. Je mehr du gebaut hast, desto größer ist dieser Teil, und er gehört ehrlich geschätzt, nicht weggewunken.

SEO und der Weiterleitungsplan liegen in deinem Storefront. Weil Medusa headless ist, gehören deine URLs deinem Storefront, nicht Medusa. Die Pfade für Produkte, Kategorien und Inhalte, die deine Rankings tragen, sind in diesem Frontend definiert, der Weiterleitungsplan wird also aus den Routen deines Storefronts gezogen. Jede alte URL auf eine dauerhafte Weiterleitung abzubilden ist der wertvollste Tag des ganzen Projekts, und ich behandle ihn bei jeder Migration gleich. Die volle Methode steht in Produkt und Katalogdaten migrieren.

So sieht es auf einen Blick aus.

Bereich	Was sauber umzieht	Was Sorgfalt braucht
Katalog	Produkte, Varianten, Preise, Bilder über Datenbank, Admin API oder CSV	Abbildung auf das Solidus Modell
Kunden	Namen, Adressen, Verknüpfung zu Bestellungen	Passwörter ziehen nie um, also zurücksetzen oder prüfen
Bestellungen	Volle Historie aus der Datenbank	Entscheiden, wie weit zurück
Zahlungen	Token bleiben bei gleichem Gateway	Ein Gateway Wechsel ist der harte Fall
Abonnements	Die Datensätze	Aktive Mandate und deine eigene Abo Logik
Storefront und SEO	Nichts automatisch	Frontend neu bauen, jede URL abbilden

Ein Beispiel: eine Grazer Marke zieht von Medusa weg

Ich mache es konkret mit einem erfundenen Unternehmen. Nichts davon ist ein echter Kunde.

Almgrün Vertrieb (almgruenvertrieb.example) ist eine Grazer Marke, die Outdoor und Camping Ausrüstung direkt an Endkundinnen verkauft. Vor drei Jahren hat ein fähiger Auftragnehmer ihnen ein Medusa Backend mit einem Next.js Storefront gebaut, und es hat ihnen gute Dienste geleistet: rund 2.500 Produkte mit Varianten, ein aufgeräumtes Admin, ein eigenes Modul für ein selbst zusammengestelltes Ausrüstungsset und Stripe für Zahlungen. Alles davon gehört ihnen, auf eigenen Servern.

Warum reden sie also mit mir? Der Auftragnehmer ist weitergezogen, Storefront und Backend laufen auf einer Medusa Version, die nun ein Jahr zurückliegt, und jede Agentur, die sie anrufen, bepreist das als Node Projekt, das ein Team braucht. Die Gründerin will zweierlei: nicht mehr von rarem, framework spezifischem Wissen abhängen, und einen Menschen haben, der für den Shop geradesteht und in drei Jahren noch da ist. Sie sind ohnehin ein Rails nahes Unternehmen, denn ihr Lagerwerkzeug ist eine kleine Rails Anwendung. Die Passung ist verrutscht.

Wir beginnen mit dem ehrlichen Gespräch, und ich sage der Gründerin klar, dass nichts diesen Umzug erzwingt. Die Daten sind sicher und der Shop läuft. Wären sie auf Node glücklich, würde ich zum Bleiben raten. Sind sie nicht, also machen wir weiter.

Die Zahlungsfrage wird im ersten Treffen geklärt, dorthin gehört sie. Almgrün behält das eigene Stripe Konto, der neue Solidus Shop verbindet sich mit genau diesem Konto, und die gespeicherten Karten ziehen einfach mit. Keine Kundin gibt eine Karte neu ein.

Die Daten selbst sind der leichte Teil. Ich nehme einen PostgreSQL Dump für den vollen Katalog und die Bestellhistorie, nutze die Admin API, um aufgelöste Produkt und Kundendaten zum Prüfen zu ziehen, und nutze den CSV Export, um den Katalog beim Laden in Solidus abzugleichen.³⁶⁷ Passwörter sind gehasht, also planen wir ein Zurücksetzen als Neustart, mit einer Servicenachricht vor dem Umzug.

Die eigentliche Arbeit sind das eigene Set Modul und das Next.js Storefront. Die Logik des selbst zusammengestellten Sets wird als gewöhnlicher Solidus und Rails Code neu ausgedrückt, mit einem Cucumber Test für jede Regel, damit die Gründerin lesen kann, was der Shop verspricht. Das Storefront wird Teil der einen Solidus Anwendung, die ich baue, und wir ziehen den Weiterleitungsplan aus den alten Next.js Routen, damit beim Umzug kein einziges Ranking fällt. Innerhalb eines geplanten Fensters ist Almgrün auf einem Shop, der ihnen so vollständig gehört wie zuvor, nun in dem Ökosystem, zu dem sie ohnehin neigten, mit einem Menschen, den sie anrufen können.

Der Umzug, abgebildet auf die Datenleitfäden

In einem Plattformartikel erkläre ich die tiefe Mechanik nicht neu, denn die Leitfäden zu den Datentypen besitzen sie. Hier ist die Abbildung für einen Medusa Umzug.

• Produkte, Varianten, Preise, Kategorien, Bilder und der so wichtige Weiterleitungsplan: Produkt und Katalogdaten migrieren.
• Kundenkonten, Adressen und das Zurücksetzen der Passwörter als Neustart: Kundenkonten und Adressen migrieren.
• Gespeicherte Karten und verwahrte Token, und warum dasselbe Gateway der stille Gewinn ist: Zahlungstoken und gespeicherte Karten migrieren.
• Wiederkehrende Pläne, Mandate und die Logik dahinter: Abonnements und wiederkehrende Zahlungen migrieren.
• Das Prinzip Eigentum unter allem: wem deine Geschäftsdaten wirklich gehören.

Zwei weitere Stücke liest du gut neben diesem. Willst du die Zahlen, so baut die Gesamtkosten über fünf Jahre ein volles Modell für einen Umzug auf Solidus. Wägst du Solidus breiter gegen die gemieteten Plattformen ab, ist der Plattformvergleich das Stück dazu. Und weil du ohnehin aus einem headless Aufbau kommst, erklärt headless und API first Solidus, wie ein Solidus Shop die API behält, die du gewohnt bist.

Wenn dein Grund, nach Medusa Alternativen zu schauen, in Wahrheit ein Vergleich moderner Commerce Frameworks ist, liegen zwei weitere quelloffene Projekte im selben Feld. Saleor ist eine Plattform in Python und GraphQL, und commercetools ist das lizenzierte Enterprise Ende von headless. Ich behandle sie fair in eigenen Stücken, von Saleor zu einem eigenen Shop wechseln und von commercetools zu einem eigenen Shop wechseln.

Was du mitnimmst

Stell die Frage, die ich jeder Plattform stelle: Wenn ich in vier Jahren wieder wechseln will, womit gehe ich?

Von Medusa mit viel, und das spricht für sie. Du nimmst deine PostgreSQL Datenbank, dein Repository und einen Shop mit, den du ohnehin auf eigenen Servern betrieben hast. Von Solidus nimmst du genau dieselbe Art Sache: eine Ruby on Rails Anwendung und eine PostgreSQL Datenbank, die dir vollständig gehören, auf einer Infrastruktur, die du kontrollierst, mit dem maßgeschneiderten Code, der dir mit vollständiger Bezahlung gehört. Der Unterschied zwischen beiden ist nicht Eigentum, denn das geben dir beide. Es ist das Ökosystem, in dem du stehst, die Reife des Frameworks und ob ein verantwortlicher Erbauer oder ein Node Team die richtige Form für dein Unternehmen ist.

Das ist der ganze ehrliche Fall. Du entkommst keiner Falle. Du wählst ein anderes, ausgereiftes, ebenso eigenes Fundament, weil es besser zu dir passt.

Wem ich zum Wechsel rate, und wem zum Bleiben

Bleib auf Medusa, wenn du Node und TypeScript Leute hast, die die Arbeit mögen, dir das Modul und Workflow Modell gefällt und headless die Architektur ist, die du willst. Deine Daten und dein Deployment gehören dir schon. Wechsle nicht um des Wechsels willen.

Wechsle zu Solidus, wenn du lieber auf Ruby on Rails baust, wenn du einen Menschen willst, der für den ganzen Shop von Anfang bis Ende geradesteht, statt eines Frameworks, das aktuell zu halten ist, wenn du eine reife Plattform mit langsamem, vorhersehbarem Pfad bevorzugst, oder wenn du eine einzige eigene Anwendung willst statt eines Backends, eines Storefronts und einer Reihe von Hilfsdiensten. Die Daten kommen sauber herüber. Die Arbeit, und der Wert, liegt im Neubau deiner Logik und deines Storefronts.

Bist du dir nicht sicher, welches davon du bist, ist genau das der Zweck des Workshops. Bring deinen Medusa Aufbau, deine eigenen Module und deinen ehrlichen Ärger mit, und ich sage dir, ob sich ein Umzug für dein Unternehmen wirklich auszahlt. Manchmal tut er das nicht, und dann sage ich es.

Footnotes

1. Medusa, README und Contribution Guide, medusajs/medusa auf GitHub (Node.js v22 oder neuer, ein Monorepo mit Yarn Workspaces, Commerce und Infrastructure Module), abgerufen am 14. November 2026, https://github.com/medusajs/medusa ↩

2. Medusa, Lizenz und README, medusajs/medusa auf GitHub (MIT Lizenz, die Enterprise Edition über eine eigene kommerzielle Vereinbarung), abgerufen am 14. November 2026, https://github.com/medusajs/medusa/blob/develop/LICENSE und https://github.com/medusajs/medusa ↩

3. Medusa Documentation, Architecture (ein Server auf Express, API Routen zu Workflows zu Modulen zu PostgreSQL, PostgreSQL als einzige nativ unterstützte Datenbank, auf Redis gestützte Infrastruktur Module und Medusa Cloud als verwaltetes Hosting), abgerufen am 14. November 2026, https://docs.medusajs.com/learn/introduction/architecture ↩ ↩² ↩³ ↩⁴

4. Medusa, Medusa 2.0 is now generally available, 23. Oktober 2024 (ein kompletter architektonischer Neubau mit Brüchen gegenüber der 1.x Reihe), https://medusajs.com/blog/v2-release/ ↩

5. Medusa Documentation, Module links (Module sind isoliert und können keinen direkten Fremdschlüssel in die Daten eines anderen Moduls legen, Verknüpfungen liegen daher in einer eigenen Verbindungstabelle), abgerufen am 14. November 2026, https://docs.medusajs.com/learn/fundamentals/module-links ↩

6. Medusa Documentation, Admin API reference (REST Routen unter dem Präfix /admin, abgesichert über ein Bearer Token, einen API Schlüssel oder eine Session), abgerufen am 14. November 2026, https://docs.medusajs.com/api/admin ↩ ↩²

7. Medusa Documentation, Import products via CSV (eine Zeile je Produktvariante, mit herunterladbarer Vorlage und demselben Format für den Export), abgerufen am 14. November 2026, https://docs.medusajs.com/user-guide/products/import ↩ ↩²

8. Solidus, Repository solidusio/solidus auf GitHub (ein quelloffenes Commerce Framework auf Ruby on Rails, unter der BSD Lizenz mit drei Klauseln), abgerufen am 14. November 2026, https://github.com/solidusio/solidus ↩