Shopify App entwickeln: Schritt für Schritt mit CLI und React Router

Du möchtest eine eigene Shopify App entwickeln und suchst einen Einstieg, der zu den aktuellen Shopify-Standards passt? Für die meisten Apps mit eigener Benutzeroberfläche empfiehlt Shopify heute den Weg über die Shopify CLI und das offizielle React-Router-Template. Das Template nimmt dir wichtige Grundlagen wie die Shopify-Authentifizierung ab und bringt deine Anwendung direkt in den Shopify-Admin.

Diese Anleitung führt dich vom ersten Funktionsplan bis zum lokalen Test. Sie orientiert sich an der offiziellen Shopify-Anleitung zum Scaffolden einer App und der Dokumentation zur Shopify CLI. Die Shopify-Dokumentation ist die maßgebliche Referenz: Prüfe dort vor einem neuen Projekt die aktuelle CLI-Version und verfügbare Optionen.

Vor dem Start: Welche Art App brauchst du?

Lege zuerst fest, wo die App eingesetzt wird und welche Daten sie benötigt. Eine im App Store angebotene App für viele Shops hat andere Anforderungen als eine interne Integration für einen einzelnen Betrieb.

• App mit eigener Oberfläche im Admin: Das React-Router-Template ist laut Shopify für die meisten Apps der empfohlene Einstieg.
• Einfache Integration ohne eingebettete Oberfläche: Wenn du nur Zugangsdaten für eine Verbindung zu einem bestehenden System brauchst, kann eine App aus dem Dev Dashboard geeigneter sein.
• Kleine Erweiterung ohne eigenen Server: Für manche individuellen Anwendungsfälle kommt eine Extension-only-App infrage.

Schreibe vor dem Programmieren drei Dinge auf: den konkreten Arbeitsablauf des Händlers, die benötigten Shopify-Daten und die kleinstmöglichen Berechtigungen. So vermeidest du, dass die App unnötig viele Daten anfordert oder am eigentlichen Problem vorbeientwickelt wird.

Schritt 1: Entwicklungsumgebung und Testshop vorbereiten

Du benötigst Zugriff auf das Shopify Dev Dashboard, eine aktuelle Shopify CLI und einen Development Store. Der Testshop ist dein sicherer Ort für Installationen und Änderungen, bevor du die App in einem echten Shop einsetzt.

Installiere die CLI nach der aktuellen Shopify-Anleitung. Mit einer globalen npm-Installation sieht der Einstieg beispielsweise so aus:

npm install -g @shopify/cli@latest

Das genaue Installationsverfahren und die Systemvoraussetzungen können sich ändern. Verwende deshalb die offizielle Installationsdokumentation als Quelle, statt eine veraltete Version aus einem älteren Tutorial zu übernehmen.

Schritt 2: Offizielles App-Grundgerüst erstellen

Öffne im Terminal den Ordner, in dem dein Projekt liegen soll, und starte den App-Assistenten:

shopify app init

Melde dich an und wähle im Assistenten Build a React Router app. Wenn du dazu aufgefordert wirst, legst du eine neue App in deiner Shopify-Organisation an und vergibst einen Projektnamen. Die CLI verbindet den lokalen Code mit dem App-Eintrag und richtet die Abhängigkeiten ein.

Das ist mehr als ein leeres React-Projekt: Das offizielle Template bringt Shopify-spezifische Projektstruktur und Authentifizierungsbausteine mit. Baue auf dieser Grundlage auf, anstatt OAuth, Weiterleitungen und den eingebetteten Einstieg eigenständig nachzubauen.

Schritt 3: App lokal mit Shopify verbinden

Wechsle in das Verzeichnis, das beim Erstellen angelegt wurde:

cd meine-shopify-app

Starte anschließend die Entwicklungsumgebung:

shopify app dev

Die CLI startet die App und stellt über einen HTTPS-Tunnel eine Verbindung zum Development Store her. Folge den angezeigten Schritten, um den Testshop auszuwählen und die App zu installieren. Eine lokale Adresse allein reicht für eine eingebettete Shopify-App nicht: Shopify muss deine Entwicklungsumgebung über die bereitgestellte öffentliche HTTPS-Adresse erreichen können.

Schritt 4: Eine kleine Funktion als vertikalen Durchstich bauen

Implementiere zuerst genau einen vollständigen Ablauf, zum Beispiel eine Seite, die den Shopnamen anzeigt. So prüfst du früh, ob Installation, Authentifizierung, Admin-Oberfläche und API-Zugriff zusammenspielen.

Im offiziellen React-Router-Muster authentifiziert der Server eine Admin-Anfrage über die Hilfsfunktion des App-Templates. Eine Route kann dann beispielsweise so aussehen:

import { authenticate } from "../shopify.server";

export async function loader({ request }: { request: Request }) {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `query { shop { name } }`,
  );

  return response;
}

Die tatsächliche Signatur und der Rückgabewert hängen von der generierten Template-Version ab. Übernimm den Code daher nicht blind: Vergleiche ihn mit der Datei und den Beispielen in deinem frisch erzeugten Projekt sowie der React-Router-App-Dokumentation.

Schritt 5: Installation und Fehlerfälle testen

Teste im Development Store mindestens den vollständigen Installations- und Startablauf. Öffne die App aus dem Shopify-Admin, prüfe die Rückkehr nach einer erneuten Installation und kontrolliere, dass die angeforderte Berechtigung für den vorgesehenen Ablauf genügt. Protokolliere Serverfehler, aber schreibe niemals Zugriffstoken oder Geheimnisse in Logs.

Wenn eine App im Shopify-Admin laufen soll, sollte der primäre Arbeitsablauf dort erreichbar sein. Die Shopify-Empfehlungen zur Integration mit dem Admin erklären, wann eine externe Oberfläche zusätzlich sinnvoll sein kann.

Vor der nächsten Funktion

Bevor du weitere Features ergänzt, beantworte diese Fragen:

1. Welches konkrete Händlerproblem löst der nächste Schritt?
2. Welche Shopify-API und welche minimalen Scopes braucht er?
3. Muss die Verarbeitung sofort stattfinden oder eignet sich ein Webhook beziehungsweise Hintergrundjob?
4. Wie kann der Ablauf im Development Store reproduzierbar getestet werden?
5. Was passiert bei fehlenden Berechtigungen, API-Fehlern oder einer Deinstallation?

Wer diese Punkte früh klärt und mit dem offiziellen Shopify-Template startet, erhält ein wartbares Fundament statt einer App, deren Authentifizierung und Admin-Einbindung später neu gebaut werden müssen.

Offizielle Shopify-Quellen

• Shopify CLI für Apps
• App scaffolden: Development Store und React Router
• Shopify App im Detail entwickeln
• React-Router-App-Paket
• Apps in der Shopify-Admin-Oberfläche integrieren

Shopify aktualisiert CLI und Dokumentation regelmäßig; prüfe die verlinkten Originalquellen vor dem Start eines neuen Projekts.