TypeScript Patterns for Alpine.js Components in Hyvä

1. Alpine.js x-data Is Untyped: The Risk in Larger Components

Alpine.js deliberately ships without a type system: x-data accepts an arbitrary JavaScript expression that gets evaluated at runtime, with no compiler, no type check and no autocomplete for properties or methods. A typo like open instead of isOpen does not surface while saving, it surfaces in the browser when a click handler silently does nothing. For a tiny dropdown snippet with two properties that is not a problem. Once a component grows, say a mini cart with quantity updates, AJAX calls and several $watch bindings, these blind spots add up to real bugs that only show up in production.

In Hyva projects this risk hits larger x-data blocks particularly often: checkout forms with conditional field logic, product configurators with a variant matrix, layered navigation filters with nested state. Several developers touch the same component over months, and without types every refactoring step loses its safety net: a renamed property is not flagged in red, it simply breaks in the frontend. The solution is not to force TypeScript and a full build process into every theme, but to introduce type safety exactly where components are complex enough to justify the effort.

2. Typed Component Factory Functions with Alpine.AlpineComponent

The most pragmatic entry point into typed Alpine components is a factory function that returns an object whose shape exactly matches the AlpineComponent interface from the official Alpine type definitions. Instead of writing x-data="{ open: false, toggle() { this.open = !this.open } }" directly in the markup, you define a function like function dropdown(): AlpineComponent<DropdownState> in a separate file, declare every property with an explicit type, and let the compiler check every use of this inside the methods. Wrong property access, missing return values and inconsistent method signatures become visible while writing the code, not while clicking around in the browser.

What matters is that this function stays plain JavaScript, or compiles down to plain JavaScript: Alpine itself knows nothing about TypeScript and expects an ordinary object at runtime. Type checking happens exclusively at development time, and the result is a normal Alpine.data() call with zero runtime overhead. This pattern can be introduced one component at a time, without converting the entire theme to TypeScript, which makes it ideal for Hyva projects that only want to type their most complex components.

// 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-Based Typing Without a TypeScript Build Step

Not every team wants to introduce a TypeScript build step into the Hyva pipeline, especially when Tailwind and Alpine compilation already run through the Hyva watcher and an extra tsc step feels like unnecessary complexity. JSDoc comments offer a genuine middle ground: with @param, @returns and @typedef you can annotate types directly in plain JavaScript, and modern editors like VS Code or PhpStorm evaluate these comments through their built-in TypeScript language engine. Autocomplete, type error underlining and refactoring support all work without a single .ts file or build step existing.

The trick lies in a jsconfig.json with "checkJs": true at the project root, which tells the editor to check JavaScript files as if they were TypeScript. For Alpine components you define a @typedef for the component state and reference it in the JSDoc signature of the factory function. The result is a file that stays unchanged JavaScript at runtime, but offers the same type safety as a .ts file during development, an approach that is particularly attractive for smaller teams or agency projects on a tight deployment schedule.

// 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. The Lightweight TS Pattern: A .ts File Compiled to Alpine.data()

For teams that already maintain a build pipeline for other JavaScript modules, the next level pays off: a .ts file per component that exports a typed factory function and gets compiled to a normal .js file via esbuild or tsc. That compiled file is then registered the regular way through Alpine.data('dropdown', dropdown), usually in a central entry point loaded before Alpine.start(). The decisive advantage over plain JSDoc: generic types, union types and interfaces for complex nested state can be expressed far more precisely and compactly in real TypeScript than in comment form.

What matters for Hyva projects is keeping the build step as lean as possible: a single esbuild call without bundler overhead is enough for most components and hooks easily into the existing npm workflow alongside the Tailwind build. No framework bundle, no extra vendor chunk, no runtime dependency on TypeScript in the browser. The compiled output is exactly the same lean JavaScript that Alpine expects anyway, only that it originates from a type-checked source instead of handwritten, unchecked 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. Typing Alpine Magics: $store and $dispatch

Alpine provides magic properties like $store, $dispatch, $watch and $refs that are available inside x-data expressions without any import, but the TypeScript compiler does not know them out of the box because they are not part of the regular this context of a class or object. The official Alpine type definitions solve this through interface augmentation: with a custom type declaration for the global store, $store.cart can be used as a typed object with known properties instead of being treated as any, which silently accepts every property access.

For $dispatch a typed wrapper pattern pays off: a helper function that forces the event name and payload shape as generic parameters, so a typo in the event name or a wrong payload structure surfaces at compile time instead of during a debugging session for an event that never arrives anywhere. Especially in Hyva components that communicate through custom events, such as a mini cart and product cards, this typing prevents an entire class of integration bugs that would otherwise only become visible in the browser.

6. Passing x-data JSON Attributes from phtml/PHP Type-Safely

A typical Hyva pattern is writing server-side data from the PHP block straight into the markup as an x-data argument via json_encode(), for example x-data="productConfigurator(<?= ... ?>)". This data arrives at runtime as plain JSON with no guarantee whatsoever that its structure matches the expected TypeScript interface. A changed view model output on the PHP side can silently break the frontend component, because TypeScript has no knowledge of the JSON data's shape at compile time.

The robust solution is an explicit interface for the payload coming from the server, combined with a lightweight validation at the boundary between PHP and JavaScript, for example a simple type guard function that checks the expected fields at runtime before the component uses them. That way the type annotation is not just a documenting comment, it actually catches real discrepancies between PHP output and frontend expectations, which is especially valuable when the view model and the Alpine component are maintained by different developers.

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

7. Staying CSP-Compatible: No eval, Using registerInlineScript Correctly

For security reasons Hyva enforces a strict Content Security Policy that by default allows no eval() and no unregistered inline scripts, both things that classic TypeScript tooling setups tend to rely on implicitly, such as source maps with eval-based debugging or dynamically generated code from some bundlers. For Alpine components this means: the TypeScript compiler output must never contain new Function() or eval(), and every esbuild or tsc target has to be set to a CSP-compatible output format like ES2020 without eval sourcemaps.

For inline scripts that are still needed in the phtml template, for example to hand server data to an already registered component, the Hyva rule applies consistently: every <script> block is cleared immediately afterwards with $hyvaCsp->registerInlineScript(), otherwise the browser blocks execution. Compiled TypeScript components themselves, on the other hand, belong in external .js files loaded through the Hyva module system rather than inline, which keeps the CSP lean and makes every exception immediately visible during code review.

<?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. Testing Typed Alpine Components

Typed Alpine components are considerably easier to test than their untyped x-data counterparts, because the factory function exists as an isolated, pure function that can be invoked independently of Alpine itself. With Vitest or Jest you import the function directly, call it without a DOM and check the returned state along with the behavior of individual methods, no jsdom setup and no mounting of a real Alpine instance required, as long as the methods do not directly touch the DOM through $refs.

For methods that genuinely interact with $refs, $dispatch or $store, a minimal mock context helps, one that only provides the magic properties needed for the test and whose shape is enforced by the same TypeScript interface as the component itself. Forget a property in the mock and the compiler flags it immediately, instead of the test failing with a cryptic runtime exception. This testability is an underrated side effect of typing: it forces a cleaner separation between pure logic and DOM interaction.

9. Typing Strategies Compared

The four approaches covered here, plain factory functions without types, factory functions with interface typing, JSDoc without a build step and compiled TypeScript, differ noticeably in effort, tooling dependency and the actual level of safety achieved. The table below maps common Alpine.js situations to the matching approach and shows where untyped patterns turn into a real risk in Hyva projects.

For most Hyva projects the rule of thumb is simple: small, local UI toggles stay untyped x-data, more complex components with more than four or five properties, external data or store access get at least JSDoc typing, and truly state-heavy components like checkout or a product configurator justify the small extra effort of a compiled TypeScript module. This tiered strategy avoids both unnecessary tooling weight in simple cases and uncontrolled complexity in the shop's critical components.

10. Summary

The core TypeScript patterns for Alpine.js components in Hyvä all address the same underlying problem: x-data is deliberately untyped, and past a certain component size that becomes a real risk for maintainability and refactoring safety. Typed factory functions with an AlpineComponent interface deliver full type checking with zero runtime overhead. JSDoc with checkJs offers the same benefit with no build step at all, for teams that do not want an extra tooling layer. A compiled .ts pattern pays off once generic types or complex nested state enter the picture.

What matters most is that every one of these strategies stays CSP-compliant: no eval() in the compiler output, no unregistered inline scripts, every necessary inline block cleared with $hyvaCsp->registerInlineScript(). That way type safety can be introduced exactly where it has the biggest effect, without sacrificing Hyva's lean no-build philosophy or the security guarantees of the Content Security Policy.

11. FAQ: TypeScript Patterns for Alpine.js Components in Hyvä