Medusa.js-Tutorial 2026: Onlineshop mit Next.js aufsetzen

Auf Deutsch gibt es zu Medusa fast nichts. Als ich 2025 angefangen habe, damit zu arbeiten, fand ich genau ein deutschsprachiges Tutorial, und das basiert inzwischen auf einem veralteten Setup. Gleichzeitig ist Medusa.js eines der aktivsten Open-Source-Commerce-Frameworks überhaupt, mit rund 36.000 GitHub-Sternen.

Diese Lücke schließt dieser Guide. Sie setzen Schritt für Schritt einen lauffähigen Onlineshop auf: Backend, Admin-Dashboard, Postgres und Redis per Docker, dazu der offizielle Next.js-Storefront. Jeder Befehl hier ist am 27. August 2026 gegen die offizielle Dokumentation geprüft, Basis ist Medusa v2.19.0 (Release vom 13. August 2026). Am Ende wissen Sie außerdem, über welche vier Fehler Einsteiger am häufigsten stolpern und was auf dem Weg in die Produktion als Nächstes kommt.

Ich schreibe das nicht aus der Theorie: Ich betreibe auf Medusa v2 einen Marketplace mit 10.000 Produkten und 50 Händlern in Produktion. Das hier ist das Tutorial, das ich am Anfang gern gehabt hätte.

Was ist Medusa.js?

Medusa.js ist ein Open-Source-Commerce-Framework in TypeScript: Es liefert Warenkorb, Bestellungen, Produkte, Zahlungen und Lagerbestand als fertige Module und überlässt Ihnen Storefront und Geschäftslogik. Der Kern steht unter MIT-Lizenz, als Datenbank dient ausschließlich PostgreSQL, die API basiert auf Express.js.

Der Unterschied zu Shopsystemen wie Shopify oder Shopware: Medusa ist headless. Das Backend liefert eine API, kein fertiges Frontend. Den Storefront bauen Sie selbst oder starten mit dem offiziellen Next.js-Template. Für Teams, die ohnehin in JavaScript und TypeScript zu Hause sind, fühlt sich das an wie normale Anwendungsentwicklung, nicht wie Plugin-Konfiguration.

Zwei Konzepte sollten Sie kennen, bevor Sie loslegen:

• Module — wiederverwendbare Pakete für je eine Domäne: Products, Orders, Customers und weitere Commerce-Module.
• Workflows — Abfolgen von Schritten für Geschäftslogik, mit definierbarer Rollback-Logik pro Schritt. Schlägt ein Schritt fehl, laufen Kompensationsfunktionen und die Daten bleiben konsistent.

Mit beidem arbeiten Sie in diesem Tutorial nur indirekt; anfassen müssen Sie es erst, wenn Sie eigene Funktionen bauen.

Neben den Commerce-Modulen gibt es eine zweite Kategorie: Infrastruktur-Module für Analytics, Caching, Events, Workflow-Engine, Dateien, Benachrichtigungen und Locking. Sie sind austauschbar: Lokal reicht die eingebaute In-Memory-Variante, in der Produktion stecken Sie Redis oder S3 dahinter, ohne Geschäftslogik anzufassen. Dieses Baukastenprinzip ist der Grund, warum sich Medusa-Projekte so unterschiedlich anfühlen können: Das Framework gibt die Architektur vor, nicht den Funktionsumfang.

Genauso ehrlich gehört dazu: Wer einen Standardkatalog mit Standard-Checkout betreiben will und kein JavaScript-Team hat, fährt mit Shopify oder Shopware schneller — wann genau, zeigt der Vergleich mit Shopware. Medusa spielt seine Stärken aus, sobald individuelle Logik Teil des Produkts ist: eigene Preismodelle, B2B-Freigaben, Marketplace-Funktionen. Die komplette Kostenrechnung beider Wege habe ich im Medusa-vs.-Shopify-Vergleich aufgeschlüsselt, und wo Medusa im Gesamtfeld steht, zeigt der Shopsystem-Vergleich 2026.

Einen Überblick, wo sich der Einsatz von Medusa geschäftlich lohnt, gibt meine Seite zu E-Commerce-Projekten. Hier geht es jetzt ums Handwerk.

Welche Voraussetzungen brauchen Sie?

Sie brauchen Node.js in einer LTS-Version, Git und eine laufende PostgreSQL-Instanz; mehr verlangt die offizielle Installationsanleitung nicht. Konkret, Stand August 2026:

Die Node-Obergrenze für den Storefront ist so ein Detail, das gern eine halbe Stunde kostet: Wer auf einer brandneuen Node-Version unterwegs ist, installiert das Backend problemlos und wundert sich dann über den Starter. Prüfen Sie es vorher:

node --version
psql --version

Der Datenbank-User braucht übrigens Create-Rechte, denn der Installer legt die Datenbank selbst an. Bei einer frischen lokalen Postgres-Installation ist das der Standardfall.

Wie installieren Sie Medusa mit create-medusa-app?

Die Installation ist ein einziger Befehl. create-medusa-app legt das Projekt an, erstellt die PostgreSQL-Datenbank, führt alle Migrationen aus, spielt Seed-Daten ein und öffnet am Ende den Browser:

npx create-medusa-app@latest mein-shop

Mit Yarn oder pnpm entsprechend yarn dlx create-medusa-app@latest mein-shop beziehungsweise pnpm dlx create-medusa-app@latest mein-shop. Während der Installation stellt das Tool genau eine Frage: ob der Next.js Starter Storefront mitinstalliert werden soll. Für dieses Tutorial: Ja.

Die Datenbank bekommt automatisch den Namen medusa-mein-shop, nach dem Schema medusa-{Projektname}. Läuft Ihre Postgres-Instanz nicht mit Standardwerten, übergeben Sie die Verbindung direkt und überspringen damit die Datenbankerstellung:

npx create-medusa-app@latest mein-shop --db-url "postgres://user:passwort@localhost:5432/mein-shop-db"

Weitere nützliche Flags aus der CLI-Referenz: --skip-db, --no-migrations, --with-nextjs-starter, --no-browser.

Nach ein paar Minuten läuft das Backend auf http://localhost:9000, das Admin-Dashboard auf http://localhost:9000/app. Die Verbindungsdaten landen in der .env des Projekts als DATABASE_URL; das Format ist postgres://[user][:passwort]@[host][:port]/[datenbank].

(Screenshot folgt: Terminal nach erfolgreichem create-medusa-app-Lauf)

Wie richten Sie Postgres und Redis mit Docker ein?

Docker ist optional, aber der sauberste Weg, die Infrastruktur zu betreiben: Postgres und Redis laufen im Container, Medusa selbst läuft weiter ganz normal per npm run dev auf Ihrem Rechner. Medusa pflegt dafür eine offizielle Docker-Anleitung samt Repository medusajs/docker-medusa, dort mit postgres:15-alpine, redis:7-alpine und einem Start per npm run docker:up.

Für den Tutorial-Anwendungsfall (nur die Infrastruktur im Container) reicht diese kompakte docker-compose.yml:

services:
  postgres:
    image: postgres:15-alpine        # Version aus dem offiziellen Medusa-Setup
    environment:
      POSTGRES_USER: medusa
      POSTGRES_PASSWORD: medusa
      POSTGRES_DB: mein-shop-db
    ports:
      - "5432:5432"                  # Standard-Postgres-Port
    volumes:
      - pgdata:/var/lib/postgresql/data   # Daten überleben Container-Neustarts

  redis:
    image: redis:7-alpine            # für Events, Caching, Workflows (Produktion)
    ports:
      - "6379:6379"

volumes:
  pgdata:

Starten mit docker compose up -d, danach die DATABASE_URL in der .env auf postgres://medusa:medusa@localhost:5432/mein-shop-db setzen. Redis braucht das lokale Dev-Setup noch nicht zwingend; Medusa nutzt es in der Produktion für Events, Caching und die Workflow-Engine; die Umgebungsvariable dafür ist REDIS_URL.

(Screenshot folgt: docker ps mit laufenden postgres- und redis-Containern)

Übrigens der Punkt, an dem ich ehrlich zwiegespalten bin: Das vollständige offizielle Docker-Setup containerisiert auch das Medusa-Backend selbst. Für die lokale Entwicklung finde ich das unnötig schwerfällig: Hot Reload und Debugging sind ohne Container direkter. Für reproduzierbare Team-Setups spricht dagegen einiges. Beide Wege sind legitim.

Wie legen Sie einen Admin-User an?

Der einfachste Weg läuft automatisch: Nach der Installation öffnet create-medusa-app das Admin-Dashboard im Browser und führt Sie durch die Erstellung des ersten Users. Falls Sie den Schritt übersprungen haben oder später weitere User brauchen, geht es per CLI:

npx medusa user --email admin@example.com --password sicheres-passwort

Die Kurzform ist -e und -p; lassen Sie --password weg, wird ein Passwort abgefragt. Mit --invite erstellen Sie statt eines Users eine Einladung mit Token, praktisch, wenn Kolleginnen und Kollegen ihr Passwort selbst setzen sollen.

Danach anmelden unter http://localhost:9000/app. Das Dashboard ist der Ort, an dem Sie ab jetzt Produkte, Bestellungen, Kunden, Preislisten und API-Keys verwalten.

(Screenshot folgt: Login-Maske des Medusa-Admin)

(Screenshot folgt: Admin-Dashboard nach dem ersten Login)

Wie starten Sie den Next.js Storefront?

Wenn Sie die Installationsfrage mit Ja beantwortet haben, liegt der Storefront bereits neben Ihrem Backend-Projekt und läuft auf http://localhost:8000. Alternativ installieren Sie beides zusammen mit einem Flag:

npx create-medusa-app@latest --with-nextjs-starter

Für die manuelle Installation, etwa in einem bestehenden Monorepo, verweist die Doku heute auf das Repository medusajs/dtc-starter: mit --depth=1 klonen und apps/storefront ins eigene Projekt kopieren, gestartet wird mit npm run dev im Storefront-Verzeichnis.

Der Storefront braucht zwei Umgebungsvariablen, um mit dem Backend zu sprechen:

NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_...

Den Publishable Key finden Sie im Admin unter Settings → API Key Management. Er ist der Schlüssel, mit dem sich der Storefront gegenüber der Store-API ausweist. Wer Stripe anbinden will, ergänzt später NEXT_PUBLIC_STRIPE_KEY.

Damit steht der Stack komplett: Next.js-Storefront auf Port 8000, Medusa-Backend samt Admin auf Port 9000, dahinter Postgres und optional Redis. Der Starter bringt App Router, Server Components, Warenkorb und Checkout-Grundgerüst bereits mit; angepasst wird er wie jede andere Next.js-Anwendung.

(Screenshot folgt: Next.js Storefront mit Demo-Produkten)

Wie legen Sie erste Produkte und Kategorien an?

Die Seed-Daten der Installation liefern bereits Demo-Produkte. Für ein Gefühl fürs Datenmodell lohnt es sich trotzdem, ein eigenes Produkt von Hand anzulegen. Im Admin unter Products → Create: Titel, Beschreibung, Bilder, dann Optionen (etwa Größe oder Farbe), aus denen das System die Varianten generiert, zum Schluss Preise pro Währung und der Lagerbestand.

Kategorien funktionieren analog unter Categories: Struktur anlegen, Produkte zuordnen, fertig. Der Next.js-Starter zieht sich beides automatisch über die API; nach einem Reload sehen Sie Ihr Produkt im Storefront.

Zwei Dinge fallen Umsteigern von WooCommerce oder Shopware hier positiv auf: Varianten sind ein sauberes Datenmodell statt eines Plugin-Konstrukts, und mehrere Währungen sind von Haus aus vorgesehen. Die Kehrseite: Felder wie „Meta-Titel pro Kategorie“ oder deutsche Rechnungsstellung gibt es nicht ab Werk. Das ist hier bewusst Ihre Aufgabe beziehungsweise die eines Moduls.

(Screenshot folgt: Produktformular im Admin)

(Screenshot folgt: Kategorieliste im Admin)

Das komplette Setup auf einen Blick

Für alle, die direkt loslegen wollen: der gesamte Weg von null zum laufenden Shop, alle Befehle am 27. August 2026 gegen die Doku geprüft:

# 1. Infrastruktur starten (optional, wenn Postgres nicht lokal läuft)
docker compose up -d

# 2. Projekt anlegen — Frage nach dem Next.js Starter mit Ja beantworten
npx create-medusa-app@latest mein-shop

# 3. Falls nötig: Migrationen nachziehen und Admin-User anlegen
npx medusa db:migrate
npx medusa user --email admin@example.com --password sicheres-passwort

# 4. Läuft alles? Health-Check des Backends
curl http://localhost:9000/health   # antwortet mit: OK

Danach: Backend und Admin auf http://localhost:9000 beziehungsweise /app, Storefront auf http://localhost:8000. Der Health-Endpoint aus Schritt 4 ist derselbe, den Sie später in der Produktion für Uptime-Checks verwenden; er gehört zum dokumentierten Deployment-Setup.

Ein Wort zur API-Struktur, weil sie beim Weiterbauen sofort relevant wird: Medusa trennt strikt zwischen der Store-API (konsumiert vom Storefront, authentifiziert über den Publishable Key) und der Admin-API (konsumiert vom Dashboard). Eigene Endpunkte hängen Sie später an genau diese zwei Oberflächen; dazu gleich mehr.

Wo passen Sie Medusa später an?

Die zentrale Konfigurationsdatei ist medusa-config.ts: Dort liegen databaseUrl, registrierte Module und später der workerMode. Alles Weitere folgt drei Mustern, die sich durch die gesamte Medusa-Entwicklung ziehen:

• Eigene API-Routen — zusätzliche Endpunkte neben der Store- und Admin-API, etwa für einen Händler-Export oder ein internes Dashboard.
• Eigene Module — ein wiederverwendbares Paket pro Domäne. Ihr Datenmodell für, sagen wir, Produkt-Zertifikate lebt in einem Modul, sauber getrennt vom Kern.
• Workflows — mehrstufige Geschäftslogik mit Kompensationsfunktionen: Schlägt Schritt drei fehl, macht Medusa Schritt eins und zwei kontrolliert rückgängig. Die Workflow-Dokumentation zeigt das Muster; gerade bei Zahlungs- und Bestandsoperationen ist es Gold wert.

Für dieses Tutorial müssen Sie nichts davon anfassen. Aber es lohnt sich, die drei Begriffe im Kopf zu haben, wenn Sie in der Doku unterwegs sind; praktisch jede Anleitung dort setzt auf eines dieser Muster auf.

Häufige Fehler und ihre Lösungen

Vier Probleme tauchen in den GitHub-Issues von Medusa immer wieder auf. Alle vier sind gelöst beziehungsweise vermeidbar, wenn man weiß, wo man hinschauen muss.

Warum bricht db:migrate mit einem SSL-Fehler ab?

The server does not support SSL connections heißt fast immer: Die DATABASE_URL erzwingt SSL, aber Ihre lokale Postgres-Instanz spricht keins (Issue #10162). Lokal gehört kein sslmode=require in die URL; bei Managed-Datenbanken ist es umgekehrt oft Pflicht.

Warum scheitert die Migration an der Tabelle tax_provider?

Das trat bei der Installation über create-medusa-app auf, wenn Migrationen in falscher Reihenfolge liefen (Issue #12890). Mit aktuellem Installer und npx medusa db:migrate auf frischer Datenbank ist das Geschichte. Bei halb migrierten Datenbanken hilft meist nur: Datenbank löschen, neu anlegen, sauber migrieren.

Warum installiert pnpm den Next.js-Starter nicht?

create-medusa-app über pnpm konnte am Next.js Starter scheitern (Issue #14675). Falls Sie es eilig haben: mit npm installieren, später zu pnpm wechseln.

Warum lässt sich kein Admin-User anlegen?

Fehler bei medusa user gehen fast immer auf eine unvollständig migrierte Datenbank zurück (Issue #13011). Erst npx medusa db:migrate, dann den User anlegen — diese Reihenfolge löst es in den dokumentierten Fällen.

Wie geht es nach dem Tutorial weiter?

Ihr lokaler Shop läuft — der Weg in die Produktion hat ab hier drei Pflichtstationen: Worker Mode, Redis und ein S3-kompatibler Datei-Speicher. Die Doku ist da unmissverständlich: Der Standard-Modus, in dem Server und Hintergrund-Jobs in einem Prozess laufen, „is not optimal for production environments". Stattdessen laufen zwei Instanzen — eine mit workerMode: 'server' für Requests, eine mit workerMode: 'worker' für Hintergrund-Aufgaben, konfiguriert über eine Umgebungsvariable. Dazu kommen mindestens 2 GB RAM laut Deployment-Guide, Redis für Events, Caching und Workflow-Engine sowie npx medusa build für das Produktions-Build. Wohin damit – Railway, Vercel oder eigener Server – klärt mein Deployment-Vergleich mit geprüften Preisen.

Konkret erwartet der Produktions-Guide unter anderem diese Umgebungsvariablen:

Das Produktions-Build erzeugt npx medusa build — es landet als eigenständiges Paket in .medusa/server, ohne Abhängigkeit von den TypeScript-Quellen. Gestartet wird dort mit npm install, dem predeploy-Skript (führt medusa db:migrate aus) und npm run start. Ob alles läuft, verrät der dokumentierte Health-Endpoint: GET /health antwortet schlicht mit OK.

Redis übernimmt in der Produktion vier Infrastruktur-Module auf einmal — Caching, Event-Bus, Workflow-Engine und Locking. Deshalb steht es oben als Pflichtstation: Ohne Redis laufen diese Systeme in flüchtigen In-Memory-Varianten, die einen Neustart nicht überleben.

Das klingt nach viel — ist es aber nicht, wenn die Plattform mitspielt. Mein Produktions-Setup läuft auf Railway: Die einzelnen Services bauen dort in zwei bis drei Minuten und deployen parallel, und über das Railway MCP lässt sich die komplette Infrastruktur inzwischen direkt aus dem AI-Coding-Workflow heraus verwalten. Der ausführliche Deployment-Vergleich (Railway, VPS, Vercel-Hybrid — mit durchgerechneten Kosten) erscheint als Nächstes hier im Blog.

Und wenn aus dem Shop mehr werden soll: Auf derselben Basis habe ich einen Multi-Vendor-Marketplace mit 50 Händlern gebaut — der Praxisbericht dazu ist in Arbeit. Bis dahin finden Sie alle Artikel rund um offene Shopsysteme im Themenbereich E-Commerce.

Sie wollen nicht Wochen in Eigenrecherche stecken, sondern in zwei Wochen einen belastbaren Prototyp sehen? Genau dafür gibt es meinen Proof-of-Concept Sprint. Und wenn Sie erst einmal sortieren möchten, ob Medusa für Ihr Vorhaben überhaupt die richtige Basis ist: Buchen Sie ein kostenloses Erstgespräch — 30 Minuten, ohne Verkaufsgespräch, dafür mit einer ehrlichen Einschätzung.