The Hyvä Tailwind v3 to v4 Upgrade Field Guide

Upgrading a Hyvä storefront to Tailwind v4 is definitely not a simple npm update. In fact, it’s one of those upgrades that looks deceptively easy right up until you actually run it. Starting with Hyvä 1.4+, the entire frontend foundation changes a lot. PostCSS and tailwind.config.js are not exist. The old pipeline is replaced by the new Tailwind engine. Everything moves into CSS via @theme and hyva-tokens.

If you have an existing theme with custom components, plugins, or overrides, you can’t just blindly bump the dependency and hope for the best.

Hyvä and Tailwind tools

Don’t manually rewrite hundreds of templates. Hyvä and Tailwind provide automated tooling for the heavy lifting.
Hyvä has Hyvä Upgrade Helper Tools Hyvä publishes an official dev package to automate the folder scaffolding, config conversion, and template analysis.

composer require --dev hyva-themes/upgrade-helper-tools:dev-main
It exposes three key scripts inside ./vendor/bin/:

./vendor/bin/convert-to-tailwind-v4.js <path-to-theme>

Backs up your old web/tailwind directory and copies over the clean Tailwind v4 from the Hyvä Default Theme (1.4.0+).

./vendor/bin/convert-tailwind-config.js

Reads your old tailwind.config.js and converts your extended colors, spacing, and breakpoints into standard CSS custom properties under web/tailwind/generated/tailwind.config.css.

Scans your .phtml and layout.xml files for removed/renamed classes (e.g., flex-grow, bg-opacity-*) and writes a tailwind-deprecated-report.md.

./vendor/bin/find-deprecated-classes.js
./vendor/bin/find-deprecated-classes.js --console
./vendor/bin/update-to-tailwind-v4.js <path-to-theme>

Runs all three scripts sequentially in one shot.

Also exist npx @tailwindcss/upgrade, please use with caution. Tailwind’s official migration tool handles template rewrites (shadow-sm → shadow-xs, !flex → flex!).

Run it targeting only your template directories, not your entire theme root (otherwise it will mangle Hyvä’s custom tailwind-source.css and hyva-modules imports).

npx @tailwindcss/upgrade --source "../../**/*.phtml"

The most safe tool if you have custom and old project is Hyvä Fallback CSS. If you are working with an older store, you almost certainly have custom modules you simply do not have time to rewrite right now. The @hyva-themes/hyva-modules package includes a css/fallback.css file specifically for this. It restores the dropped Tailwind v2 and v3 utility classes back into your build, so your existing templates keep working while you plan the refactoring.

What You Must Pay Attention To

Tailwind v4 @source engine reads your .gitignore to prevent scanning unnecessary folders.
Common Magento .gitignore setups use an inverted whitelist rule. Tailwind assumes vendor/ is ignored. It silently skips scanning vendor/hyva-themes/magento2-default-theme and all vendor module templates. Checkout, account, and base components can lose all Tailwind classes, but the build succeeds without error.

Switch to an explicit deny-list .gitignore can resolve this issue.

Also if you have third-party Hyvä modules they can be crashing the build. Older Hyvä modules ship with their own CSS loaded via PostCSS @import "path/file.css“ or contain @screen md {} blocks.

Tailwind v4 throws a fatal error on bare imports (non-./ paths) and @screen rules.

You don’t need to fork the module. Exclude its CSS and keep scanning its templates via hyva.config.json:

JSON
{
  "tailwind": {
    "exclude": [
      {
        "module": "Vendor_LegacyModule",
        "keepSource": true
      }
    ]
  }
}

Then rewrite that module’s small custom CSS file inside your theme’s web/tailwind/components/.

Also often you can have issue with some of the styles. F.e. in v3, border had a default gray color #e5e7eb. In v4, it defaults to currentColor. A plain <div class="border"> on white cards with black text will suddenly get a harsh, pure black border.

Ring in v3 gave a 3px blue outline. In v4, naked ring is 1px currentColor. Form inputs and focus triggers will look thin or invisible.

In Tailwind v3, dynamic class names constructed inside Alpine x-data or PHP conditions often survived if whole strings appeared in .phtml. Because v4 uses source by default in Hyvä and relies on strict @source paths, classes evaluated dynamically will fail to generate.

But as a fix you can safelist them in tailwind-source.css using the inline source directive

@source inline("grid-cols-1 grid-cols-2 grid-cols-3 grid-cols-4");

My migration experience

Start with estimation. If this is a big custom project and you have enought time to check all custom modules please include it. If you are focused on upgrade and keep main styles but without spend a lot of time you can use fallback approach.

Run the Upgrade Helper & Update Dependencies for your theme.

Generate your hyva.config.json file and add your custom colors and dimensions from your old tailwind.config.js intohyva.config.json

Verify Your tailwind-source.css. Ensure your main entrypoint matches the 1.4+ architecture. To be sure that you haven’t miss anything, you can run the scanner.

./vendor/bin/find-deprecated-classes.js

Open tailwind-deprecated-report.md and address the high-priority hits in your custom theme templates.

bg-opacity-* \rightarrow bg-*/<percentage> (e.g. bg-black/50)   

flex-grow should be grow, flex-shrink change to shrink, overflow-ellipsis will be text-ellipsis if you have importat it should stay f. e !block to block!.

Run build and compare the design that was before. Look specifically at form input focus outlines, card drop-shadows, divider borders between list items.