Hyvä Theme Support

This article describes how the LS Central Magento extension supports running your storefront on a Hyvä theme: prerequisites, how to install and configure the Hyvä theme, which storefront flows are supported, how checkout is handled, feature parity with Luma, and troubleshooting.

In this article

1. Overview

2. Prerequisites and compatibility

3. Installing and configuring the Hyvä theme

4. Supported storefront flows on Hyvä

5. Checkout on Hyvä

6. Hyvä vs Luma — feature parity

7. How data flows: Hyvä → Magento → LS Central

8. Troubleshooting & FAQ

9. Known limitations

1. Overview

Hyvä is a modern, lightweight Magento frontend theme built on Alpine.js and Tailwind CSS with a minimal-JavaScript approach. It replaces the heavy Luma/Knockout/RequireJS stack with server-rendered markup and small Alpine components, giving significantly faster, simpler storefronts.

The LS Central Magento extension supports running your storefront on a Hyvä theme. The extension modules ship Hyvä-aware templates and styles that activate automatically when a Hyvä theme is installed, so LS Central catalog, cart, loyalty, gift card and customer-account features render correctly in the Hyvä frontend — while continuing to synchronise orders with LS Central.

Who this is for

• Merchants running — or evaluating — a Hyvä storefront.

• Implementation partners setting up the LS Central Magento extension on a Hyvä theme.

What LS Retail provides

LS Retail distributes the extension packages only — the LS Central Magento extension (lsmag-two) and the Hospitality add-on. LS Retail does not ship a Hyvä theme; you install and maintain your own Hyvä theme (the Hyvä default theme or your child theme). The extension’s Hyvä templates and Tailwind styles compile into whatever Hyvä theme you run.

Note  Hyvä theme licences are obtained from Hyvä Themes, separately from LS Central. See hyva.io for licensing and installation of the theme itself.

2. Prerequisites and compatibility

3. Installing and configuring the Hyvä theme

The LS Central Magento extension is installed and connected to LS Central exactly as on a Luma storefront — that process is unchanged by Hyvä and is covered by the standard LS Central Magento setup documentation. What is specific to a Hyvä storefront is installing and configuring the Hyvä theme itself. The Hyvä theme is a commercial product supplied by Hyvä Themes; the steps below summarise the Hyvä-side setup — always follow Hyvä’s own documentation for the definitive procedure.

Hyvä documentation  Registration & licensing: https://www.hyva.io/ · Installation & configuration guide: https://docs.hyva.io/

3.1 Register and license Hyvä for your domain

• Create an account: register at https://www.hyva.io/.

• Add a licence for your domain: in the Hyvä customer portal, add/activate a Hyvä theme licence for the domain(s) the storefront runs on.

3.2 Configure Composer access to the Hyvä repository

Hyvä packages are delivered through a private Composer (Packagist) repository tied to your licence. Add the repository and authenticate with the token from your Hyvä account:

# Add the Hyvä private Composer repository
composer config repositories.hyva composer https://hyva-themes.repo.packagist.com/<your-account>/

# Authenticate (token from your Hyvä account)
composer config --auth http-basic.hyva-themes.repo.packagist.com token <your-token>

Note  The repository URL and token are issued per Hyvä account/licence in the Hyvä portal. Keep the auth token in auth.json (or an environment variable) — never commit it to source control.

3.3 Install the Hyvä theme packages

Install the CSP-compatible Hyvä default theme and the theme-fallback module:

composer require hyva-themes/magento2-default-theme-csp
composer require hyva-themes/magento2-theme-fallback

bin/magento setup:upgrade
bin/magento setup:di:compile

• magento2-default-theme-csp: the Hyvä default theme (Content-Security-Policy compatible), the parent for your Hyvä storefront theme.

• magento2-theme-fallback: lets pages not implemented in Hyvä fall back to the Luma theme. This is what serves the checkout in this integration (see 5. Checkout on Hyvä).

Then set your Hyvä theme as the active storefront theme in Admin under Content > Design > Configuration (or create a child theme of Hyvä/default-csp and activate it).

3.4 Generate the Hyvä config and build the theme CSS

The LS extension’s Hyvä styles live in each module’s view/frontend/tailwind/module.css and are compiled into the Hyvä theme’s single global styles.css — not loaded as a separate CSS request. Each LS module registers itself with the Hyvä Tailwind build automatically (via an observer on the hyva_config_generate_before event), so no manual hyva.config.json editing is required. Generate the config and rebuild the theme CSS:

bin/magento hyva:config:generate        # registers the LS modules (automatic)

# In your active Hyvä theme directory:
cd app/design/frontend/<Vendor>/<theme>/web/tailwind
npm install                             # first time only (Node 20)
npm run build                           # compiles styles.css

bin/magento setup:static-content:deploy
bin/magento cache:flush

Important  setup:upgrade and setup:static-content:deploy alone do NOT compile Tailwind. If LS components (loyalty tiles, stores page, cart discounts, hospitality modifiers) appear unstyled, the theme’s Tailwind build has not been run, or hyva:config:generate was not run before it.

Tip  In developer mode, static-content:deploy can skip an unchanged output path. If a rebuilt styles.css is not published, delete pub/static/frontend/<Vendor>/<theme>/<locale>/css/styles.css and redeploy.

3.5 LS Central connection is unchanged

Connecting the storefront to LS Central (connection settings, replication jobs, web store, store and terminal setup) is identical to a Luma deployment and is not affected by Hyvä. Follow the standard LS Central Magento connection and replication setup. Hyvä affects only how the storefront renders, not how it communicates with LS Central.

4. Supported storefront flows on Hyvä

The following LS Central features are validated on the Hyvä frontend. Each renders through the extension’s Hyvä templates (Alpine.js/Tailwind) and activates only when a Hyvä theme is active.

4.1 Catalog (product listing and detail)

• Pricing and stock: LS Central prices and inventory display on product listing and detail pages.

• Promotions / proactive discounts: LS Central proactive discounts and applicable coupons are shown on the product detail page.

• Availability & return policy: Product availability and return-policy information render on the Hyvä PDP.

4.2 Cart and mini-cart

• Add / update / remove: Cart operations work on Hyvä; totals reflect LS Central calculations.

• Strike-through discount price: Discounted prices display correctly in the mini-cart (drawer) and on the cart page.

• Coupon recommendations: Recommended coupons are shown and can be applied under Apply Discount Code.

• Loyalty points: Available loyalty points are shown and can be applied via the loyalty points component.

• Gift card: Gift cards can be applied via the Apply Gift Card component; gift-card balance lookup is available.

• Order summary: Applied coupon discount, loyalty points, gift card and voucher amounts appear as separate lines in the order summary.

Note  These behaviours apply to the Hyvä frontend only; existing Luma behaviour is unchanged.

4.3 Customer account and orders

• Registration & login: LS Central member registration and login render on Hyvä.

• Loyalty / club area: Loyalty offers — general offers, member offers, point offers and coupons — render in the account area.

• Order listing: The order history page renders correctly on Hyvä, with View Order and Reorder actions.

• Order detail: Individual order view, including invoices and shipments.

• Order cancellation: Cancellable orders can be cancelled from the order list and order view.

• Refunds / credit memos: The refund/credit-memo view shows the correct returned items, totals and return ID.

4.4 Miscellaneous pages

• Stores page & link: the stores page and its footer link render in the Hyvä frontend.

• Gift Card balance check page & link: the gift card balance check page and its footer link render in the Hyvä frontend.

4.4 Hospitality

For hospitality deployments, the Hospitality add-on (3.1) ships dedicated Hyvä templates and layouts, so the following render correctly on the Hyvä storefront:

• Product modifiers / customizable options: hospitality modifiers render on the Hyvä product detail page using Hyvä-compatible option templates (replacing the Luma-era swatch / options-modal markup).

• Kitchen information: kitchen status/information appears on the order success page and on customer order views.

• Kitchen status page & link: the kitchen-status page and its footer link render in the Hyvä frontend.

Note  Hospitality Hyvä rendering activates only when a Hyvä theme is installed; the hospitality module.css compiles into the theme’s styles.css via the same Tailwind build step (3. Installing and configuring the Hyvä theme). Under Luma, the existing hospitality templates are unchanged.

5. Checkout on Hyvä

Everything provided by the Hyvä open-source theme is supported by the LS Central extension. Checkout, however, is a special case: Hyvä Checkout is a separate, commercial (non-open-source) product and is not part of the open-source Hyvä theme, so it is not covered by this integration. Instead, the storefront uses the standard Magento (Luma) checkout, served through the Hyvä theme-fallback mechanism (the magento2-theme-fallback module from 3. Installing and configuring the Hyvä theme).

What this means in practice:

• Order placement works: Customers complete purchase through the Luma checkout; LS totals match Magento totals and payment methods work as expected.

• Orders sync to LS Central: Placed orders are created in LS Central; data is consistent between Magento and LS Central, and failures are logged and handled.

• Appearance: The checkout step renders with the Luma checkout UI (via theme fallback), not the Hyvä look-and-feel.

• Checkout-step LS components: Checkout-only features such as Tips/gratuity remain on the Luma checkout and are not reimplemented as Hyvä (Alpine) components.

Note  POS Data Entry Voucher amounts are surfaced in the Hyvä cart/order-summary totals; voucher/tip entry at the checkout step follows the Luma-fallback checkout.

5.1 Enabling the Luma checkout fallback (Admin configuration)

The Luma checkout fallback is provided by the magento2-theme-fallback module and must be enabled and pointed at the checkout routes in the Magento Admin. In the Admin, go to:

Stores > Configuration > HYVÄ THEMES > Theme Fallback > General Settings

Configure the following:

• Enable: set to Yes (config path hyva_theme_fallback/general/enable — disabled by default).

• Theme full path: select the fallback theme, Magento Luma (default frontend/Magento/luma).

• Apply fallback to requests containing: add the checkout (and payment) route fragments the fallback should apply to. For the standard Luma checkout, add:

checkout/index
paypal/express/review
paypal/express/saveShippingMethod
# add any additional routes your payment/shipping methods use

Important  Flush the page cache after changing these settings for them to take effect (bin/magento cache:flush).

5.2 LS Central components at the checkout step

Because checkout runs on the Luma theme via fallback, the following LS Central checkout-step components operate through the Luma checkout (they are not reimplemented as Hyvä/Alpine components). They continue to function and to communicate with LS Central as on a Luma storefront:

• Click & Collect: in-store pickup / collection selection at checkout.

• Delivery & pick-up date management: selection of delivery and pick-up dates.

• POS Data Entry: POS data entry / voucher handling at the checkout step.

• Loyalty points: applying loyalty points during checkout.

• Destination-based address: destination/address handling for the order.

• Pre-order validation: stock validation and discount validation performed before the order is placed.

6. Hyvä vs Luma — feature parity

Use this table to assess fit before adopting Hyvä with LS Central. “Luma fallback” means the feature is served by the Luma theme through Hyvä’s fallback, not reimplemented in Hyvä.

7. How data flows: Hyvä → Magento → LS Central

The integration architecture is unchanged from Luma — LS Central remains the system of record for items, prices, inventory, members/loyalty and orders. Hyvä changes only the presentation layer. Two channels connect Magento and LS Central:

• Replication (batch): Master data (items, prices, inventory, categories, stores, discounts) is pulled from LS Central on a schedule and stored in Magento.

• Runtime (real time): Baskets, loyalty, gift cards, login and order placement call LS Central at request time.

Hyvä-specific presentation notes:

• Server-rendered + Alpine: LS data is rendered server-side into Hyvä templates and hydrated by small Alpine.js components — there are no Knockout/RequireJS UI components on Hyvä pages.

• AJAX endpoints: Interactive cart features (proactive discounts, coupon recommendations, voucher / POS data entry) use dedicated Hyvä AJAX controllers and the extension’s GraphQL resolvers rather than Luma’s Knockout components.

• Checkout: Because checkout uses the Luma fallback, the checkout-step data flow to Magento and LS Central is the existing Luma flow.

Difference vs Luma  The runtime data flow to LS Central is the same on both themes. The only Hyvä difference is the frontend rendering technology (Alpine/Tailwind vs Knockout/RequireJS) for the storefront pages listed in 4. Supported storefront flows on Hyvä.

8. Troubleshooting & FAQ

LS components (loyalty tiles, stores page, cart discounts) appear unstyled.

The Hyvä theme’s Tailwind build has not been run, or hyva:config:generate was not run before it. Run hyva:config:generate, then npm run build in the theme’s web/tailwind directory, then setup:static-content:deploy and cache:flush.

I rebuilt styles.css but the storefront still looks the same.

In developer mode, static-content:deploy can skip an unchanged path. Delete pub/static/frontend/<Vendor>/<theme>/<locale>/css/styles.css and redeploy, then clear the full-page cache.

The checkout page doesn’t look like Hyvä.

Expected. Checkout uses the Luma theme via Hyvä fallback; there is no Hyvä-native checkout in this integration. Order placement and LS Central sync still work.

Customer order listing page is blank on Hyvä.

Ensure the LS extension is at 3.1 or later and the Hyvä config/build steps have been run; the Hyvä order-listing templates activate only when a Hyvä theme is active.

Do I need to edit hyva.config.json to add the LS modules?

No. The LS modules register themselves with the Hyvä Tailwind build automatically via the hyva_config_generate_before observer.

9. Known limitations

• Checkout is not Hyvä-native: the Luma checkout is used via theme fallback; Hyvä Checkout (React) is not part of this integration.

• Merchant-supplied theme: LS Retail does not ship a Hyvä theme; you obtain, license and maintain your own Hyvä theme and its Tailwind build (3. Installing and configuring the Hyvä theme).

• Version: Hyvä support is introduced in extension version 3.1; earlier versions do not ship the Hyvä templates.