Hyva Checkout: the React-based checkout

Part 11 of the Hyva series — advanced storefront work. Implementation-focused, drawn from real checkout upgrades (project names withheld).

What Hyva Checkout is

The default Luma checkout is a Knockout monolith — one large uiElement graph that manages steps, payment, and shipping in the browser. Hyva Checkout replaces it with a React application driven by Magewire, Magento's Laravel-Livewire-style server-driven component framework. The browser holds a React UI; user actions travel to a PHP component that re-renders the relevant fragment.

This is a different architecture from the rest of Hyva (which is Tailwind + Alpine). It is a deliberate choice: the checkout is the most stateful, payment-sensitive surface on the store, and React's component model handles that better than Alpine would. You opt into it as a separate module.

Why teams upgrade it separately

On the migrations observed, the checkout was always its own phase, never bundled with the catalog work. Two reasons:

1. Risk concentration. Payment methods, tax, and shipping all converge at checkout. A regression here is a revenue regression, so it gets its own verification track.
2. Independent module. Hyva Checkout is versioned and upgraded on its own cadence; coupling it to the theme cutover just creates a larger blast radius.

Treat the checkout upgrade as a project inside the project.

Failure mode 1 — navigator reset breaks place order

A recurring bug: after the Hyva Checkout navigator (the step controller) reset, placing an order for a new account failed while existing accounts succeeded. The reset rebuilt the navigator state but did not restore the customer session reference the place-order action expected, so the request hit the server without the account context.

The fix lives in the navigator lifecycle: ensure the place-order handler reads the session-derived customer id at call time, not from a value captured before the reset. If you see "works for repeat customers, fails for new ones," suspect exactly this — state captured too early.

Failure mode 2 — guest checkout "rule not found"

Guest checkout surfaced a "rule not found" error during the upgrade. The cause was a cart-price-rule lookup that the Luma checkout resolved implicitly but Hyva Checkout only runs when a specific step event fired. Because guests skip account creation, that event never fired, and the rule resolver threw.

Fix: move the rule resolution to a point in the flow that both guests and logged-in customers reach, or guard the resolver so a missing rule degrades to "no discount" instead of an exception. The lesson generalizes — audit every "this only runs for logged-in users" assumption when guests are in scope.

Failure mode 3 — FPC does not render checkout JS dependencies

The full-page cache is your friend everywhere else, but the checkout's JavaScript dependencies must be present and correct on the cached HTML. A common symptom: the catalog is fast and cached, then the checkout loads broken because the cached page is missing a script the checkout needs, or the CSP blocks it.

Validate the checkout route is excluded from FPC (or that its dynamic fragments are properly hole-punched), and that the JS the React app loads is the version the server components expect. Version skew between the React bundle and the Magewire component contract is the usual root cause.

Payment methods under Magewire

Express payment options that previously hooked the Luma knockout flow now wire into the Magewire component lifecycle. The pattern is: the payment component receives the authorization result, pushes it to the server component, and the server re-renders the summary. Verify each method end-to-end — including the post-auth redirect and the order-placement callback — because each provider integrates at a different step.

Verification checklist for checkout

• Place order as a new account (not a returning customer).
• Place order as a guest, including any cart-rule path.
• Each payment method through to order confirmation.
• Checkout route correctly cached or exempted from FPC.
• No CSP violations in the console on the checkout page.
• React bundle and Magewire component versions aligned.

What's next

Hyva Checkout is the React edge of the storefront. The next post covers the other modern edge — building custom storefront components with Hyva React against the Magento GraphQL API.

Next in this series: Hyva React components and the GraphQL storefront — /blog/magento2-hyva-react-graphql