How to keep custom code and parent theme updates cleanly separated for good, instead of colliding with every release
A Hyvä update that suddenly changes the structure of the mini-cart component hits projects especially hard when the core has been copied directly in several places instead of overridden through the fallback system. This article shows how to reliably spot breaking changes in Hyvä releases, why the fallback principle structurally separates custom code from parent updates, and what testing strategy actually provides safety before a Hyvä major update.
Table of Contents
- 1. Why Hyvä updates work differently from classic Magento core updates
- 2. Consistently using the fallback principle instead of forking the core
- 3. Spotting breaking changes in Hyvä releases early
- 4. Choosing Composer version constraints deliberately
- 5. Checking Tailwind config compatibility across Hyvä updates
- 6. Keeping a Hyvä update in sync across several vendor variants of a theme
- 7. Building a testing strategy before a Hyvä major update
- 8. Preparing a clear rollback strategy for the worst case
- 9. Practical example: rolling in a Hyvä minor update with a changed mini-cart component
- 10. Summary
- 11. FAQ
1. Why Hyvä updates work differently from classic Magento core updates
A Magento core update usually touches PHP classes extended through plugins or preferences, while the actual core logic lives in the vendor directory and gets updated automatically through composer update, without directly touching any custom files. A Hyvä theme update works structurally differently, because templates, layout XML and Tailwind configuration are assembled through a fallback system across several theme layers, in which custom overrides deliberately take precedence over the parent theme.
In concrete terms: running composer update on the hyva-themes/magento2-default-theme-csp package only updates the files inside the vendor directory, while custom templates in the child theme stay untouched and may now work against a data structure or an Alpine component interface in the parent that has since changed. An update can therefore pass technically without a hitch and still be functionally broken, with Composer never reporting an error at all.
2. Consistently using the fallback principle instead of forking the core
The biggest strategic mistake in many grown Hyvä projects is copying an entire .phtml file from the parent theme into the child theme just to change a single CSS class. That turns a targeted adjustment into a full fork of the file, one that has to be manually reconciled against the original on every future parent update, because the fallback system permanently prefers the local copy from then on, even once the original has fundamentally changed.
The cleaner alternative is overriding only the smallest sensible template unit actually affected, and documenting the specific change against the original with a short comment right inside that file. If a plain CSS adjustment is all that's needed, it should ideally go through additional Tailwind classes in layout XML rather than a full copy of the .phtml file, keeping the exposure to future parent changes as small as possible.
<!-- app/design/frontend/Mironsoft/default/Magento_Checkout/layout/checkout_index_index.xml -->
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
<body>
<referenceBlock name="checkout.root">
<!-- targeted addition instead of a full template copy -->
<arguments>
<argument name="jsLayout" xsi:type="array">
<item name="components" xsi:type="array">
<item name="checkout" xsi:type="array">
<item name="children" xsi:type="array">
<item name="steps" xsi:type="array">
<item name="children" xsi:type="array">
<item name="shipping-step" xsi:type="array">
<item name="component" xsi:type="string">Mironsoft_Checkout/js/view/shipping</item>
</item>
</item>
</item>
</item>
</item>
</item>
</argument>
</arguments>
</referenceBlock>
</body>
</page>
3. Spotting breaking changes in Hyvä releases early
Hyvä publishes a changelog with every release that explicitly separates bugfixes, new features and breaking changes, with the latter usually covering changes to Alpine component names, to the structure of jsLayout components, or to the Tailwind configuration file itself. Before any planned update it pays off to deliberately read exactly that section, not just the version number, since even a seemingly small minor release occasionally ships a change flagged as breaking.
On top of that, diffing your own overridden templates against the new parent version with a simple diff tool, scoped only to files that actually exist in the local theme, helps a lot. If that diff reveals a structural change, such as a new x-data attribute or a renamed Alpine property, it's a far more reliable indicator of required work than just reading the release notes.
#!/usr/bin/env bash
# ci/diff-overridden-templates.sh
set -euo pipefail
THEME_DIR="src/app/design/frontend/Mironsoft/default"
PARENT_OLD="vendor-old/hyva-themes/magento2-default-theme-csp"
PARENT_NEW="vendor/hyva-themes/magento2-default-theme-csp"
find "$THEME_DIR" -name "*.phtml" | while read -r file; do
relpath="${file#$THEME_DIR/}"
old="$PARENT_OLD/$relpath"
new="$PARENT_NEW/$relpath"
if [ -f "$old" ] && [ -f "$new" ] && ! diff -q "$old" "$new" > /dev/null; then
echo "Parent file changed, local override affected: $relpath"
fi
done
4. Choosing Composer version constraints deliberately
A constraint that's too loose, like ^1.3 in composer.json, lets Composer jump automatically to the newest minor or patch version within the same major version on every composer update, which means a breaking change can end up in a deployment unnoticed simply because nobody deliberately reviewed that specific version bump. For a production Hyvä theme, a tighter constraint like ~1.3.2 pays off instead, allowing only patch releases automatically and turning every minor or major version into a conscious, explicit decision.
That decision then gets locked into composer.lock, which should be committed to the repository alongside composer.json, so every environment, from local development through CI to production, uses exactly the same package version. An update becomes a deliberate step visible in a pull request, instead of quietly happening in the background through an automated composer update.
5. Checking Tailwind config compatibility across Hyvä updates
A Hyvä update sometimes ships a new version of the bundled base Tailwind configuration too, with changed default colors, new design tokens, or a different structure for breakpoints, against which custom tailwind.config.js extensions no longer line up cleanly. Since Tailwind v4 increasingly expresses configuration through CSS-first directives rather than a pure JavaScript file, the fundamental structure of the config file itself can also change between two Hyvä versions.
Before an update it pays off to deliberately review the local configuration for which values are actually inherited from the parent theme and which were consciously overridden, so it's clear after the update whether a custom adjustment still applies or has been silently shadowed by a new parent definition. An automated build failure at this point would be desirable, but it rarely happens in practice, which is why manual review remains necessary.
6. Keeping a Hyvä update in sync across several vendor variants of a theme
Projects that maintain the same theme across several vendor variants, for example a Mironsoft variant and a derived Abrams variant with an identical template structure, face an extra challenge during a Hyvä update: a breaking change has to be applied to both variants at the same time, or the two theme copies drift apart in content even though they're supposed to reflect the same state. Without a clear process, the fix often lands only in whichever variant got touched first, while the second one silently sits on the old, incompatible state.
A diff script that checks not only against the new parent version, but also compares both custom theme variants against each other, reliably surfaces a divergence like that before it ever becomes visible in production. In practice it pays off to implement every adjustment from a Hyvä update as its own small commit, deliberately applied to both vendor paths back to back, instead of updating the two variants separately at different times.
7. Building a testing strategy before a Hyvä major update
A major update should fundamentally never happen directly against production, but instead first run in an isolated staging environment with a separate Composer branch that contains the update, while main stays untouched and remains deployable. In that staging environment, the same functional end-to-end suite that normally runs in the pipeline applies, complemented by visual regression tests that surface layout changes from a new parent version without having to click through every page manually.
Comparing test results side by side between main and the update branch is particularly valuable here, because a newly appearing failure can then be clearly attributed to the update, instead of being mistaken for an unrelated, time-independent regression. Only once both the functional and the visual suite pass cleanly on the update branch does a merge into main even become a consideration.
8. Preparing a clear rollback strategy for the worst case
Even a carefully tested update can surface a problem in production that stayed invisible in staging, for example because real customer data triggers an edge case synthetic test data never covers. A prepared rollback plan that documents the previous composer.lock state, the associated Git tag, and the matching static content version, significantly shortens the response time in a case like that.
Because Hyvä updates frequently also change compiled static content, that plan must include re-running the full deploy sequence from the project documentation, including clearing var/view_preprocessed and pub/static/frontend, so a rollback never accidentally leaves stale static files behind that are incompatible with the older theme version.
9. Practical example: rolling in a Hyvä minor update with a changed mini-cart component
A concrete real-world example is a Hyvä minor update that changes the internal structure of the mini-cart Alpine component to support a new, asynchronously loadable product preview. A project that had copied the entire minicart.phtml from the parent now has to manually carry that change into its own copy, while a project with a targeted layout XML override only has to check whether its own addition still hooks into the right spot in the new component structure.
In practice, that difference is exactly what separates an update that takes a few minutes from one that costs several hours of manual reconciliation. It shows why investing in a disciplined fallback approach pays off, not necessarily on the first update round of a theme project, but reliably by the third or fourth one.
| Update Type | Typical Risk | Recommended Preparation | Rollback Effort |
|---|---|---|---|
| Patch release | Usually low | Quick changelog check, update directly | Low |
| Minor release | New Alpine properties, changed defaults | Diff against custom overrides, staging test | Medium |
| Major release | Structural breaking changes possible | Full staging suite, separate branch | High without preparation |
| Tailwind config update | Changed design tokens, different structure | Deliberately review custom config values | Medium |
| Security patch | Time-critical, little lead time | Accelerated staging review, narrow focus | Low to medium |
Mironsoft
Hyvä theme development and Luma migration
Still running Luma, or a Hyvä theme that just doesn't feel right?
We build Hyvä themes for Magento from scratch or migrate existing Luma shops cleanly, with Tailwind CSS, Alpine.js, and none of the unnecessary JavaScript baggage.
Luma-to-Hyvä Migration
Move an existing shop to Hyvä in a structured way, without losing functionality.
Custom Theme Development
Build a custom Hyvä theme from scratch based on your design.
Performance Optimization
Improve Core Web Vitals and load times in the Hyvä frontend with purpose.
10. Summary
Theme Versioning and Updates in Hyvä: Key Takeaways
Fallback over forking
Targeted overrides instead of copied templates keep future updates manageable.
Deliberate constraints
Tight Composer constraints turn every minor and major update into an explicit decision.
Diff before every update
Comparing custom overrides against the new parent version reveals real adjustment needs.
Staging before production
Functional and visual tests on a staging branch prevent surprises after the merge.