In diesem Leitfaden teilen wir unsere Erfahrungen aus erster Hand, die wir bei Nodus Works beim Erstellen einer vollflächigen UI-Extension für die neuen Shopify-Kundenkonten gesammelt haben. Wir beschreiben den Weg von der Einrichtung bis zum Live-Gang, gehen auf echte Fehler ein, auf die wir dabei gestoßen sind, und zeigen mit Codebeispielen, wie wir diese gelöst haben. Dieser Leitfaden basiert auf unseren direkten Erfahrungen bei der Implementierung einer vollflächigen Kundenkonto-Extension in einer Produktionsumgebung.
Warum ist eine vollflächige UI-Extension erforderlich?
Shopifys neue Kundenkonten bieten vorgefertigte Seiten wie Bestellungen, Profil und Adressen. Für Szenarien wie Treueprogramme, Wunschlisten, Abonnementverwaltungen oder ein eigenständiges „Impact-Dashboard“ reichen diese Standardblöcke jedoch nicht aus. Shopify löst diesen Bedarf mit vollflächigen UI-Extensions, die das Ziel (Target) customer-account.page.render verwenden.
Was sind UI-Extensions und Targets?
Eine UI-Extension ist ein Modul, das Code an bestimmten Stellen der Kundenkonto-Oberfläche injiziert; das Target bestimmt, wo dieser Code platziert wird. Während Block-Targets in bestehende Seiten eingefügt werden, erstellt ein vollflächiges Target eine komplett neue Route. Die folgende Tabelle fasst die Unterschiede zwischen den beiden Target-Typen zusammen.
Wichtiger Hinweis: Ein vollflächiges Target kann nicht zusammen mit anderen Targets innerhalb derselben Extension existieren. Sie müssen eine separate Extension für Ihre Vollbildseite erstellen; der Versuch, ein vollflächiges Target in eine bestehende Block-Extension zu integrieren, führt zu einem Konfigurationsfehler.
Schritt-für-Schritt-Einrichtung: Wie erstellt man eine Extension?
Für die Erstellung einer Extension sind zwei Dateien erforderlich: die Konfigurationsdatei und die Seitenkomponente. Ein vollflächiges Target muss innerhalb einer eigenständigen Extension definiert werden.
api_version = "2026-04"
[[extensions]]
name = "Impact Page"
handle = "impact-page"
type = "ui_extension"
[[extensions.targeting]]
module = "./src/FullPage.jsx"
target = "customer-account.page.render"
Anschließend wird eine minimale Seitenkomponente definiert. Der kritische Punkt ist: Es ist zwingend erforderlich, die von Shopify bereitgestellten Webkomponenten (wie s-page, s-section, s-grid) zu verwenden und kein Standard-HTML. Der Host lehnt die gesamte Seite ab, wenn er einen unzulässigen Knoten erkennt.
import "@shopify/ui-extensions/preact";
import { render } from "preact";
export default () => {
render(<MyPage />, document.body);
};
function MyPage() {
return (
<s-page heading="Impact">
<s-section>
<s-text>Loading…</s-text>
</s-section>
</s-page>
);
}
Wie wird die Extension bereitgestellt (Deploy)?
Der Extension-Code wird nicht auf Ihrem eigenen Server gehostet; wenn Sie den Befehl shopify app deploy ausführen, kompiliert Shopify den Code und stellt ihn auf seiner eigenen Infrastruktur bereit.
shopify app deploy
Der Befehl fragt, ob eine neue Version veröffentlicht werden soll; sobald Sie dies bestätigen, geht die Extension live. Bis hierhin verläuft alles gemäß der Dokumentation; der eigentliche Lerneffekt beginnt jedoch nach dem Deployment.
Wie erstellt man eine neue Seite unter „Mein Konto“? (Aktivierungsschritte)
Das Deployment einer vollflächigen Extension macht die Seite im Menü „Mein Konto“ (Customer Accounts) noch nicht sichtbar oder funktionsfähig; damit die Seite aktiv wird, müssen Sie sie separat über den Editor für Kundenkonten hinzufügen. Dieser Schritt ist ein eigenständiger Prozess, der völlig unabhängig vom Deployment-Vorgang ist.
- Gehen Sie im Admin-Bereich zu Settings (Einstellungen) → Customer accounts (Kundenkonten).
- Klicken Sie oben rechts auf Customize; es öffnet sich ein Editor, der dem Theme-Editor ähnelt.
- Fügen Sie im Editor über den Bereich zum Hinzufügen von Apps/Extensions die entsprechende vollflächige Extension hinzu.
- Der Editor leitet Sie automatisch zur Menü-Konfiguration weiter; bestätigen Sie dies.
- Save / Publish veröffentlichen.
Zu vermeidendes Risiko: Es reicht nicht aus, die Extension nur bereitzustellen (deploy) und manuell einen Link im Navigationsmenü hinzuzufügen. Die Seite wird weiterhin den Fehler "There's a problem loading this page" anzeigen, solange sie nicht über den Kundenkonto-Editor hinzugefügt und aktiviert wurde; diese beiden Schritte (Deployment und Aktivierung) sind voneinander unabhängig.
Warum tritt der Fehler "There's a Problem Loading This Page" auf?
Dieser Fehler tritt auf, wenn der oben genannte Aktivierungsschritt übersprungen wird, selbst wenn die Extension erfolgreich bereitgestellt und der Link im Navigationsmenü hinzugefügt wurde; dies ist die zeitaufwendigste Fehlerquelle. In der Browser-Konsole finden sich keine JavaScript-Fehler der Extension, sondern lediglich irrelevante Warnungen zu Analytics und CSP. Dies deutet darauf hin, dass das Problem nicht in der Rendering-Phase liegt, sondern bei der Auflösung (Resolution) der Seite.
Weitere häufige Fehler und Fehldiagnosen
Neben Deployment und Aktivierung gibt es vier weitere Situationen, die bei der Diagnose Zeit kosten. Die folgende Tabelle fasst die tatsächliche Ursache und den korrekten Diagnoseansatz für jeden Fall zusammen.
Der schnellste Weg zur korrekten Diagnose ist das Herunterbrechen auf eine minimale "Hello World"-Seite, um zu beweisen, dass das Problem nicht im Code, sondern in der Aktivierung liegt.
Self-Service-Content-Management für Shop-Betreiber
Nachdem die Seite funktioniert, ist der nächste logische Schritt, die Texte in die Extension-Einstellungen zu verschieben, damit der Shop-Betreiber sie ohne Entwickler bearbeiten kann. Die Felder werden in der Konfigurationsdatei definiert.
[extensions.settings]
[[extensions.settings.fields]]
key = "heading"
type = "single_line_text_field"
name = "Seitentitel"
[[extensions.settings.fields]]
key = "intro"
type = "multi_line_text_field"
name = "Einleitungstext"
Auf der Code-Seite werden diese Werte über ein Signal ausgelesen und in Echtzeit aktualisiert; ist ein Feld leer, greift der im Code definierte Standardwert.
const settings = globalThis.shopify?.settings?.current ?? {};
const heading = settings.heading?.trim() || "Standardüberschrift";
Dank dieser Struktur können tägliche Textänderungen per Self-Service über den Editor vorgenommen werden; nur für strukturelle Änderungen ist ein neues Deployment erforderlich.
Architektur: Ist ein separater Backend-Server erforderlich?
Nein, für Full-Page-UI-Extensions sind kein separates Backend und kein Hosting erforderlich. Sobald Sie das Deployment durchführen, kompiliert Shopify den Code und stellt ihn über das eigene CDN bereit; die Seite läuft innerhalb des Kundenkonto-Erlebnisses und fügt sich nahtlos in das Branding des Shops ein. Die Wartungskosten sind im Vergleich zu einem herkömmlichen Anwendungsserver deutlich geringer, da keine Serverkapazitäten geplant, aktualisiert oder überwacht werden müssen.
Schnell-Checkliste
- Erstellen Sie eine separate Extension für das Vollseiten-Ziel.
- Verwenden Sie ausschließlich offizielle Web-Komponenten; nutzen Sie kein Standard-HTML.
- Veröffentlichen Sie die neue Version mit shopify app deploy.
- Die Seite muss zwingend über den Editor für Kundenkonten hinzugefügt und aktiviert werden; ein bloßer Link im Menü reicht nicht aus.
- Schreiben Sie den Menü-Link nicht manuell, sondern wählen Sie ihn über den Editor bzw. die Auswahlfunktion als App-Seite aus.
- Unterscheiden Sie in der Konsole zwischen Analytics-/CSP-Rauschen und tatsächlichen Fehlern.
- Überlassen Sie die Inhaltsverwaltung dem Shop-Betreiber, indem Sie Texte in die Einstellungsbereiche verschieben.
Solche individuellen UI-Extension-Entwicklungen gehen über die Standard-Theme-Anpassung hinaus und stellen eine Integration auf Code-Ebene dar; Unser Service für Shopify-Integrationslösungen verwaltet plattformweite Anpassungen wie Kundenkonten ganzheitlich, einschließlich aller Deployment- und Aktivierungsschritte. Für die schnelle Diagnose von Fehlern wie "problem loading page" nach der Veröffentlichung steht unser technischer Support- und Wartungsservice für Shopify mit umfassender Praxiserfahrung bereit.
Häufig gestellte Fragen
Was bedeutet die Fehlermeldung "There's a problem loading this page"?
Dieser Fehler tritt auf, wenn die Seite zwar erfolgreich bereitgestellt (deployed), aber nicht über den Editor für Kundenkonten hinzugefügt und aktiviert wurde. Deployment und Aktivierung sind zwei unabhängige Schritte; der erste allein reicht nicht aus.
Was ist der Unterschied zwischen einer Vollseiten-Extension und einer Block-Extension?
Eine Block-Extension ist eine kleine Komponente, die in eine bestehende Seite (Bestellungen, Profil etc.) eingefügt wird und innerhalb derselben Extension mit anderen Zielen koexistieren kann. Eine Vollseiten-Extension hingegen erstellt mit dem Ziel customer-account.page.render eine eigenständige neue Route und erfordert eine separate Extension.
Muss ich für eine Vollseiten-Extension einen separaten Backend-Server einrichten?
Nein. Shopify kompiliert und hostet den bereitgestellten Code über sein eigenes CDN. Ein separates Hosting oder eine Serververwaltung ist nicht erforderlich, wodurch der Wartungsaufwand im Vergleich zu einem herkömmlichen Anwendungsserver deutlich geringer ist.
Wie füge ich den Menü-Link hinzu?
Geben Sie Links nicht manuell ein; eine manuell zum Navigationsmenü hinzugefügte /pages/<id>-Adresse führt zu einem ungültigen Link. Die korrekte Adresse wird automatisch vom App-Seitenauswähler im Editor für Kundenkonten generiert.
Kann ich Seitentexte ändern, ohne ein Deployment durchzuführen?
Ja, wenn die Texte in Einstellungsfelder wie single_line_text_field oder multi_line_text_field verschoben wurden, kann der Shop-Inhaber diese direkt über den Editor anpassen. Nur strukturelle Änderungen (Komponenten, Logik) erfordern ein neues Deployment.
Fazit
Obwohl das Hinzufügen einer vollflächigen Erfahrung zu den neuen Shopify-Kundenkonten technisch einfach erscheint, nimmt in der Praxis das Problem „Ich habe es deployed, aber es lädt nicht“ die meiste Zeit in Anspruch. Die wichtigste Lektion lautet: Das Veröffentlichen einer Full-Page-Extension und deren Aktivierung im Editor für Kundenkonten sind zwei separate Schritte. Sobald Sie dies verinnerlicht haben, werden die restlichen Aspekte – wie die Auswahl der Komponenten, der Deployment-Prozess und die Editierbarkeit von Texten – zu einem klaren und wiederholbaren Ablauf. Shopify aktualisiert gelegentlich die Benutzeroberfläche und Versionsdetails; daher empfehlen wir, diesen Leitfaden stets in Verbindung mit der offiziellen Dokumentation zu verwenden.
Wenn Sie eine benutzerdefinierte Seite für Kundenkonten in Ihrem eigenen Shopify-Shop entwickeln oder ein ähnliches Aktivierungsproblem bei einer bestehenden Extension lösen möchten, können Sie sich bezüglich unserer Integrationslösungen mit unserem Team in Verbindung setzen.
