TypeScript-Patterns für Alpine.js-Komponenten in Hyvä

1. Alpine.js x-data ist ungetypt: das Risiko in größeren Komponenten

Alpine.js verzichtet bewusst auf ein Typsystem: x-data nimmt einen beliebigen JavaScript-Ausdruck entgegen, der zur Laufzeit ausgewertet wird - kein Compiler, kein Typecheck, keine Autovervollständigung für Properties oder Methoden. Ein Tippfehler wie open statt isOpen fällt nicht beim Speichern auf, sondern erst im Browser, wenn ein Klick-Handler stillschweigend nichts tut. Für ein winziges Dropdown-Snippet mit zwei Properties ist das kein Problem. Sobald eine Komponente aber wächst, wie ein Mini-Cart mit Mengen-Update, AJAX-Aufrufen und mehreren $watch-Bindings, summieren sich diese blinden Flecken zu echten Bugs, die erst im Live-Betrieb auffallen.

In Hyvä-Projekten trifft dieses Risiko besonders häufig auf größere x-data-Blöcke: Checkout-Formulare mit bedingter Feldlogik, Produktkonfiguratoren mit Varianten-Matrix, Layered-Navigation-Filter mit verschachteltem State. Mehrere Entwickler bearbeiten dieselbe Komponente über Monate, und ohne Typen verliert jeder Refactoring-Schritt seine Sicherheitsnetze: eine umbenannte Property wird nicht rot markiert, sie bricht einfach im Frontend. Die Lösung ist nicht, TypeScript und einen kompletten Build-Prozess in jedes Theme zu zwingen, sondern gezielt dort Typsicherheit einzuführen, wo Komponenten komplex genug sind, dass sich der Aufwand lohnt.

2. Typisierte Component-Factory-Functions mit Alpine.AlpineComponent

Der pragmatischste Einstieg in typisierte Alpine-Komponenten ist eine Factory-Function, die ein Objekt zurückgibt, dessen Form exakt der AlpineComponent-Schnittstelle aus den offiziellen Alpine-Typdefinitionen entspricht. Statt x-data="{ open: false, toggle() { this.open = !this.open } }" direkt im Markup zu schreiben, definiert man eine Funktion wie function dropdown(): AlpineComponent<DropdownState> in einer separaten Datei, deklariert jede Property mit explizitem Typ und lässt den Compiler jede Verwendung von this innerhalb der Methoden prüfen. Falsche Property-Zugriffe, vergessene Rückgaben und inkonsistente Methoden-Signaturen werden so schon beim Schreiben sichtbar, nicht erst beim Klicken im Browser.

Wichtig ist, dass diese Funktion reines JavaScript beziehungsweise nach der Kompilierung reines JavaScript bleibt: Alpine selbst weiß nichts von TypeScript und erwartet zur Laufzeit ein gewöhnliches Objekt. Die Typprüfung passiert ausschließlich zur Entwicklungszeit, das Ergebnis ist ein normaler Alpine.data()-Aufruf ohne Laufzeit-Overhead. Dieses Pattern lässt sich pro Komponente einzeln einführen, ohne dass das gesamte Theme auf TypeScript umgestellt werden muss - ideal für Hyvä-Projekte, die nur ihre komplexesten Komponenten typisieren wollen.

// dropdown.ts - typed Alpine component factory
import type { AlpineComponent } from 'alpinejs';

interface DropdownState {
  open: boolean;
  toggle(): void;
  close(): void;
}

export function dropdown(): AlpineComponent<DropdownState> {
  return {
    open: false,
    toggle() {
      this.open = !this.open;
    },
    close() {
      this.open = false;
    },
  };
}

3. JSDoc-basierte Typisierung ohne TypeScript-Build-Step

Nicht jedes Team will einen TypeScript-Build-Step in die Hyvä-Pipeline einführen, gerade wenn Tailwind- und Alpine-Kompilierung bereits über den Hyvä-Watcher laufen und ein zusätzlicher tsc-Schritt als überflüssige Komplexität empfunden wird. JSDoc-Kommentare bieten hier einen echten Mittelweg: Mit @param, @returns und @typedef lassen sich Typen direkt in normalem JavaScript annotieren, und moderne Editoren wie VS Code oder PhpStorm werten diese Kommentare über die integrierte TypeScript-Sprachengine aus - Autovervollständigung, Typfehler-Unterstreichung und Refactoring-Unterstützung funktionieren, ohne dass eine einzige .ts-Datei oder ein Build-Schritt existiert.

Der Trick liegt in einer jsconfig.json mit "checkJs": true im Projektstamm, die den Editor anweist, JavaScript-Dateien wie TypeScript zu prüfen. Für Alpine-Komponenten definiert man ein @typedef für den Komponentenzustand und referenziert es in der JSDoc-Signatur der Factory-Function. Das Ergebnis ist eine Datei, die zur Laufzeit unverändertes JavaScript bleibt, aber während der Entwicklung dieselbe Typsicherheit wie eine .ts-Datei bietet - ein Ansatz, der besonders für kleinere Teams oder Agentur-Projekte mit engem Deployment-Zeitplan attraktiv ist.

// mini-cart.js - JSDoc-based typing, no build step required
/**
 * @typedef {Object} MiniCartState
 * @property {number} itemCount
 * @property {boolean} isLoading
 * @property {(qty: number) => void} updateQuantity
 * @property {() => Promise<void>} refresh
 */

/**
 * Factory function for the mini cart Alpine component.
 * @returns {MiniCartState}
 */
function miniCart() {
  return {
    itemCount: 0,
    isLoading: false,
    updateQuantity(qty) {
      this.itemCount = qty;
    },
    async refresh() {
      this.isLoading = true;
      const response = await fetch('/rest/V1/carts/mine');
      const data = await response.json();
      this.itemCount = data.items_count;
      this.isLoading = false;
    },
  };
}

document.addEventListener('alpine:init', () => {
  Alpine.data('miniCart', miniCart);
});

4. Das leichtgewichtige TS-Pattern: .ts-Datei kompiliert zu Alpine.data()

Für Teams, die bereits eine Build-Pipeline für andere JavaScript-Module pflegen, lohnt sich das nächste Level: eine .ts-Datei pro Komponente, die eine typisierte Factory-Function exportiert und über esbuild oder tsc zu einer normalen .js-Datei kompiliert wird. Diese kompilierte Datei wird anschließend ganz regulär über Alpine.data('dropdown', dropdown) registriert, meist in einem zentralen Einstiegspunkt, der vor Alpine.start() geladen wird. Der entscheidende Vorteil gegenüber reinem JSDoc: generische Typen, Union-Types und Interfaces für komplexe verschachtelte Zustände lassen sich in echtem TypeScript deutlich präziser und kompakter ausdrücken als in Kommentarform.

Wichtig für Hyvä-Projekte ist, den Build-Schritt so schlank wie möglich zu halten: Ein einzelner esbuild-Aufruf ohne Bundler-Overhead reicht für die meisten Komponenten aus und lässt sich problemlos in den bestehenden npm-Workflow neben dem Tailwind-Build einhängen. Kein Framework-Bundle, kein zusätzlicher Vendor-Chunk, keine Laufzeitabhängigkeit von TypeScript im Browser. Das kompilierte Ergebnis ist exakt dasselbe schlanke JavaScript, das Alpine ohnehin erwartet - nur dass es aus einer typgeprüften Quelle stammt statt aus handgeschriebenem, ungeprüftem Code.

// src/alpine/product-configurator.ts - compiled to plain JS via esbuild, then registered
interface ConfiguratorOption {
  optionId: number;
  label: string;
  priceDelta: number;
}

interface ConfiguratorState {
  selected: Record<number, number>;
  options: ConfiguratorOption[];
  selectOption(optionId: number, valueId: number): void;
  totalPrice(basePrice: number): number;
}

export function productConfigurator(options: ConfiguratorOption[]): ConfiguratorState {
  return {
    selected: {},
    options,
    selectOption(optionId, valueId) {
      this.selected[optionId] = valueId;
    },
    totalPrice(basePrice) {
      return this.options.reduce((sum, opt) => sum + opt.priceDelta, basePrice);
    },
  };
}

// build: esbuild src/alpine/*.ts --outdir=web/js/alpine --format=esm --target=es2020
// entrypoint.js - registered before Alpine.start()
// import { productConfigurator } from './alpine/product-configurator.js';
// document.addEventListener('alpine:init', () => {
//   Alpine.data('productConfigurator', productConfigurator);
// });

5. Alpine-Magics typisieren: $store und $dispatch

Alpine stellt magische Properties wie $store, $dispatch, $watch und $refs bereit, die in x-data-Ausdrücken ohne Import verfügbar sind - für den TypeScript-Compiler sind sie aber zunächst unbekannt, weil sie nicht Teil des regulären this-Kontexts einer Klasse oder eines Objekts sind. Die offiziellen Alpine-Typdefinitionen lösen das über Interface-Erweiterungen: Mit einer eigenen Typdeklaration für den globalen Store lässt sich $store.cart als typisiertes Objekt mit bekannten Properties nutzen, statt als any behandelt zu werden, das jede Eigenschaft klaglos akzeptiert.

Für $dispatch lohnt sich ein typisiertes Wrapper-Pattern: eine Hilfsfunktion, die den Event-Namen und die Payload-Form als generische Parameter erzwingt, sodass ein Tippfehler im Event-Namen oder eine falsche Payload-Struktur schon beim Kompilieren auffällt, statt erst beim Debuggen eines Events, das nirgends ankommt. Gerade bei Hyvä-Komponenten, die über CustomEvents miteinander kommunizieren, etwa Mini-Cart und Produktkarten, verhindert diese Typisierung ein ganzes Muster von Integrationsfehlern, die sonst erst im Browser sichtbar werden.

6. x-data-JSON-Attribute aus phtml/PHP typsicher übergeben

Ein Hyvä-typisches Muster ist, serverseitige Daten aus dem PHP-Block über json_encode() direkt als x-data-Argument ins Markup zu schreiben, etwa x-data="productConfigurator(<?= ... ?>)". Diese Daten kommen zur Laufzeit als reines JSON an, ohne jede Garantie, dass die Struktur mit dem erwarteten TypeScript-Interface übereinstimmt - ein geänderter ViewModel-Output auf PHP-Seite kann die Frontend-Komponente stillschweigend brechen, weil TypeScript die Form der JSON-Daten zur Compile-Zeit nicht kennt.

Die robuste Lösung ist ein explizites Interface für die vom Server kommende Payload, kombiniert mit einer schlanken Validierung an der Grenze zwischen PHP und JavaScript, etwa einer einfachen Typwächter-Funktion, die die erwarteten Felder zur Laufzeit prüft, bevor die Komponente sie verwendet. So bleibt die Typannotation nicht nur dokumentierender Kommentar, sondern deckt tatsächliche Abweichungen zwischen PHP-Output und Frontend-Erwartung auf - besonders wertvoll, wenn ViewModel und Alpine-Komponente von unterschiedlichen Entwicklern gepflegt werden.

{
  "options": [
    { "optionId": 93, "label": "Farbe", "priceDelta": 0 },
    { "optionId": 144, "label": "Groesse", "priceDelta": 5.00 }
  ],
  "basePrice": 49.90,
  "sku": "MS-1234"
}

7. CSP-Kompatibilität: kein eval, registerInlineScript korrekt nutzen

Hyvä setzt aus Sicherheitsgründen auf eine strikte Content-Security-Policy, die per Default kein eval() und keine unregistrierten Inline-Skripte erlaubt - beides Dinge, die klassische TypeScript-Tooling-Setups gerne implizit nutzen, etwa Source-Maps mit eval-basiertem Debugging oder dynamisch generierter Code aus manchen Bundlern. Für Alpine-Komponenten bedeutet das: Der TypeScript-Compiler-Output darf niemals new Function() oder eval() enthalten, und jedes esbuild- oder tsc-Target muss auf ein CSP-kompatibles Ausgabeformat wie ES2020 ohne eval-Sourcemaps eingestellt sein.

Für Inline-Skripte, die dennoch im phtml-Template nötig sind, etwa um Server-Daten an eine bereits registrierte Komponente zu übergeben, gilt die Hyvä-Regel konsequent: jeder <script>-Block wird unmittelbar danach mit $hyvaCsp->registerInlineScript() freigegeben, sonst blockiert der Browser die Ausführung. Kompilierte TypeScript-Komponenten selbst gehören dagegen als externe, über das Hyvä-Modul-System eingebundene .js-Dateien ausgeliefert, nicht als Inline-Skript - das hält die CSP schlank und macht jede Ausnahme im Code-Review sofort sichtbar.

<?php /** @var \Magento\Framework\View\Helper\SecureHtmlRenderer $hyvaCsp */ ?>
<div x-data="productConfigurator(<?= $block->escapeHtmlAttr(
    json_encode($block->getConfiguratorOptions(), JSON_THROW_ON_ERROR)
) ?>)">
    <!-- markup omitted -->
</div>

<script>
    // Only pass server data here, never define component logic inline
    window.__CONFIGURATOR_BASE_PRICE__ = <?= (float) $block->getBasePrice() ?>;
</script>
<?php $hyvaCsp->registerInlineScript() ?>

8. Typisierte Alpine-Komponenten testen

Typisierte Alpine-Komponenten lassen sich deutlich einfacher testen als ihre ungetypten x-data-Pendants, weil die Factory-Function als isolierte, reine Funktion existiert, die unabhängig von Alpine selbst aufgerufen werden kann. Mit Vitest oder Jest importiert man die Funktion direkt, ruft sie ohne DOM auf und prüft den zurückgegebenen Zustand sowie das Verhalten einzelner Methoden - kein jsdom-Setup, kein Mounten einer echten Alpine-Instanz nötig, solange die Methoden keine direkten DOM-Zugriffe über $refs enthalten.

Für Methoden, die tatsächlich mit $refs, $dispatch oder $store interagieren, hilft ein minimaler Mock-Kontext, der nur die im Test benötigten magischen Properties bereitstellt und dessen Form durch dasselbe TypeScript-Interface abgesichert wird wie die Komponente selbst - vergisst man eine Property im Mock, meldet der Compiler das sofort, statt dass der Test mit einer kryptischen Laufzeit-Exception fehlschlägt. Diese Testbarkeit ist ein unterschätzter Nebeneffekt der Typisierung: Sie zwingt zu einer saubereren Trennung zwischen reiner Logik und DOM-Interaktion.

9. Typisierungsstrategien im Vergleich

Die vier vorgestellten Ansätze, reine Factory-Functions ohne Typen, Factory-Functions mit Interface-Typisierung, JSDoc ohne Build-Step und kompiliertes TypeScript, unterscheiden sich deutlich in Aufwand, Tooling-Abhängigkeit und tatsächlich erreichter Sicherheit. Die folgende Übersicht ordnet gängige Alpine.js-Situationen dem jeweils passenden Ansatz zu und zeigt, wo ungetypte Muster in Hyvä-Projekten zum Risiko werden.

Für die meisten Hyvä-Projekte ist die Faustregel einfach: kleine, lokale UI-Toggles bleiben ungetyptes x-data, komplexere Komponenten mit mehr als vier oder fünf Properties, externen Daten oder Store-Zugriff bekommen mindestens JSDoc-Typisierung, und wirklich zustandsreiche Komponenten wie Checkout oder Produktkonfigurator rechtfertigen den kleinen Mehraufwand eines kompilierten TypeScript-Moduls. Diese abgestufte Strategie vermeidet sowohl unnötigen Tooling-Ballast in einfachen Fällen als auch unkontrollierte Komplexität in den kritischen Komponenten des Shops.

10. Zusammenfassung

Die wichtigsten TypeScript-Patterns für Alpine.js-Komponenten in Hyvä lösen alle dasselbe Grundproblem: x-data ist absichtlich ungetypt, und ab einer gewissen Komponentengröße wird das zum Risiko für Wartbarkeit und Refactoring-Sicherheit. Typisierte Factory-Functions mit AlpineComponent-Interface liefern volle Typprüfung ohne Laufzeit-Overhead. JSDoc mit checkJs bietet denselben Nutzen ganz ohne Build-Step, für Teams, die keine zusätzliche Tooling-Schicht wollen. Ein kompiliertes .ts-Pattern lohnt sich, sobald generische Typen oder komplexe verschachtelte Zustände ins Spiel kommen.

Entscheidend bleibt, dass jede dieser Strategien CSP-konform bleibt: kein eval() im Compiler-Output, keine unregistrierten Inline-Skripte, jeder notwendige Inline-Block mit $hyvaCsp->registerInlineScript() freigegeben. So lässt sich Typsicherheit gezielt dort einführen, wo sie den größten Effekt hat, ohne Hyvä's schlanke No-Build-Philosophie oder die Sicherheitsgarantien der Content-Security-Policy zu opfern.

11. FAQ: TypeScript-Patterns für Alpine.js-Komponenten in Hyvä