Vue mit Magento GraphQL verbinden: Produkte, Preise und Lagerbestand laden

1. Warum Vue mit Magento GraphQL mehr braucht als fetch

Wer Vue mit Magento GraphQL verbindet, könnte theoretisch mit einem einzigen fetch Aufruf pro Query beginnen, und für ein einzelnes Prototyp-Feature reicht das auch aus. In einer produktiven Storefront mit Dutzenden Komponenten, die Produkte, Kategorien, Preise und Lagerbestand aus demselben Schema lesen, wird dieser naive Ansatz jedoch schnell zum Wartungsproblem: Feldnamen wiederholen sich in jeder Query, Fehlerbehandlung ist inkonsistent, und niemand hat einen zentralen Überblick, welche Felder überhaupt genutzt werden.

Der zentrale Unterschied zwischen einer soliden und einer fragilen Vue Magento GraphQL Integration liegt in drei Bausteinen: einem konsistenten Client für alle Anfragen, wiederverwendbaren Fragmenten für wiederkehrende Feldgruppen, und einer einheitlichen Strategie für Fehler und Caching. Ohne diese drei Bausteine funktioniert die Integration zunächst, wird aber bei jeder Erweiterung langsamer zu pflegen.

Die folgenden Abschnitte zeigen, wie Vue mit Magento GraphQL so verbunden wird, dass die Integration auch nach einem Magento Upgrade oder einer Schema-Erweiterung stabil bleibt, inklusive konkreter Beispiele für Fragmente, Fehlerbehandlung und Store-Kontext.

2. Client-Wahl: Apollo, urql oder schlanker Fetch-Wrapper

Für Vue mit Magento GraphQL stehen grob drei Optionen zur Wahl: ein vollständiger Apollo Client mit Normalized Cache und umfangreichem Feature-Set, ein leichtgewichtigerer Client wie urql, oder ein selbstgebauter Fetch-Wrapper ohne externe Abhängigkeit. Apollo bringt automatisches Cache-Normalisieren und Optimistic UI Unterstützung mit, kostet aber signifikantes Bundle-Gewicht und eine steilere Lernkurve für das Team.

Für die meisten Magento Storefronts ist ein schlanker Fetch-Wrapper kombiniert mit Nuxts useAsyncData ausreichend, weil Caching und Deduplizierung von Requests bereits auf Framework-Ebene gelöst sind. Normalisiertes Caching, wie es Apollo bietet, lohnt sich vor allem, wenn dieselbe Entity, etwa ein Produkt, an vielen unterschiedlichen Stellen der Seite gleichzeitig angezeigt wird und Änderungen sich überall synchron widerspiegeln sollen.

// graphql/client.ts — minimal typed client for Vue + Magento GraphQL
interface GraphQLResponse<T> {
  data?: T;
  errors?: { message: string; extensions?: { category?: string } }[];
}

export async function graphqlRequest<T>(
  query: string,
  variables: Record<string, unknown> = {},
  headers: Record<string, string> = {}
): Promise<T> {
  const response = await fetch(useRuntimeConfig().public.magentoGraphqlUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', ...headers },
    body: JSON.stringify({ query, variables }),
  });

  const json: GraphQLResponse<T> = await response.json();

  if (json.errors?.length) {
    const message = json.errors.map((e) => e.message).join('; ');
    throw new Error(`Magento GraphQL error: ${message}`);
  }
  if (!json.data) {
    throw new Error('Magento GraphQL returned no data');
  }
  return json.data;
}

3. GraphQL Fragmente für konsistente Feldstrukturen

Fragmente sind der wichtigste Baustein, um Vue mit Magento GraphQL wartbar zu halten. Statt in jeder Query die Felder für Preis, Bild und Verfügbarkeit erneut aufzulisten, definiert ein Fragment diese Feldgruppe einmal zentral, und jede Query fügt das Fragment per Referenz ein. Ändert sich das Magento Schema, etwa durch ein neues Preisfeld für Sonderaktionen, wird nur das Fragment angepasst, nicht jede einzelne Query im gesamten Projekt.

Für eine Vue Magento GraphQL Integration mit vielen Komponenten empfiehlt sich eine Fragment-Datei pro Entität, also productFragments.ts, categoryFragments.ts, cartFragments.ts, mit klaren, sprechenden Fragment-Namen. Ein Fragment sollte dabei nie mehr Felder enthalten, als tatsächlich in den meisten Komponenten benötigt werden, sonst wächst die Payload unnötig für Komponenten, die nur einen Bruchteil der Felder darstellen.

// graphql/fragments/productFragments.ts — shared field groups for products
export const PRODUCT_CARD_FRAGMENT = `
  fragment ProductCardFields on ProductInterface {
    sku
    name
    url_key
    price_range { minimum_price { final_price { value currency } } }
    small_image { url label }
  }
`;

export const PRODUCT_DETAIL_FRAGMENT = `
  fragment ProductDetailFields on ProductInterface {
    ...ProductCardFields
    description { html }
    stock_status
    media_gallery { url label position }
  }
  ${PRODUCT_CARD_FRAGMENT}
`;

4. Fehlerbehandlung bei partiellen GraphQL Antworten

Ein häufig übersehener Aspekt bei Vue mit Magento GraphQL ist, dass GraphQL sowohl Daten als auch Fehler in derselben Antwort zurückgeben kann, im Gegensatz zu klassischen REST APIs mit eindeutigem HTTP-Statuscode. Eine Query kann teilweise erfolgreich sein, etwa Produktdaten liefern, aber bei einem verschachtelten Feld wie Cross-Sell-Produkten einen Fehler enthalten. Naive Fehlerbehandlung, die nur auf den HTTP-Statuscode prüft, übersieht solche partiellen Fehler komplett.

Für eine robuste Vue Magento GraphQL Integration sollte jede Komponente separat prüfen, ob die für sie relevanten Felder tatsächlich vorhanden sind, statt sich blind auf einen globalen Erfolg oder Misserfolg zu verlassen. Ein Composable, das sowohl data als auch errors aus der Antwort zurückgibt, ermöglicht es Komponenten, teilweise fehlgeschlagene Anfragen elegant zu behandeln, etwa indem Cross-Sells ausgeblendet werden, während der Hauptproduktinhalt trotzdem angezeigt wird.

5. Preise und Lagerbestand korrekt aus dem Schema lesen

Magentos GraphQL Schema modelliert Preise über verschachtelte Typen wie price_range, minimum_price und final_price, mit zusätzlichen Feldern für reguläre Preise und Sonderpreise. Ein häufiger Fehler beim Verbinden von Vue mit Magento GraphQL ist, direkt den final_price anzuzeigen, ohne zu prüfen, ob ein regular_price abweicht, wodurch eine Rabattkennzeichnung in der Oberfläche komplett fehlt, obwohl das Produkt tatsächlich reduziert ist.

Lagerbestand wird über stock_status als Enum geliefert, IN_STOCK oder OUT_OF_STOCK, aber nicht als konkrete Menge, da Magento aus Sicherheitsgründen keine exakten Lagerbestandszahlen über die öffentliche GraphQL API preisgibt. Ein Vue Magento GraphQL Composable sollte diese Enum-Werte in sprechende, typisierte Zustände übersetzen, statt den rohen String-Wert direkt in Templates zu vergleichen, was bei Tippfehlern unbemerkt fehlschlägt.

6. Authentifizierung und Store-Kontext im Request-Header

Für mehrsprachige oder mehrere Store Views nutzt Magento den Header Store, der bei jeder GraphQL Anfrage mitgesendet werden muss, damit Vue mit Magento GraphQL die richtige Sprache, Währung und Preisliste zurückliefert. Ein fehlender oder falscher Store-Header führt nicht zu einem sichtbaren Fehler, sondern zu leise falschen Daten, etwa Preisen in der falschen Währung, was besonders tückisch beim Debuggen ist.

Für eingeloggte Kunden kommt der Authorization Header mit dem Customer Token hinzu. Der zentrale Vue Magento GraphQL Client aus Abschnitt zwei sollte beide Header automatisch aus dem aktuellen Store- und Auth-Zustand ableiten, statt dass jede aufrufende Komponente diese Header manuell zusammenbauen muss.

// composables/useMagentoGraphQL.ts — automatic store and auth headers
export function useMagentoGraphQL() {
  const storeCode = useState('storeCode', () => 'default');
  const authToken = useState<string | null>('customerToken', () => null);

  async function query<T>(gql: string, variables: Record<string, unknown> = {}): Promise<T> {
    const headers: Record<string, string> = { Store: storeCode.value };
    if (authToken.value) {
      headers.Authorization = `Bearer ${authToken.value}`;
    }
    return graphqlRequest<T>(gql, variables, headers);
  }

  return { query };
}

7. Umgang mit Schema-Änderungen und Deprecations

Magentos GraphQL Schema entwickelt sich mit jedem Minor Release weiter, und Felder werden gelegentlich als deprecated markiert, bevor sie in einer späteren Version entfernt werden. Für Vue mit Magento GraphQL ist es wichtig, Deprecation-Warnungen aus der Magento Dokumentation oder aus GraphQL Introspection Tools nicht zu ignorieren, weil ein entferntes Feld sonst erst nach einem Upgrade als Laufzeitfehler auffällt, nicht schon vorher als Warnung.

Ein pragmatischer Ansatz: Ein automatisierter Schema-Diff-Check in der CI-Pipeline vergleicht das aktuelle Magento Schema mit dem Schema, gegen das die Vue Magento GraphQL Fragmente zuletzt getestet wurden, und schlägt bei entfernten oder umbenannten Feldern Alarm. Das verwandelt einen späten Produktions-Fehler in einen frühen, gut sichtbaren Build-Fehler.

8. Vue Komponenten gegen Magento GraphQL testen

Für Unit-Tests sollte eine Vue Magento GraphQL Integration niemals gegen eine echte Magento Instanz laufen, sondern gegen gemockte GraphQL Antworten mit realistischen Fixture-Daten. Tools wie Mock Service Worker fangen die Fetch-Aufrufe auf Netzwerkebene ab und liefern deterministische Antworten, ohne dass die Komponente selbst angepasst werden muss, um Test-Daten zu injizieren.

Für Integrationstests gegen eine echte Magento Instanz empfiehlt sich eine separate Testumgebung mit stabilen, bekannten Testprodukten, deren SKUs sich zwischen Testläufen nicht ändern. Ohne diese Stabilität werden Tests für Vue mit Magento GraphQL brüchig, sobald jemand im Katalog Testprodukte umbenennt oder löscht, ohne die Tests selbst anzupassen.

9. GraphQL Clients im Vergleich

Die Wahl des richtigen Clients für Vue mit Magento GraphQL hängt stark vom Umfang des Projekts ab. Die folgende Tabelle vergleicht die gängigen Optionen.

Für die überwiegende Mehrheit der Magento Storefronts auf Vue oder Nuxt Basis ist ein schlanker Fetch-Wrapper mit Nuxts eingebautem Caching der pragmatischste Weg, Vue mit Magento GraphQL zu verbinden. Apollo lohnt sich erst, wenn normalisiertes Caching über viele gleichzeitig angezeigte Entitäten hinweg zu einem konkreten, messbaren Problem wird.

10. Zusammenfassung

Wer Vue mit Magento GraphQL professionell verbindet, setzt auf einen konsistenten, zentralen Client statt verstreuter Fetch-Aufrufe, wiederverwendbare Fragmente statt duplizierter Feldlisten, und eine explizite Strategie für partielle Fehler, weil GraphQL Daten und Fehler in derselben Antwort zurückgeben kann. Preise und Lagerbestand müssen korrekt aus Magentos verschachteltem Schema gelesen werden, inklusive Rabatterkennung und typisierter Lagerbestandszustände.

Store-Kontext und Authentifizierung gehören in einen zentralen Composable, der Header automatisch aus dem aktuellen Zustand ableitet. Ein automatisierter Schema-Diff-Check in der CI-Pipeline macht Breaking Changes sichtbar, bevor sie zum Produktionsproblem werden, und gemockte GraphQL Fixtures halten Tests für Vue mit Magento GraphQL unabhängig von einer echten Magento Instanz.

11. FAQ: Vue mit Magento GraphQL verbinden