Migration zu Next.js / Astro in Düsseldorf

Sie verkaufen in Düsseldorf mit WooCommerce und wollen die Website auf Astro oder Next.js umstellen? Dann steht vor jeder Framework-Frage eine andere: Bleibt WooCommerce das Commerce-Backend hinter dem neuen Frontend, oder bleibt der Shop ganz auf WordPress, und nur die Inhaltsseiten ziehen um? Beide Wege funktionieren. Welcher für Ihren Shop passt, entscheiden die Zahlungsplugins und Checkout-Erweiterungen, die heute im Theme rendern, und die Pflichten aus Preisangabenverordnung und BGB, die auf der Seite stehen müssen, egal wer sie ausliefert. Ich bin Mariusz Szatkowski, arbeite allein aus Gdynia mit WordPress seit 2006, schriftlich und ohne Termine. Das Layout liefern Sie oder Ihre Agentur, ich setze es um.

#Zwei Wege für einen WooCommerce-Shop

Weg A: WooCommerce bleibt Backend, das Frontend ist neu. Produkte, Lager, Bestellungen, Steuern, Versand und Zahlungsabwicklung bleiben in WooCommerce. Astro oder Next.js zeigen Kategorien und Produktseiten an, führen den Warenkorb und schicken die Bestellung über die Store API an WooCommerce. Ihr Team pflegt Produkte weiter im gewohnten Admin. Der Checkout ist danach aber Code im neuen Projekt, und alles, was heute ein Plugin an der Kasse einblendet, muss dort neu entstehen.

Weg B: Der Shop bleibt auf WordPress, nur die Inhaltsseite zieht um. Ratgeber, Blog, Markenseiten und Landingpages laufen auf Astro, oft unter der Hauptdomain. Katalog, Warenkorb und Kasse bleiben im WordPress-Theme, etwa unter einer Subdomain oder einem Pfad. Zahlungsplugins, Rechtstexte-Plugins und Checkout-Felder arbeiten weiter wie bisher. Die Grenze zwischen beiden Systemen ist ein Link.

Weg B ist der kleinere Eingriff und deshalb mein Ausgangspunkt, wenn Ihr Ziel eine schnellere, besser pflegbare Inhaltsseite ist. Weg A lohnt sich, wenn das Einkaufserlebnis selbst neu gebaut werden soll, zum Beispiel ein Produktkonfigurator, eine Filterlogik, die das Theme nicht hergibt, oder ein gemeinsamer Auftritt von Inhalt und Katalog ohne sichtbaren Systemwechsel.

#Was die Store API liefert

WooCommerce beschreibt die Store API als öffentliche REST-Schnittstelle für kundenseitige Funktionen: Produkte, Warenkorb und Checkout. Sie liegt im Namensraum wc/store/v1 unter /wp-json/ und ist nicht authentifiziert. Sie braucht keinen API-Schlüssel und gibt nur Daten des aktuellen Kunden heraus, keine Einstellungen, keine fremden Bestellungen. Für alles, was der Händler im Hintergrund braucht, verweist WooCommerce auf die authentifizierte WC REST API (Store API, WooCommerce).

Für ein Frontend sind diese Endpunkte die wichtigsten:

Zwei Details aus der Dokumentation des Produkt-Endpunkts prägen die Umsetzung. Preise kommen als ganze Zahl in der kleinsten Währungseinheit, zusammen mit currency_minor_unit, also muss das Frontend sie selbst in Euro mit Komma formatieren. Und die API liefert nur veröffentlichte Produkte. Ein Entwurf ergibt einen 404, was für eine Vorschau-Funktion der Redaktion eigene Arbeit bedeutet (Products API).

#Warenkorb ohne Cookie: Cart-Token und Nonce

Kundensitzungen in WooCommerce laufen über Cookies. Schreibende Anfragen an /cart und alle Anfragen an /checkout brauchen deshalb einen Nonce, den WordPress mit wp_create_nonce( 'wc_store_api' ) erzeugt (Nonce Tokens). Ein Astro- oder Next.js-Frontend auf einer anderen Domain hat diese Sitzung nicht ohne Weiteres.

Für diesen Fall gibt es den Cart-Token. Jede erfolgreiche Antwort auf /cart trägt einen Cart-Token-Header. Das Frontend speichert ihn und schickt ihn bei jeder weiteren Anfrage an Warenkorb und Checkout mit. Mit Cart-Token ist laut WooCommerce kein Nonce nötig (Cart Tokens).

Den Filter woocommerce_store_api_disable_nonce_check, der die Nonce-Prüfung abschaltet, nutze ich nur lokal. WooCommerce schreibt dazu ausdrücklich, dass er nicht in die Produktion gehört.

#Was beim Umzug bricht

#Zahlungsplugins

Die Bestellung geht an POST /wc/store/v1/checkout. Pflicht sind Rechnungsadresse, Lieferadresse und payment_method, dazu optional payment_data für das Zahlungsplugin. Welche Daten ein Plugin dort erwartet, dokumentiert WooCommerce nicht für alle Anbieter. Die Dokumentation verweist an die Autoren der jeweiligen Zahlungsplugins (Checkout API).

Der serverseitige Teil ist oft das kleinere Problem. Der Checkout-Block wandelt eingehende payment_data in $_POST um und ruft die Methode process_payment des Gateways auf. Ein Plugin, das im klassischen Checkout funktioniert, verarbeitet die Zahlung auf diesem Weg häufig weiter. Der clientseitige Teil dagegen, also Kartenfelder, Express-Buttons oder Weiterleitungen zum Anbieter, registriert sich per JavaScript über wc.wcBlocksRegistry im Checkout-Block von WordPress (Payment method integration). In einem eigenen Frontend gibt es dieses Register nicht. Dort baue ich den Teil mit dem SDK des Zahlungsanbieters nach, oder ich leite für die Kasse zurück auf WordPress.

Ein nützlicher Schutz im Checkout-Endpunkt ist expected_total: Das Frontend schickt den Betrag mit, den die Kundin bestätigt hat. Weicht die Berechnung auf dem Server ab, lehnt WooCommerce die Bestellung mit Status 409 ab und liefert den aktualisierten Warenkorb zurück. So bestellt niemand zu einem Preis, den er nicht gesehen hat.

#Erweiterungen, die im Theme rendern

Hängt in Ihrem Shop eine Checkbox, ein Hinweis oder ein Zusatzfeld an einem Hook des Shortcode-Checkouts, wird es eng. WooCommerce führt eine Tabelle, welche dieser Hooks im Checkout-Block noch laufen. woocommerce_review_order_before_submit und woocommerce_checkout_terms_and_conditions sind dort als nicht unterstützt markiert. woocommerce_checkout_fields gilt als teilweise unterstützt, neue Felder kommen über die Additional Checkout Fields API (Hook alternatives). Auch die Validierung ändert sich: Weil der Checkout-Block den Store-API-Ablauf nutzt, läuft woocommerce_after_checkout_validation dort nicht. WooCommerce nennt woocommerce_checkout_validate_order_before_payment als Ersatz (Beispiel aus der WooCommerce-Doku).

Für Weg A ist das ein Frühwarnsystem. Was im Checkout-Block schon nicht funktioniert, funktioniert in einem eigenen Frontend auf derselben API erst recht nicht. Seit WooCommerce 8.3 vom November 2023 sind Warenkorb- und Checkout-Block bei neuen Shops Standard. WooCommerce weist darauf hin, dass inkompatible Erweiterungen Teile der Kasse ausblenden können, ein Zahlungsplugin etwa als Zahlart fehlt (Customizing the Cart and Checkout Pages). Läuft Ihr Shop noch mit dem Shortcode-Checkout, teste ich zuerst auf einer Staging-Kopie, was im Block-Checkout übrig bleibt.

Daten, die eine Erweiterung im neuen Frontend zeigen soll, kommen über ExtendSchema in die Antworten der Store API. WooCommerce beschreibt diesen Weg bewusst als enger als klassische Filter, damit eine Erweiterung die Daten anderer nicht überschreibt (Extending the Store API). Ob ein Plugin das schon tut, sehe ich in der Antwort von /cart und /products auf Staging.

Foto: Janericloebe, Public domain, Wikimedia Commons.

#Preisangaben nach PAngV im neuen Frontend

Rendert Astro oder Next.js die Produktseite, ist das Frontend für jede Preisangabe verantwortlich. Was heute ein Theme oder ein Plugin für deutsches Recht ausgibt, muss ich dort wieder abbilden. Die Preisangabenverordnung verlangt:

• Gesamtpreis nach § 3 PAngV. Wird der Preis aufgegliedert, ist der Gesamtpreis hervorzuheben (§ 3 PAngV).
• Grundpreis nach § 4 PAngV neben dem Gesamtpreis bei Waren nach Gewicht, Volumen, Länge oder Fläche, unmissverständlich, klar erkennbar und gut lesbar, mit Ausnahmen etwa unter 10 Gramm oder 10 Millilitern (§ 4 PAngV).
• Umsatzsteuer und Versandkosten nach § 6 PAngV bei Fernabsatz: der Hinweis, dass die Preise die Umsatzsteuer enthalten, ob Versandkosten anfallen und, soweit vorab berechenbar, in welcher Höhe (§ 6 PAngV).
• Niedrigster Preis der letzten 30 Tage nach § 11 PAngV bei jeder Bekanntgabe einer Preisermäßigung (§ 11 PAngV).

In der Store API stehen Preis, regulärer Preis und Angebotspreis. Grundpreis und 30-Tage-Tiefstpreis sind dort nicht als eigene Felder dokumentiert. Liefert heute ein Plugin diese Werte, prüfe ich, ob es sie über ExtendSchema an die Store API weitergibt. Wenn nicht, lese ich sie über einen eigenen, schmalen Endpunkt aus oder berechne den Grundpreis aus Produktdaten. Den Wortlaut der Hinweise legen Sie oder Ihre Rechtsberatung fest. Ich sorge dafür, dass er auf jeder Produktseite, in Listen und im Warenkorb gleich erscheint.

#Bestellbutton und Widerrufsfunktion

§ 312j BGB regelt drei Stellen im Bestellablauf. Spätestens zu Beginn müssen Lieferbeschränkungen und akzeptierte Zahlungsmittel klar angegeben sein. Unmittelbar vor der Bestellung müssen die Informationen aus Art. 246a § 1 EGBGB hervorgehoben erscheinen. Und der Button muss gut lesbar mit “zahlungspflichtig bestellen” oder einer gleich eindeutigen Formulierung beschriftet sein, sonst kommt der Vertrag nach Absatz 4 nicht zustande (§ 312j BGB). Bei Weg A steht dieser Button in meinem Code und nicht mehr in WooCommerce oder einem Plugin. Die Beschriftung lege ich als feste Zeichenkette an, die in jedem Release mitgetestet wird.

Die elektronische Widerrufsfunktion nach § 356a BGB betrifft Fernabsatzverträge über eine Online-Benutzeroberfläche. Gefordert ist eine Funktion mit der Beschriftung “Vertrag widerrufen” oder gleichbedeutend, während der Widerrufsfrist ständig verfügbar, hervorgehoben und leicht zugänglich. Sie fragt Name, Vertrag und den Kommunikationsweg für die Eingangsbestätigung ab, schließt mit “Widerruf bestätigen” und löst eine Eingangsbestätigung mit Datum und Uhrzeit auf einem dauerhaften Datenträger aus (§ 356a BGB). Die Widerrufsfrist selbst beträgt nach § 355 Abs. 2 BGB 14 Tage (§ 355 BGB).

Bei Weg A wird diese Funktion Teil des neuen Frontends. Den Widerruf ordne ich der Bestellung in WooCommerce zu, und die Bestätigung verschickt das Backend per E-Mail. Bei Weg B bleibt die Funktion dort, wo die Bestellung entsteht, also auf WordPress. Die Inhaltsseite verlinkt dann gut sichtbar auf sie, zum Beispiel im Fußbereich jeder Seite.

#Was das für Händler in Düsseldorf heißt

In Düsseldorf findet mit der EuroShop die nach eigener Angabe weltweit führende Handelsmesse statt (Stand November 2026), zuletzt vom 22. bis 26. Februar 2026, die nächste ist für den 18. bis 22. Februar 2029 angekündigt. Die Schwestermesse für Handelstechnik, die EuroCIS, ist für den 16. bis 18. Februar 2027 in Düsseldorf angesetzt (EuroShop). Wer dort neue Kassen-, Zahlungs- oder Warenwirtschaftsanbindungen sieht, fragt sich als Nächstes, ob der eigene Shop sie aufnehmen kann. Bei Weg A hängt das an der Frage, ob der Anbieter eine Integration für die Store API oder den Checkout-Block hat. Bei Weg B bleibt es eine Frage an das WooCommerce-Plugin wie bisher.

Mehrsprachige Shops mit Deutsch und Englisch behandle ich bei Weg A im Routing des Frontends. Bei Weg B bleibt die Sprachumschaltung des Shops, wo sie ist, und die Inhaltsseite verlinkt auf die passende Sprachversion.

#Checkliste: Inventur vor der Entscheidung

Diese Tabelle können Sie auch ohne mich ausfüllen. Schon drei oder vier Antworten zeigen, ob Ihr Shop eher zu Weg A oder zu Weg B passt.

#Ablauf eines Shop-Projekts mit mir

1. Sie schicken mir die Adresse des Shops, die Liste der aktiven Plugins und Ihr Ziel. Lesezugriff auf eine Staging-Kopie oder einen Export der Plugin-Liste reicht für den Anfang.
2. Ich arbeite die Checkliste oben durch, rufe /wc/store/v1/cart und /products auf der Staging-Kopie auf und mache eine Testbestellung mit jeder Zahlart.
3. Sie bekommen einen schriftlichen Umfang: empfohlener Weg, was bricht, was neu gebaut wird, was offen ist, welche Rechtstexte Ihre Beratung liefern muss.
4. Ich setze auf einer Staging-Umgebung um. Layout und Grafik kommen von Ihnen, Fragen stelle ich schriftlich.
5. Abnahme mit Testbestellungen je Zahlart, einem Testwiderruf und einer Prüfung der Preisangaben auf Produktseite, Liste und Warenkorb.
6. Danach kann ich Updates von WordPress, WooCommerce und Frontend betreuen, wenn Sie das wollen.

Wie die URL-Übernahme beim Wechsel funktioniert, beschreibe ich auf der Seite zur Migration zu Next.js und Astro. Zur Arbeit an WooCommerce selbst steht mehr auf der Seite WooCommerce-Entwickler, zu WordPress als Redaktionssystem hinter einem neuen Frontend auf der Seite zum Headless-CMS-Entwickler. Für Düsseldorf gibt es außerdem eine Seite zu WooCommerce in Düsseldorf, dort zum Verpackungsrecht im Shop.

#Häufige Fragen

#Muss ich WooCommerce aufgeben, wenn die Website auf Astro oder Next.js umzieht?

Nein. WooCommerce kann als Backend für Produkte, Bestellungen, Zahlungen und Versand bestehen bleiben. Das neue Frontend holt Produkte und Warenkorb über die Store API. Alternativ bleibt der ganze Shop auf WordPress, und nur die Inhaltsseiten ziehen um.

#Funktioniert mein Zahlungsplugin in einem Headless-Checkout?

Das prüfe ich pro Plugin. Die Store API nimmt die Zahlung über payment_method und payment_data entgegen, aber welche Daten ein Plugin erwartet, legt das Plugin fest. WooCommerce verweist dafür ausdrücklich an die Plugin-Autoren. Den clientseitigen Teil, etwa ein Kartenformular, baue ich im neuen Frontend nach oder lasse den Checkout auf WordPress.

#Warum zeigt mein bisheriges Checkout-Feld im neuen Frontend nichts an?

Viele Erweiterungen hängen sich an Hooks des Shortcode-Checkouts, etwa woocommerce_review_order_before_submit. Diese Hooks laufen nur, wenn WordPress die Seite rendert. Im Checkout-Block und in einem eigenen Frontend auf Basis der Store API greifen sie nicht. Das Feld muss als Daten über die Store API kommen oder neu gebaut werden.

#Wer ist für den Bestellbutton nach § 312j BGB verantwortlich, wenn das Frontend neu ist?

Sie als Händler. In einem eigenen Frontend schreibe ich die Beschriftung selbst in den Code, zum Beispiel “zahlungspflichtig bestellen”. Sie stammt dann nicht mehr aus WooCommerce oder einem Rechtstexte-Plugin. Nach § 312j Abs. 4 BGB kommt der Vertrag ohne korrekte Beschriftung nicht zustande.

#Wo liegt die Widerrufsfunktion nach § 356a BGB bei einem Headless-Shop?

Auf der Oberfläche, über die der Vertrag geschlossen wurde, also im neuen Frontend. Sie muss mit “Vertrag widerrufen” oder gleich eindeutig beschriftet, während der Widerrufsfrist ständig verfügbar und leicht zugänglich sein. Die Eingangsbestätigung muss auf einem dauerhaften Datenträger ankommen, etwa per E-Mail.

#Was ist der geringste Eingriff, wenn ich nur eine schnellere Inhaltsseite will?

Shop, Warenkorb und Kasse bleiben auf WordPress, Blog, Ratgeber und Leistungsseiten ziehen auf Astro. Die Inhaltsseite verlinkt auf Produktseiten oder auf Checkout-Links von WooCommerce, die Produkte direkt in den Warenkorb legen. Zahlungsplugins und Rechtstexte im Checkout bleiben unverändert.

#Schreiben Sie mir zu Ihrem Shop

Schicken Sie mir über die Kontaktseite die Adresse Ihres Shops, die WooCommerce-Version, die Liste der aktiven Plugins mit den Zahlarten, Ihr Ziel für das neue Frontend und einen Wunschtermin. Haben Sie die Checkliste oben schon ausgefüllt, legen Sie sie bei. Ich antworte schriftlich an Werktagen. Die erste schriftliche Einschätzung, welcher Weg zu Ihrem Shop passt und was dabei bricht, ist kostenlos.