Alpine.js Stores für globalen State im Hyvä-Theme

1. Warum Prop-Drilling in Hyvä-Templates schnell unuebersichtlich wird

In einem klassischen Alpine-Aufbau lebt Zustand lokal in x-data, direkt an dem Element, das ihn benoetigt. Für isolierte UI-Elemente wie ein Dropdown oder ein Akkordeon funktioniert das hervorragend. Sobald aber mehrere, strukturell weit auseinanderliegende Komponenten denselben Wert kennen müssen, etwa die Anzahl der Warenkorb-Artikel im Header, in einer Sticky-Add-to-Cart-Leiste und im Minicart-Badge, stoesst der Ansatz an Grenzen.

Der naheliegende Reflex ist, den Wert als Prop von einer Elternkomponente an alle Kinder durchzureichen, oder ihn per Custom Event muehsam durch die DOM-Hierarchie zu schicken. In Hyvä-Templates, die oft aus vielen unabhaengig geladenen phtml-Bloecken bestehen, gibt es aber gar keine gemeinsame Elternkomponente, die diese Rolle übernehmen könnte. Jede Prop-Drilling-Lösung endet hier in einem Geflecht aus Events, das schwer nachzuvollziehen ist.

// Anti-Pattern: Synchronisation über verstreute Custom Events
// Header, Sticky-Bar und Minicart müssen je einen eigenen Listener pflegen
document.addEventListener('cart:item-added', (event) => {
  document.querySelectorAll('[data-cart-badge]').forEach((el) => {
    el.textContent = event.detail.itemCount;
  });
});
document.addEventListener('cart:item-added', (event) => {
  document.querySelector('[data-sticky-bar-count]').textContent = event.detail.itemCount;
});
// Jede neue Stelle, die den Zaehler anzeigt, braucht einen weiteren Listener

2. Alpine.store(): Grundlagen des globalen reaktiven Speichers

Alpine.store() registriert ein benanntes, reaktives Objekt, das über $store.name aus jeder beliebigen x-data-Komponente auf der Seite erreichbar ist, unabhaengig davon, wo im DOM sie sitzt. Anders als lokaler x-data-Zustand existiert ein Store nur einmal pro Seite, und jede Komponente, die per x-text, x-show oder x-bind auf einen Store-Wert zugreift, wird bei einer Änderung automatisch neu gerendert.

Wichtig ist der Registrierungszeitpunkt: Stores müssen vor dem Alpine.start()-Aufruf definiert sein, sonst greifen frühe Komponenten ins Leere. Hyvä laedt Alpine über den zentralen Bootstrap, deshalb gehoert die Store-Definition in ein eigenes Skript, das am alpine:init-Event haengt und garantiert vor dem Start ausgefuehrt wird.

document.addEventListener('alpine:init', () => {
  Alpine.store('cart', {
    itemCount: 0,
    increment(qty = 1) {
      this.itemCount += qty;
    },
    setFromSectionData(count) {
      this.itemCount = count;
    },
  });
});

3. Wo Stores im Hyvä-Theme sauber registriert werden

In Hyvä landet Store-Definitionscode am besten in einer eigenen phtml-Datei, die im Layout-Handle default.xml als frueh geladener Skript-Block eingebunden wird, damit sie zuverlaessig vor den ersten Komponenten läuft, die den Store konsumieren. Wichtig: Der Inline-Block muss per registerInlineScript() bei der Content Security Policy angemeldet werden, sonst blockiert Hyväs CSP-Modul das Skript im Produktivbetrieb.

Für größere Themes lohnt sich ein eigenes Modul unter web/js/stores/ mit einem Export pro Store, das im requirejs-config.js als Alias registriert und dann aus dem Bootstrap-Skript importiert wird. Das haelt die Store-Definition testbar und vermeidet, dass Store-Logik über mehrere Inline-Skript-Bloecke verstreut wird.

<?php /** @var \Magento\Framework\View\Element\Template $block */
/** @var \Hyva\Theme\ViewModel\HyvaCsp $hyvaCsp */
$hyvaCsp = $block->getData('hyvaCsp');
?>
<script>
  document.addEventListener('alpine:init', () => {
    Alpine.store('cart', { itemCount: <?= (int) $block->getCartItemCount() ?> });
  });
</script>
<?= $hyvaCsp->registerInlineScript() ?>

4. Praxisbeispiel: Ein Warenkorb-Store für die Artikel-Anzahl

Der Warenkorb-Store haelt den zentralen Zaehler itemCount sowie eine Methode increment(), die von jeder Add-to-Cart-Aktion im Theme aufgerufen wird, egal ob sie auf der Produktseite, in der Kategorie-Schnellansicht oder im Minicart selbst ausgeloest wird. Header-Badge, Sticky-Bar und Minicart-Icon lesen alle denselben $store.cart.itemCount und bleiben dadurch ohne einen einzigen Custom Event zwischen ihnen synchron.

Der eigentliche Trigger bleibt weiterhin Magentos Add-to-Cart-Ajax-Aufruf, der Store übernimmt lediglich die UI-seitige Synchronisation. Erst wenn der Ajax-Aufruf erfolgreich zurueckkommt, ruft die aufrufende Komponente $store.cart.increment(qty) auf, sodass die Anzeige nie einen Wert zeigt, der serverseitig gar nicht existiert.

<div x-data class="relative">
  <button type="button" aria-label="Warenkorb">
    <span x-show="$store.cart.itemCount > 0"
          x-text="$store.cart.itemCount"
          class="absolute -top-2 -right-2 rounded-full bg-orange-600 px-1.5 text-xs text-white"></span>
  </button>
</div>

<script>
  function addToCartHandler(productId, qty) {
    return fetch('/checkout/cart/add', { method: 'POST', body: buildFormData(productId, qty) })
      .then((response) => {
        if (response.ok) {
          Alpine.store('cart').increment(qty);
        }
        return response;
      });
  }
</script>

5. Zusammenspiel mit Magentos Section Data und Customer Data

Magentos Section-Data-Mechanismus bleibt in Hyvä die eigentliche Wahrheitsquelle für Warenkorb- und Kundendaten, weil er den serverseitigen, privaten Content über den Private-Content-Cache liefert, inklusive korrekter Invalidierung bei aktivem Full-Page-Cache. Ein Alpine-Store darf diese Rolle nicht ersetzen, sondern sollte als schnelle, clientseitige Projektion der zuletzt bekannten Section-Daten verstanden werden.

Praktisch bedeutet das: Nach jedem Section-Data-Reload, den Hyvä über sein eigenes Customer-Data-Äquivalent ausloest, liest eine kleine Bridge-Funktion die aktuellen Werte aus dem Section-Storage und schreibt sie in den passenden Alpine-Store. So bleibt der Store immer nur ein Spiegelbild der echten, serverseitig autorisierten Daten, nie eine eigenständige Quelle.

document.addEventListener('private-content-loaded', (event) => {
  const cartSection = event.detail.data.cart;
  if (cartSection) {
    Alpine.store('cart').setFromSectionData(cartSection.summary_count);
  }
  const wishlistSection = event.detail.data.wishlist;
  if (wishlistSection) {
    Alpine.store('wishlist').setFromSectionData(wishlistSection.items);
  }
});

6. Wishlist-Status als zweiter Store: reaktive Herzen ohne Reload

Ein zweiter, typischer Anwendungsfall ist der Wishlist-Status pro Produkt. Statt für jede Produktkachel einzeln zu prüfen, ob ein Artikel bereits auf der Wunschliste liegt, haelt ein wishlist-Store ein Set von Produkt-IDs, das beim Laden der Seite einmalig aus den Section-Daten befuellt wird und danach von jeder Produktkachel per x-bind:class abgefragt wird.

Der entscheidende Vorteil zeigt sich beim Hinzufuegen: Klickt ein Kunde in der Kategorie-Übersicht auf mehreren Kacheln gleichzeitig auf das Herz-Icon, aktualisieren sich alle betroffenen Icons augenblicklich über denselben Store, auch wenn nur eine einzige Komponente den Ajax-Aufruf tatsaechlich ausgeloest hat.

document.addEventListener('alpine:init', () => {
  Alpine.store('wishlist', {
    ids: new Set(),
    setFromSectionData(items) {
      this.ids = new Set(items.map((item) => item.product_id));
    },
    has(productId) {
      return this.ids.has(productId);
    },
    toggle(productId) {
      this.ids.has(productId) ? this.ids.delete(productId) : this.ids.add(productId);
      this.ids = new Set(this.ids);
    },
  });
});

7. Persistenz-Strategie über Seitenwechsel hinweg

Hyvä ist bewusst keine Single-Page-Application, jeder Klick auf einen Link löst einen vollstaendigen Seitenaufruf aus, wodurch jeder Alpine-Store bei jeder Navigation komplett neu initialisiert wird. Anders als in einer SPA bringt das offizielle Alpine-Persist-Plugin mit localStorage-Bindung deshalb nur für wenige UI-Zustaende echten Mehrwert, etwa ob ein Filter-Panel eingeklappt war.

Für Warenkorb- und Wishlist-Daten ist Persistenz über localStorage sogar riskant, weil sie mit dem serverseitigen Stand auseinanderlaufen kann, etwa wenn sich der Kunde in einem zweiten Tab abmeldet. Die robustere Strategie ist deshalb, den Store bei jedem Seitenaufruf frisch aus den aktuellen Section-Daten zu initialisieren, statt ihn über den Browser-Speicher kuenstlich am Leben zu halten.

// Sinnvoller Einsatz von Alpine Persist: reine UI-Praeferenz, kein Serverbezug
Alpine.store('filterPanel', {
  collapsed: Alpine.$persist(false).as('filterPanelCollapsed'),
  toggle() {
    this.collapsed = !this.collapsed;
  },
});
// Warenkorb- und Wishlist-Store bewusst OHNE $persist, immer frisch aus Section Data

8. Performance-Aspekte: Reaktivitaet ohne unnoetige Re-Renders

Weil potenziell viele Komponenten auf demselben Store lauschen, lohnt sich ein Blick auf die Granularitaet der beobachteten Werte. Wer das komplette Store-Objekt per x-text ausgibt, statt gezielt auf ein einzelnes Feld zu binden, erzwingt bei jeder noch so kleinen Änderung eine Neuberechnung aller abhaengigen Ausdruecke im DOM, auch dort, wo sich der angezeigte Wert gar nicht geaendert hat.

Ein weiterer Stolperstein ist das komplette Ersetzen eines Store-Objekts statt der gezielten Mutation einzelner Felder. Alpines Reaktivitaet basiert auf Proxy-Traps auf Objekt- und Array-Ebene, ein Ersetzen des gesamten Objekts funktioniert zwar, kann aber bei tief verschachtelten Strukturen zu spuerbaren Verzoegerungen fuehren, wenn viele Komponenten gleichzeitig neu evaluieren müssen.

9. Debugging und typische Fehler im Store-Alltag

Der haeufigste Fehler ist der Zugriff auf einen Store, bevor er registriert wurde, meist weil das Store-Skript nach statt vor den konsumierenden Komponenten im DOM steht oder der registerInlineScript()-Aufruf im falschen Layout-Handle liegt. Die Fehlermeldung zu undefinierten Eigenschaften beim ersten Klick ist in Hyvä-Projekten fast immer ein Hinweis auf genau dieses Timing-Problem.

Für die Fehlersuche selbst reicht in der Regel die Browser-Konsole: Alpine.store('cart') gibt das aktuelle Store-Objekt live zurück und lässt sich direkt manipulieren, um UI-Reaktionen ohne echten Ajax-Aufruf zu testen. Die offizielle Alpine-Devtools-Erweiterung zeigt zusätzlich alle registrierten Stores in einem eigenen Panel, inklusive Live-Werten bei jeder Interaktion.

10. Zusammenfassung

11. FAQ: Alpine Stores in Hyvä