Unabhängige Analyse der öffentlichen Entwicklerdokumentation von Shopify. Identity Forge ist nicht mit Shopify verbunden und wird nicht von Shopify unterstützt. Shopify und Polaris sind Marken ihres jeweiligen Eigentümers. Der Migrationsstatus und die Paketdetails entsprechen der Dokumentation zum Zeitpunkt der Erstellung – bitte vor der Planung einer Migration auf shopify.dev verifizieren.
Die Deprecation, ungeschönt formuliert
Die Dokumentationsseite von Polaris React trägt nun in der eigenen Überschrift ein Deprecation-Label, zusammen mit einem Banner, das auf Polaris Web Components verweist. Wenn Sie nach Polaris suchen und bei der Dokumentation der React-Komponenten landen, lesen Sie die vorherige Generation.
Die React-Library ist nicht verschwunden – die Dokumentation zu Foundations, Komponenten, Tokens und Icons wird weiterhin veröffentlicht –, aber die Richtung ist eindeutig. Neue Shopify-Apps erhalten Web Components, die von der Shopify CLI während des Scaffoldings integriert werden.
Wie Polaris Web Components bereitgestellt werden
Dies ist der Teil, der am stärksten von dem abweicht, was Nutzer von Designsystemen gewohnt sind: ein einziger Script-Tag:
<head>
<meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
<script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script>
</head>Das ist die gesamte Installation. In einer Remix-App wird derselbe Tag im Root-Dokument platziert:
// app/root.tsx
export default function App() {
return (
<html>
<head>
<meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
<script src="https://cdn.shopify.com/shopifycloud/polaris.js" />
</head>
</html>
)
}TypeScript-Nutzer fügen ein ergänzendes Paket, @shopify/polaris-types, via npm hinzu. Die Shopify-Dokumentation ist präzise darin, wie diese synchron gehalten werden: Da das CDN immer die neuesten Komponenten ausliefert, sollte @shopify/polaris-types@latest in der package.json spezifiziert werden, damit die Typen mitziehen.
Lesen Sie den letzten Satz zweimal, falls Sie eine Meinung zu Lockfiles haben. Die Runtime-Komponenten werden nicht von Ihnen versioniert – das CDN liefert das aktuelle Release aus – und der empfohlene Weg, die Typen korrekt zu halten, ist die Abhängigkeit von @latest. Dies ist eine bewusste Umkehrung der normalen Dependency-Hygiene; ob dies akzeptabel ist, hängt vollständig vom Deployment-Kontext ab.
Warum der Vendor die Kontrolle über die Version will
Der erklärte Zweck von Polaris im App-Kontext ist, dass sich Ihre App im Shopify-Admin nativ anfühlen und aussehen soll. Das ist eine grundlegend andere Anforderung als „Ihre App sollte konsistent sein“, und es erklärt das Bereitstellungsmodell vollständig.
Wenn sich die visuelle Sprache des Shopify-Admins ändert – eine Überarbeitung der Abstände, eine neue Typografie-Skala, ein Dark Mode –, sieht eine App, die an eine Komponentenversion von vor achtzehn Monaten gepinnt ist, plötzlich falsch aus. Nicht defekt. Aber falsch, in einer Weise, die ein Händler als minderwertige App wahrnimmt. Multipliziert man dies mit einem App-Marketplace, wird die Oberfläche der Plattform sichtbar inkonsistent, ohne dass ein einzelner Entwickler daran schuld ist.
Die Bereitstellung von Komponenten über ein CDN verlagert dieses Risiko von tausenden App-Entwicklern, die keinen Anreiz haben, eine funktionierende Abhängigkeit zu aktualisieren, auf ein einziges Plattform-Team, das dies tut. Es ist derselbe Instinkt, der auch hinter dem Stripe App UI Toolkit steckt, das willkürliches CSS ablehnt: Wenn Ihre UI auf der Oberfläche eines anderen gerendert wird, übernimmt dieser die Styling-Entscheidungen zurück.
| npm-Paket | CDN-Script | |
|---|---|---|
| Wer kontrolliert die Version | Sie, via Lockfile | Der Vendor |
| Breaking Change | Tritt ein, wenn Sie es entscheiden. Tritt eventuell nie ein | Tritt ein, sobald der Vendor es ausliefert |
| Plattformkonsistenz | Nimmt mit der Zeit ab, wenn Apps veralten | Automatisch gewartet |
| Offline / Air-gapped | Funktioniert | Funktioniert nicht |
| Bundle-Größe | Selbst optimierbar, Tree-shakeable | Überhaupt nicht im Bundle; separate Anfrage |
| Genau dann, wenn | Die eigene App die Oberfläche ist | Die App eines Dritten die Oberfläche ist |
Die unterste Zeile enthält die gesamte Entscheidung. Dies ist keine allgemeine Empfehlung, das eigene Designsystem über ein CDN bereitzustellen – bei einem Produkt, bei dem man die Oberfläche kontrolliert, bringt der Verzicht auf die Versionskontrolle keinen Vorteil, kostet jedoch reproduzierbare Builds. Es ist die richtige Antwort auf eine spezifische strukturelle Frage darüber, wer für das Aussehen der Seite verantwortlich ist.
Warum Web Components statt React
Das CDN-Modell erklärt sich von selbst, sobald man das Ziel der Plattformkonsistenz akzeptiert, aber es erzwingt quasi auch die technologische Wahl. Man kann keine React-Komponenten über einen Script-Tag in eine App ausliefern, die möglicherweise mit Remix, reinem HTML, Vue oder etwas gebaut wurde, das zum Zeitpunkt der Entscheidung noch gar nicht existierte. Custom Elements sind das einzige weit verbreitete Format, das unabhängig von der umschließenden Umgebung identisch gerendert wird.
In der Dokumentation von Shopify wird darauf hingewiesen, dass der Script-Tag in jedem Framework hinzugefügt werden kann. Dieser Satz ist sehr aussagekräftig: Er drückt den gesamten Grund für die Migration als eine funktionale Fähigkeit aus.
Es ist wichtig, die Kosten zu benennen, denn Web Components sind nicht kostenlos. Man verzichtet auf die Ergonomie von React – typisierte Props, die zur Build-Zeit statt zur Laufzeit geprüft werden, vertraute Composition-Patterns, das Ökosystem aus React-spezifischen Tools – im Austausch für Framework-Unabhängigkeit. Das Paket @shopify/polaris-types existiert genau deshalb, um den ersten dieser Punkte zurückzugewinnen. Ob dieser Tausch sinnvoll ist, hängt davon ab, welchen Wert Framework-Unabhängigkeit für Sie hat; für eine Plattform, die einen App-Marketplace betreibt, ist dieser Wert enorm.
Was Polaris außer Komponenten noch ist
Der Wechsel der Komponenten-Bibliothek verschleiert die Tatsache, dass der Großteil des übertragbaren Wertes von Polaris gar nicht in den Komponenten liegt. Die Dokumentationsseite veröffentlicht vier Dinge, und drei davon überstehen jede Implementierungsänderung:
| Was es ist | Außerhalb von Shopify nützlich? | |
|---|---|---|
| Foundations | Design-Richtlinien für die Erstellung hochwertiger Admin-Erlebnisse | Ja. Admin-UX-Richtlinien sind Admin-UX-Richtlinien |
| Tokens | Codierte Namen, die Design-Entscheidungen repräsentieren – Farbe, Abstände, Typografie | Als Modell ja. Als Werte nur, wenn man wie Shopify aussehen möchte |
| Icons | Über 400 Icons mit Fokus auf Commerce und Unternehmertum | Ja, wenn man Commerce-Software entwickelt. Lizenz prüfen |
| Komponenten | Die Implementierung, jetzt als Web Components | Nein. Sie wurden spezifisch für den Shopify-Admin entwickelt |
Das Icon-Set wird oft unterschätzt. Vierhundert für den Commerce gezeichnete Icons – Zustände der Auftragsabwicklung, Rabatte, Inventar, Versand, Zahlungskonzepte – sind eine enorme Menge an spezialisierter Zeichenarbeit, und generische Icon-Sets sind bei genau diesen Konzepten spürbar schwach. Wenn Sie etwas im Bereich Commerce entwickeln, ist dies eine Stunde Ihrer Zeit und ein Blick in die Lizenzbedingungen wert.
Die Tokens lohnt es sich als Namensübung zu studieren, selbst wenn die Werte für Sie nutzlos sind. Die Beschreibung von Shopify – codierte Namen, die Design-Entscheidungen repräsentieren – ist die korrekte Definition, und genau hier scheitern die meisten Teams, wenn sie einen Token blue-500 nennen, anstatt die Rolle zu benennen, die er spielt.
Das Muster über drei Systeme hinweg
Polaris ist eines von drei großen Enterprise-Designsystemen, die in etwa demselben Zeitraum eine strukturelle Änderung vorgenommen haben. Jedes setzt unterschiedlich auf dieselbe Prämisse: Dass der Code, der ein Designsystem konsumiert, zunehmend nicht mehr von einem Menschen geschrieben wird, der die Dokumentation liest.
| Was sich geändert hat | Die zugrunde liegende Wette | |
|---|---|---|
| Shopify Polaris | React veraltet; framework-agnostische Web Components via CDN | Das Bereitstellungsformat darf keine Annahmen darüber treffen, was die Seite generiert hat |
| IBM Carbon | Ein MCP-Server, der Dokumentationen und Code-Beispiele für Agenten bereitstellt | Agenten sollten das System abrufen, anstatt es aus dem Gedächtnis zu reproduzieren |
| Salesforce Lightning (SLDS 2) | CSS-Architektur entkoppelt vom visuellen Stil; ein Linter, der das Markup gegen die Regeln validiert | Das System muss ausreichend themebar für generierte UIs sein, und Verstöße müssen mechanisch erkannt werden |
Die Version von Polaris ist die am wenigsten diskutierte und wohl die folgenreichste für alle, die auf einer Plattform aufbauen. Wenn ein AI-Agent eine Shopify-App erstellt, muss er nicht wissen, welches Framework der Entwickler gewählt hat, da die Komponenten in jedem Fall dieselben Custom Elements sind. Framework-agnostische Bereitstellung ist agent-agnostische Bereitstellung, unabhängig davon, ob dies die ursprüngliche Motivation war.
Was dies nicht löst
Eine Komponentenbibliothek – via CDN bereitgestellt, framework-agnostisch, immer aktuell – teilt einem Agenten mit, welche Komponenten existieren und wie sie aufzurufen sind. Sie sagt jedoch nichts darüber aus, wie das Produkt aussehen soll, denn im Fall einer Shopify-App ist die Antwort fix: Sie soll wie die Shopify-Administration aussehen.
Außerhalb dieses Falls bleibt die Frage offen, und nichts in einer Komponentenbibliothek beantwortet sie. Wir haben 299 DESIGN.md-Dateien analysiert, die Agenten genau diese Antwort geben sollten. 86 % listeten Farben als reine Hex-Werte ohne zugewiesene Rolle auf, 76 % nannten keine Verbote, 57 % definierten keine Motive und 54 % verließen sich auf vage Adjektive – „clean“ in 39 %, „modern“ in 36 %. Ein Modell, das diese Datei liest, hat eine Palette, aber kein Design.
Identity Forge Design-Kits beantworten die andere Hälfte: semantische Farbrollen für Light- und Dark-Mode, Typografie- und Spacing-Skalen, Motive sowie explizite Do's und Don'ts, serialisiert in einer DESIGN.md, die mit jeder Komponentenbibliothek funktioniert. Kits durchsuchen oder erfahren Sie, was eine DESIGN.md-Datei ist.
Praktische Anleitung
- Aktuell eine Shopify-App erstellen? Verwenden Sie Polaris Web Components. Nutzen Sie das Scaffolding mit dem Shopify CLI, dann ist alles vorkonfiguriert; fügen Sie
@shopify/polaris-types@latesthinzu, wenn Sie TypeScript verwenden. - Eine Polaris React-App warten? Diese funktioniert weiterhin, basiert jedoch auf einer veralteten Implementierung. Lesen Sie die aktuellen Migrationsrichtlinien, bevor Sie weitere größere Änderungen an dieser Codebasis planen.
- Etwas außerhalb von Shopify bauen? Übernehmen Sie keine Polaris-Komponenten. Schauen Sie sich jedoch die Foundations und das Commerce-Icon-Set an und nutzen Sie die Benennung der Design-Tokens als Referenzbeispiel.
- Ein eigenes Designsystem warten? Die übertragbare Frage ist nicht React versus Web Components. Es geht darum, ob Sie oder Ihre Konsumenten die Version kontrollieren sollten – und das ergibt sich daraus, wer für das visuelle Ergebnis verantwortlich ist.
Ist Polaris React veraltet?
Ja. Die Dokumentationsseite von Polaris React enthält einen Deprecation-Hinweis und verweist auf Polaris Web Components. Bestehende React-Apps funktionieren weiterhin, aber für die Entwicklung neuer Shopify-Apps werden die Web Components verwendet, die vom Shopify CLI beim Scaffolding automatisch hinzugefügt werden.
Wie installiere ich Polaris Web Components?
Sie werden nicht über npm installiert. Fügen Sie im Head Ihres Dokuments ein Script-Tag ein, das auf https://cdn.shopify.com/shopifycloud/polaris.js verweist, zusammen mit dem shopify-api-key Meta-Tag. Das Shopify CLI erledigt dies automatisch beim Erstellen einer App. TypeScript-Nutzer fügen @shopify/polaris-types via npm für die Typdefinitionen hinzu.
Warum stellt Shopify Komponenten über ein CDN statt über npm bereit?
Damit Apps visuell nativ in der Shopify-Administration bleiben, während diese sich ändert. Eine fixierte npm-Abhängigkeit würde bedeuten, dass eine App in einer veralteten visuellen Sprache verharrt, während die Umgebung weiterentwickelt wurde, was auf Händler wie eine App minderer Qualität wirkt. Die Verlagerung der Versionskontrolle auf die Plattform löst dieses Problem für den gesamten Marketplace gleichzeitig.
Kann ich Polaris außerhalb einer Shopify-App verwenden?
Die Komponenten sind für die Shopify-Administration entwickelt worden und für andere Zwecke die falsche Wahl – sie würden Ihr Produkt wie Shopify aussehen lassen. Die Dokumentation der Foundations, der Ansatz zur Benennung der Design-Tokens und die über 400 Commerce-Icons sind außerhalb von Shopify tatsächlich nützlich; prüfen Sie jedoch die Lizenzbedingungen, bevor Sie die Icons verwenden.
Was sind Polaris-Tokens?
Codierte Namen, die Designentscheidungen für Farben, Spacing, Typografie und mehr repräsentieren. Der Benennungsansatz ist der übertragbare Teil: Ein Token sollte nach der Entscheidung benannt werden, die es kodiert, und nicht nach dem Wert, den es enthält – das ist der Unterschied zwischen einem Token-System und einer Liste von Variablen.