Porting Luma Modules to Hyvä: Process, Effort, Practice

1. Porting or a Compatibility Module: Drawing the Line

Before starting to make a third-party module Hyvä compatible, it is worth asking whether a full port is even the right path. A compatibility module that isolates Luma assets or provides a simple fallback rendering is enough as a stopgap when the module is rarely used, will soon be replaced anyway, or the vendor is already working on a native Hyvä version. Whether Luma remnants need to be removed at all is a separate audit question, touched on only briefly here on purpose.

Anyone running a module permanently, who cares about performance and strict CSP compliance, or who wants to heavily customize the frontend, cannot avoid a genuine port. That is exactly what this article covers: the concrete process for porting Luma modules to Hyvä, from the initial audit through template translation to CSP hardening, along with realistic effort estimates for different module types.

2. Audit Phase: Identifying Templates, Knockout Bindings and Widgets

The first step in making a module Hyvä compatible is a complete inventory. Skipping this audit almost guarantees you will underestimate the effort, because Knockout bindings and RequireJS widgets are often buried deep inside nested UI component configurations. The goal is a list of every .html template, every data-bind attribute, every ko.observable call and every RequireJS widget definition that exists in the third-party module's frontend.

The search is best done directly in the module directory with targeted grep commands. It is important to cover view/frontend/web/template, view/frontend/layout and view/frontend/requirejs-config.js alike, since Knockout templates, layout bindings and widget registrations live in different places. Anyone who does this audit carefully before porting Luma modules to Hyvä avoids nasty surprises halfway through the implementation.

#!/usr/bin/env bash
# audit-luma-module.sh - find Knockout bindings, observables and RequireJS widgets
# in a third-party Luma module before porting it to Hyvä
set -euo pipefail

MODULE_DIR="app/code/Vendor/ThirdPartyModule"

echo "=== Knockout templates (.html) ==="
find "$MODULE_DIR" -path "*/web/template/*" -name "*.html"

echo "=== data-bind attributes ==="
grep -rn "data-bind=" "$MODULE_DIR" --include="*.html" --include="*.phtml"

echo "=== ko.observable / ko.observableArray usage ==="
grep -rn "ko\.observable\|ko\.computed\|ko\.observableArray" "$MODULE_DIR" --include="*.js"

echo "=== RequireJS widgets (jQuery UI widget factory) ==="
grep -rln "define(\['jquery'" "$MODULE_DIR" --include="*.js" \
  | xargs grep -l "widget(" || true

echo "=== UI Component XML declarations ==="
find "$MODULE_DIR" -path "*/ui_component/*" -name "*.xml"

echo "=== knockout templates referenced from layout XML ==="
grep -rn "Magento_Ui/js/lib/knockout\|uiComponent" "$MODULE_DIR" --include="*.xml"

3. Translating Knockout Templates into Alpine.js phtml

The core of making any module Hyvä compatible is translating the Knockout templates. An .html template with data-bind="visible: isActive" becomes a .phtml template with x-show="isActive". Important: Alpine.js works directly against the DOM instead of through a virtual bindings layer, so the state logic moves entirely into an x-data definition on the root element, instead of being loaded through a separate Knockout view model.

Foreach bindings become x-for with a <template>, click bindings become @click, text bindings become x-text. The biggest shift concerns the data source: where Knockout loaded values into observables via AJAX, Alpine.js reads the initial data directly from PHP via json_encode() in the template and enriches it with fetch() as needed. Anyone porting Luma modules to Hyvä should document this translation template by template, so later reviews stay traceable.

<!-- BEFORE: Knockout/UI-Component template (view/frontend/web/template/widget.html) -->
<div data-bind="visible: isActive, css: { 'is-loading': isLoading() }">
  <span data-bind="text: itemCount"></span>
  <ul data-bind="foreach: items">
    <li data-bind="click: $parent.selectItem, text: label"></li>
  </ul>
  <button data-bind="click: loadMore, enable: !isLoading()">Load more</button>
</div>

<!-- AFTER: native Hyvä phtml with Alpine.js -->
<?php /** @var \Magento\Framework\View\Element\Template $block */ ?>
<div x-data="thirdPartyWidget()" x-init="init()" :class="{ 'is-loading': isLoading }">
  <span x-text="itemCount"></span>
  <ul>
    <template x-for="item in items" :key="item.id">
      <li @click="selectItem(item)" x-text="item.label"></li>
    </template>
  </ul>
  <button @click="loadMore()" :disabled="isLoading">Load more</button>
</div>

4. Replacing RequireJS Widgets with Alpine Components

Besides templates, many third-party modules ship RequireJS widgets built on the jQuery UI widget pattern ($.widget(...)). To fully make a module Hyvä compatible, these widgets need to be replaced with Alpine components registered via Alpine.data(...). The structure stays similar: options become reactive properties, widget methods become Alpine methods, and initialization happens through init() instead of _create().

One important difference: RequireJS widgets attach to arbitrary DOM elements via a selector, while Alpine components are anchored declaratively via x-data in the template. Events the widget previously fired via this._trigger(...) become $dispatch(...) calls with their own namespace, so they do not collide with Hyvä core events. Anyone porting Luma modules to Hyvä should document every widget option explicitly as an Alpine property, so the translation stays complete.

// BEFORE: RequireJS / jQuery UI widget factory
define(['jquery', 'jquery/ui'], function ($) {
  'use strict';
  $.widget('vendor.thirdPartyWidget', {
    options: { autoRefresh: true, refreshInterval: 5000 },
    _create: function () {
      this.isLoading = false;
      this._bindEvents();
      if (this.options.autoRefresh) {
        this._startPolling();
      }
    },
    _bindEvents: function () {
      this.element.on('click', '.js-refresh', $.proxy(this._refresh, this));
    },
    _refresh: function () {
      this.isLoading = true;
      this._trigger('refreshStart');
      // ... ajax call ...
    }
  });
  return $.vendor.thirdPartyWidget;
});

// AFTER: Alpine.js component registered via Alpine.data
document.addEventListener('alpine:init', () => {
  Alpine.data('thirdPartyWidget', (autoRefresh = true, refreshInterval = 5000) => ({
    isLoading: false,
    autoRefresh: autoRefresh,
    refreshInterval: refreshInterval,

    init() {
      if (this.autoRefresh) {
        this.startPolling();
      }
    },
    refresh() {
      this.isLoading = true;
      this.$dispatch('vendor:refresh-start');
      // ... fetch call ...
    },
    startPolling() {
      setInterval(() => this.refresh(), this.refreshInterval);
    }
  }));
});

5. Migrating LESS/CSS to Tailwind Utilities

Once templates and widgets are ported, styling remains. Third-party modules usually bring their own LESS files, which are neither loaded nor needed in the Hyvä theme. To consistently make a module Hyvä compatible, LESS classes get replaced with Tailwind utility classes directly in the template. Custom CSS rules with fixed color values, spacing and breakpoints disappear almost entirely in favor of utility classes like flex, gap-4 or rounded-lg.

@apply should be used sparingly, only for truly recurring component patterns that appear identically in many places. For everything else: utility classes directly in the markup are the preferred approach in Tailwind CSS v4, because they require no extra CSS file and the build process automatically purges unused classes. Anyone porting Luma modules to Hyvä should delete the old LESS file only after all classes in the template have been replaced, to avoid accidental leftover dependencies.

/* BEFORE: module LESS file (view/frontend/web/css/source/_widget.less) */
.vendor-widget {
  display: flex;
  gap: 16px;
  padding: 24px;
  border-radius: 8px;
  background-color: #f8fafc;
  border: 1px solid #e2e8f0;
}
.vendor-widget__title {
  font-size: 18px;
  font-weight: 700;
  color: #0f172a;
  margin-bottom: 8px;
}
.vendor-widget.is-loading {
  opacity: 0.5;
  pointer-events: none;
}

/* AFTER: equivalent Tailwind utility classes used directly in the phtml template */
/* <div class="flex gap-4 p-6 rounded-lg bg-slate-50 border border-slate-200"
        :class="{ 'opacity-50 pointer-events-none': isLoading }">
     <p class="text-lg font-bold text-slate-900 mb-2">...</p>
   </div> */

/* @apply used sparingly, only for a truly repeated pattern */
.widget-card {
  @apply flex gap-4 p-6 rounded-lg bg-slate-50 border border-slate-200;
}

6. Forms and Validation Without Knockout

Many third-party modules ship their own forms whose validation runs entirely through Knockout computed observables. To make a form Hyvä compatible, that logic is replaced with native HTML5 validation (required, pattern, minlength) combined with Alpine.js x-data for dynamic behavior such as conditional fields or live feedback. This drastically reduces JavaScript code, since the browser takes over most of the validation logic itself.

For cases that go beyond native validation, such as server-side checks or complex field dependencies, Alpine.js takes over the orchestration: an x-data object holds the form state, @submit.prevent intercepts submission, checks form.checkValidity() and shows custom error messages as needed. This combination is noticeably more robust for forms being ported to Hyvä than trying to rebuild Knockout validation one to one.

<?php /** @var \Magento\Framework\View\Element\Template $block */ ?>
<form x-data="thirdPartyForm()" @submit.prevent="submitForm($event)" novalidate>
  <div class="mb-4">
    <label class="block text-sm font-semibold mb-1" for="vendor_email">Email</label>
    <input
      id="vendor_email"
      type="email"
      name="vendor_email"
      class="border rounded-lg px-3 py-2 w-full"
      required
      x-model="email"
      :class="{ 'border-red-500': errors.email }"
    >
    <p class="text-red-600 text-xs mt-1" x-show="errors.email" x-text="errors.email"></p>
  </div>

  <div class="mb-4" x-show="requiresPhone">
    <label class="block text-sm font-semibold mb-1" for="vendor_phone">Phone</label>
    <input id="vendor_phone" type="tel" name="vendor_phone" class="border rounded-lg px-3 py-2 w-full"
           pattern="[0-9+ ]{6,}" x-model="phone" :required="requiresPhone">
  </div>

  <button type="submit" class="bg-orange-600 text-white font-semibold px-4 py-2 rounded-lg" :disabled="isSubmitting">
    Submit
  </button>
</form>

<script>
document.addEventListener('alpine:init', () => {
  Alpine.data('thirdPartyForm', () => ({
    email: '',
    phone: '',
    requiresPhone: false,
    isSubmitting: false,
    errors: {},
    submitForm(event) {
      if (!event.target.checkValidity()) {
        event.target.reportValidity();
        return;
      }
      this.isSubmitting = true;
      // ... fetch to controller endpoint ...
    }
  }));
});
</script>

7. Ensuring CSP Compliance

Hyvä runs by default under a strict Content Security Policy, and every remaining inline <script> must be registered for it. Anyone trying to make a module Hyvä compatible must not forget this step: directly after every inline script block comes a call to $hyvaCsp->registerInlineScript() in the .phtml template. Without this registration the browser blocks the script and the Alpine component never initializes, which usually only becomes obvious late in testing.

For scripts coming from the original third-party module that use inline event handlers like onclick="...", registration alone is not enough: those attributes need to be converted to @click directives first, because CSP blocks inline event handlers outright, regardless of nonce or hash. For third-party scripts that cannot be removed, such as an external tracking snippet, a hash list in csp_whitelist.xml is usually used instead of a nonce, since nonces change on every request and are unsuitable for static external assets.

8. Effort Estimation: Small, Medium, Large

The effort to make a module Hyvä compatible depends almost entirely on how much state logic and how many interactions the frontend contains, not on the raw amount of code. A pure display widget with no forms of its own and no AJAX loading usually lands at 0.5 to 1.5 person-days: translate the template, migrate the styles, register CSP. A module of medium complexity with a form, client-side validation and one AJAX request realistically moves between 2 and 4 person-days.

Complex modules with checkout integration, several interlinked UI components, or a dashboard with multiple views often land at 5 to 10 person-days or more. The strongest cost drivers are: the number of nested Knockout bindings per template, hidden dependencies on Magento_Ui components, server-side endpoints that also need adjustment, and missing or outdated documentation of the third-party module. Anyone porting Luma modules to Hyvä should use the audit from section 2 to count these factors concretely before estimating, instead of guessing from the code volume alone.

9. Comparison Table: Time and Risk by Module Type

The table below classifies typical third-party module types by time effort, risk and recommended approach. It does not replace an individual estimate, but gives a solid first orientation before deciding to port a specific module to Hyvä.

It is notable that risk and effort almost always rise together once a module touches checkout processes or synchronizes multiple UI components. In these cases, a short proof of concept on a single, isolated component is worth doing before the full port, to validate actual complexity before the full effort gets budgeted.

10. Summary

Making a third-party module Hyvä compatible is a clearly structured process, not a black-box project: first a clean audit of every Knockout binding, RequireJS widget and LESS file. Then templates get translated step by step from data-bind to x-show/x-for/x-text, widgets move from $.widget(...) to Alpine.data(...), and styles switch from custom LESS rules to Tailwind utilities. Forms use native HTML5 validation combined with Alpine.js for dynamic behavior. Every remaining inline script gets secured with $hyvaCsp->registerInlineScript().

The effort of porting Luma modules to Hyvä depends mostly on the amount of state logic and interactions involved: from half a day for a pure display widget to several weeks for a complex checkout feature with multiple UI components. A short proof of concept before the full port helps calibrate the effort estimate realistically, instead of estimating from raw code volume alone.

11. FAQ: Porting Luma Modules to Hyvä