GraphQL in Headless Frontends: Magento mit React, Vue oder Next.js

1. Headless Commerce: was das Architekturversprechen bedeutet

Headless Commerce bedeutet, dass das Frontend vollständig vom Commerce-Backend entkoppelt ist. Magento dient als Daten- und Geschäftslogik-Layer, das Frontend als eigenständige Applikation, die über APIs kommuniziert. GraphQL ist dabei die bevorzugte Schnittstelle, weil sie dem Frontend erlaubt, genau die Daten abzufragen, die für eine bestimmte Seite benötigt werden – ohne mehrere REST-Endpunkte koordinieren zu müssen. Das Architekturversprechen ist: bessere Frontend-Performance, technologische Freiheit bei der Frontend-Wahl, und die Möglichkeit, das Frontend unabhängig vom Magento-Upgrade-Zyklus weiterzuentwickeln.

In der Praxis zeigt sich, dass dieses Versprechen nur dann eingelöst wird, wenn mehrere Voraussetzungen erfüllt sind. Das GraphQL-Schema muss stabil und gut dokumentiert sein, damit das Frontend-Team unabhängig arbeiten kann. Caching muss auf mehreren Ebenen durchdacht sein: Apollo In-Memory-Cache, HTTP-Cache-Layer und CDN-Edge-Cache. Und der Kundenkontext – Warenkorb, Loginzustand, Preisgruppe – muss sicher und performant über Session-Tokens transportiert werden. Wer nur das Frontend wechselt, ohne diese Punkte zu adressieren, tauscht bekannte Luma-Probleme gegen neue Headless-Probleme.

2. Apollo Client vs. URQL vs. fetch: die richtige Wahl

Apollo Client ist die umfassendste Lösung: normalisierter In-Memory-Cache, React Hooks (useQuery, useMutation), optimistische Updates, Pagination-Utilities und eine große Ecosystem-Bibliothek. Für komplexe Commerce-Frontends mit Warenkorb, Produktlisten, Suchfunktion und Kundenkontext ist Apollo Client die stärkste Wahl, auch wenn die Konfiguration initial aufwändiger ist. Der normalisierte Cache ist besonders wertvoll, wenn dieselben Produkte über verschiedene Queries geladen werden – Apollo dedupliziert sie automatisch.

URQL ist leichtgewichtiger, modularer und einfacher zu konfigurieren. Für Projekte, bei denen nicht alle Apollo-Features benötigt werden, ist URQL eine gute Alternative. Simples fetch mit einer selbst geschriebenen Wrapper-Funktion ist ausreichend für SSR/SSG-Kontexte in Next.js, wo Queries nur einmal bei der Page-Generierung ausgeführt werden und kein clientseitiger Cache benötigt wird. Die Wahl hängt von der Komplexität des Frontends ab: Je mehr clientseitiger State und Update-Logik, desto mehr lohnt Apollo Client.

# Fragment-based product query — collocated with the ProductCard component
# This query is generated and typed by GraphQL Code Generator

fragment ProductCardFragment on ProductInterface {
  __typename
  sku
  name
  url_key
  small_image {
    url
    label
  }
  price_range {
    minimum_price {
      final_price {
        value
        currency
      }
      discount {
        percent_off
      }
    }
  }
}

query GetCategoryProducts(
  $categoryId: String!
  $pageSize: Int = 24
  $currentPage: Int = 1
) {
  products(
    filter: { category_id: { eq: $categoryId } }
    pageSize: $pageSize
    currentPage: $currentPage
    sort: { position: ASC }
  ) {
    total_count
    page_info {
      current_page
      page_size
      total_pages
    }
    items {
      ...ProductCardFragment
    }
  }
}

3. Code-Generierung: typsichere Queries in TypeScript

GraphQL Code Generator analysiert das Magento-Schema und die im Frontend definierten Queries und Fragments und generiert daraus vollständig typsichere TypeScript-Typen und React-Hooks. Das Ergebnis: statt manuelle Interface-Definitionen für jeden Query-Response pflegen zu müssen, entstehen Typen automatisch aus dem Schema. Wenn Magento im nächsten Release ein Feld umbenennt oder einen Typ ändert, schlägt die Code-Generierung sofort fehl – der Breaking Change wird im Frontend sichtbar, bevor er in der Produktion Probleme macht.

Die Konfiguration von GraphQL Code Generator für Magento erfordert einen Schema-Download. Das Magento GraphQL-Schema kann über den Introspection-Endpunkt (POST /graphql mit der Introspection-Query) oder als SDL-Datei bereitgestellt werden. Für Teams empfiehlt sich ein automatischer Schema-Download in der CI-Pipeline, der bei jeder Magento-Version-Aktualisierung ausgeführt wird. So bleiben generierte Typen immer synchron mit dem tatsächlichen Magento-Schema, und Diskrepanzen werden im CI erkannt, bevor ein Entwickler eine Stunde lang einen Type-Error debuggt.

4. Fragment-Colocation: Queries nah am Component

Fragment-Colocation ist eines der wichtigsten Prinzipien für wartbare GraphQL-Frontends. Die Idee: Jeder React-Component definiert selbst das Fragment, das beschreibt, welche Daten er benötigt. Die übergeordnete Page-Komponente kombiniert diese Fragments in einer Query. Wenn ein Component neue Daten braucht, fügt er Felder zum eigenen Fragment hinzu – die Query aktualisiert sich automatisch. Das eliminiert die häufige Situation, dass eine zentrale Query-Datei für den gesamten Seitenbedarf gepflegt werden muss, und Entwickler lange suchen müssen, welche Felder für welche Components benötigt werden.

Mit GraphQL Code Generator in Kombination mit dem near-operation-file-Preset landet die generierte Hook-Datei direkt neben der Query-Datei. Das gesamte Datenmuster – Component, Fragment, generierter Hook, Typen – ist in einem Verzeichnis. Bei einer Code-Review ist sofort sichtbar, was ein Component rendert und welche Daten er anfordert. Dieses Muster skaliert auch in größeren Teams: Frontend-Teams können parallel an verschiedenen Page-Sections arbeiten, ohne Query-Konflikte zu erzeugen.

# Authentication: customer token flow in Magento GraphQL
# Step 1: generate token with credentials
mutation GenerateCustomerToken($email: String!, $password: String!) {
  generateCustomerToken(email: $email, password: $password) {
    token
  }
}

# Step 2: use token in Authorization header for subsequent requests
# Authorization: Bearer <token>

# Step 3: fetch customer data with active session
query GetCustomerData {
  customer {
    firstname
    lastname
    email
    addresses {
      id
      firstname
      lastname
      street
      city
      postcode
      country_code
      default_shipping
      default_billing
    }
    orders(pageSize: 5) {
      items {
        number
        order_date
        status
        total {
          grand_total { value currency }
        }
      }
    }
  }
}

# Step 4: revoke token on logout
mutation RevokeCustomerToken {
  revokeCustomerToken {
    result
  }
}

5. Caching im Headless-Frontend: Apollo, SSR und CDN

Der Apollo In-Memory-Cache normalisiert alle GraphQL-Responses nach Typ und ID. Das bedeutet: Wird ein Produkt mit SKU DEMO-001 in einer Kategorieliste geladen und später auf der Produktdetailseite erneut angefragt, gibt Apollo die gecachte Version zurück – ohne weiteren Netzwerk-Request. Diese Normalisierung funktioniert automatisch für alle Typen, die ein id-Feld haben. Für Magento-Typen, die keine Standard-ID verwenden (wie Produktarten mit sku statt id), muss der Apollo Cache mit einer benutzerdefinierten keyFields-Konfiguration angepasst werden.

Auf der HTTP-Ebene sind Magento-GraphQL-Queries grundsätzlich POST-Requests und werden von HTTP-Caches nicht gecacht. Persisted Queries wandeln häufig verwendete Queries in GET-Requests mit einem Hash als Parameter um. Diese GET-Requests können von CDNs und Reverse-Proxies gecacht werden. Magento unterstützt Persisted Queries nativ für Katalogdaten – Queries ohne Kundenkontext können so mit sehr hohen Cache-Hit-Raten aus dem CDN bedient werden. Das reduziert die Last auf Magento und verbessert Time-to-First-Byte erheblich.

6. SSR und SSG mit Next.js und Magento GraphQL

Next.js bietet drei Rendering-Strategien, die unterschiedliche GraphQL-Caching-Ansätze erfordern. Static Site Generation (SSG) mit getStaticProps eignet sich für Produktdetailseiten und Kategorieseiten ohne Kundenkontext: Die GraphQL-Query wird bei Build-Time ausgeführt, die Seite wird als statisches HTML ausgeliefert. Incremental Static Regeneration (ISR) ergänzt SSG um automatische Aktualisierung nach einem konfigurierbaren Intervall – ideal für Kategorieseiten, die sich nicht bei jedem Request ändern, aber aktuell bleiben müssen. Server-Side Rendering (SSR) ist notwendig, wenn der Kundenkontext die gerenderten Daten beeinflusst – etwa personalisierte Preise oder Store-Credit-Informationen.

Eine wichtige Einschränkung: Apollo Client ist primär für den Browser konzipiert. In Next.js SSR-Kontexten empfiehlt sich entweder ein Server-Only-Fetch-Pattern ohne Apollo, oder Apollo mit @apollo/client/react/ssr und der renderToStringWithData-Funktion, die alle Apollo-Queries während des Server-Renderings auflöst. Für die meisten Commerce-Seiten ist ein simples fetch in getStaticProps und ein separater Apollo Client nur im Browser die klarere und wartbarere Lösung.

7. React vs. Vue vs. Next.js: was passt zu welchem Projekt

Die Wahl des Frontend-Frameworks beeinflusst die GraphQL-Client-Wahl und die Caching-Architektur. React mit Apollo Client ist die am besten dokumentierte Kombination mit Magento GraphQL und hat die größte Ökosystem-Unterstützung. Next.js baut darauf auf und fügt SSR/SSG und File-System-Routing hinzu – es ist die natürliche Wahl für Commerce-Projekte, bei denen SEO und Initial-Load-Performance kritisch sind. Vue 3 mit URQL oder dem Vue Apollo-Wrapper ist eine gute Wahl für Teams mit bestehender Vue-Erfahrung; die GraphQL-Patterns sind dieselben, nur die Component-API unterscheidet sich.

Für neue Headless-Magento-Projekte ist Next.js aktuell die Standardempfehlung: die Kombination aus SSG für Katalogseiten, SSR für personalisierte Seiten und nativem Image-Optimierung-Support macht es zum stärksten Commerce-Framework im React-Ökosystem. Vue-Teams setzen auf Nuxt.js und URQL mit denselben GraphQL-Prinzipien.

8. Typische Fehler im Headless-Betrieb

Der häufigste Fehler: alle Daten bei jedem Request neu von Magento laden, ohne Caching-Schichten zu nutzen. Kategorieseiten, die bei jedem Request die gesamte Produktliste frisch von Magento laden, erzeugen unnötige Last und schlechte TTFB-Werte. Die Lösung ist eine klare Trennung nach Datentyp: statische Katalogdaten werden gecacht (ISR, CDN), kundensitzungsbezogene Daten werden nicht gecacht.

Der zweite häufige Fehler ist das Laden zu vieler Felder in einer Query. GraphQL-Queries, die hunderte von Feldern abrufen, weil das Frontend sie theoretisch brauchen könnte, belasten Magento-Resolver unnötig. Fragment-Colocation löst dieses Problem strukturell: jeder Component fordert nur die Felder an, die er tatsächlich rendert. Der dritte Fehler betrifft den Kundentoken-Umgang: Customer-Tokens, die im localStorage gespeichert werden, sind XSS-anfällig. Für Commerce-Applikationen ist HttpOnly-Cookie-Storage die sicherere Alternative, erfordert aber eine CORS-Konfiguration auf dem Magento-Server.

9. Authentication und Kundenkontext im Headless-Frontend

Magento GraphQL verwendet Bearer-Token-Authentication. Ein Kundentoken wird über die generateCustomerToken-Mutation ausgestellt und muss bei allen nachfolgenden Requests als Authorization: Bearer <token>-Header mitgeschickt werden. Tokens haben keine eingebaute Ablaufzeit in Standard-Magento – die Gültigkeit muss über Konfiguration oder Custom-Module gesteuert werden. Bei der Implementierung im Frontend muss sichergestellt sein, dass Queries, die Kundendaten enthalten, niemals gecacht werden – weder im Apollo In-Memory-Cache für andere Nutzer noch im CDN.

Der Warenkorb im Headless-Frontend ist ein besonders kritischer Punkt. Magento unterscheidet zwischen Guest-Carts (mit einer Cart-ID als String) und Customer-Carts (verknüpft mit dem Kundentoken). Beim Login muss der Guest-Cart in den Customer-Cart gemerged werden (mergeCarts-Mutation). Diese Logik ist fehleranfällig und muss explizit getestet werden, besonders in Kombination mit Browser-Tab-Wechseln und parallelen Sessions. Ein gut strukturiertes State-Management für den Cart-Kontext ist wichtiger als die technische GraphQL-Implementierung.

# Cart management in headless Magento: guest to customer merge
# Step 1: create guest cart
mutation CreateGuestCart {
  createEmptyCart
}
# Returns: "abc123" — store as cookie or localStorage

# Step 2: add items to guest cart
mutation AddToGuestCart($cartId: String!, $sku: String!, $qty: Float!) {
  addSimpleProductsToCart(input: {
    cart_id: $cartId
    cart_items: [{ data: { sku: $sku, quantity: $qty } }]
  }) {
    cart {
      id
      totalQuantity
    }
  }
}

# Step 3: after login — merge guest cart into customer cart
mutation MergeCarts($guestCartId: String!, $customerCartId: String!) {
  mergeCarts(
    source_cart_id: $guestCartId
    destination_cart_id: $customerCartId
  ) {
    id
    totalQuantity
    itemsV2 {
      items {
        product { sku name }
        quantity
      }
    }
  }
}

10. Zusammenfassung

Headless Commerce mit Magento GraphQL ist eine reife Architektur, die bei sorgfältiger Implementierung echte Vorteile bringt: Frontend-Unabhängigkeit, präzise Datenabfragen und bessere Performance durch mehrstufiges Caching. Die kritischen Erfolgsfaktoren sind: typsichere Code-Generierung mit GraphQL Code Generator, Fragment-Colocation für wartbare Queries, klar getrennte Caching-Strategien für statische und kundenbezogene Daten, und eine robuste Cart-Merge-Logik beim Login-Flow.

Next.js ist aktuell die stärkste Wahl für neue Headless-Magento-Projekte, weil SSG, ISR und SSR nativ integriert sind und die Caching-Architektur für Commerce-Anforderungen gut passt. Apollo Client ist die empfohlene GraphQL-Client-Bibliothek für komplexe Commerce-Frontends. Einfachere Projekte können mit URQL oder simpleren fetch-Patterns beginnen und bei Bedarf zu Apollo migrieren.

11. FAQ: GraphQL in Headless Frontends mit Magento