Upgrading a Magento 2 store with Hyvä Themes can sometimes feel difficult, especially when major frontend technologies like Tailwind CSS or Alpine.js change versions.
Updating files manually takes time and also increases the chances of mistakes.
To simplify this process, Hyvä provides a package called hyva-themes/upgrade-helper-tools. It includes several command-line scripts that help developers automate theme upgrades and reduce manual work.
In this blog, we will explore how the Hyvä theme upgrade helper tool works and how to use it.
What Are Hyvä Upgrade Helper Tools?
The hyva-themes/upgrade-helper-tools package is a set of scripts designed to help developers upgrade custom Hyvä themes more easily.
These tools help with:
- Tailwind CSS upgrades
- Alpine.js migrations
- Finding deprecated classes
- Updating theme configuration files
- Reducing manual code changes
Instead of checking every file one by one, the scripts automate most of the upgrade work.
Important Note Before Using the Tools
These scripts should only be used in a development environment.
Do not run them directly on a live production server.
Before deploying changes:
- Review all updated files properly
- Test the frontend carefully
- Commit changes to version control
This helps avoid unexpected issues on the live website.
Install the Hyvä Upgrade Helper Tools
You can install the package using Composer.
Run the following command from your Magento root directory:
composer require --dev hyva-themes/upgrade-helper-tools:dev-main
You can also install it globally using Composer if needed.
Upgrading Tailwind from CSS v3 to v4
If you are upgrading to Hyvä 1.4.0 or later, you also need to migrate Tailwind CSS from version 3 to version 4.
Hyvä provides a simple wrapper script that runs all required upgrade steps automatically.
./vendor/bin/update-to-tailwind-v4.js <path-to-your-theme>
This command handles most of the migration work for you.
The wrapper script actually runs multiple scripts internally. You can also run them separately if you want better control over the upgrade process.
Step 1: Update Tailwind Core Files
This script:
- Creates a backup of your current Tailwind folder
- Copies the latest Tailwind v4 structure into your theme
Command:
./vendor/bin/convert-to-tailwind-v4.js <path-to-your-theme>
This helps prepare your theme for Tailwind v4 compatibility.
Step 2: Convert Tailwind Configuration
In Tailwind CSS v4, configuration handling changed significantly.
Earlier versions used:
tailwind.config.js
Now Tailwind v4 mainly uses CSS variables.
This script converts your old configuration automatically.
Command:
./vendor/bin/convert-tailwind-config.js <path-to-your-tailwind.config.js> <path-to-your-theme/web/tailwind>
After running the command, a new CSS configuration file is generated.
You will then need to manually import it into:
tailwind-source.css
Step 3: Find Deprecated Tailwind Classes
Tailwind v4 removes or renames several old utility classes.
For example:
- bg-opacity-25
- flex-grow
This script scans your theme files and generates a report showing deprecated classes and their locations.
Command:
./vendor/bin/find-deprecated-classes.js <directory-to-scan>
After execution, you will get a detailed report file named:
tailwind-deprecated-report.md
This makes it much easier to identify outdated code.
Example: Running the Tailwind v4 Upgrade
Suppose your custom theme is located at:
app/design/frontend/Custom/theme
You can run:
./vendor/bin/update-to-tailwind-v4.js app/design/frontend/Custom/theme
This command will:
- Update Tailwind structure files
- Convert configuration
- Prepare your theme for Tailwind v4
After that, you can review the deprecated classes report and update the remaining code.
Other Useful Upgrade Scripts
The package also includes tools for older migrations and additional Hyvä components.
Hyvä CMS Migration Script
Used for updating CMS component configuration files.
./bin/hyva-cms-0.6.0-migrate-children-field.js [path/to/components.json]
Alpine.js CSP Helper
Helps update Content Security Policy settings during Alpine.js upgrades.
./bin/hyva-csp-helper […DIRECTORY] | tee CSP-migration.md
Legacy Tailwind & Alpine Migration Tool used for upgrading:
- Tailwind CSS v2 to v3
- Alpine.js v2 to v3
./bin/hyva-1.2.0-tailwind-and-alpine.js <directory-to-scan>
Conclusion
The hyva-themes/upgrade-helper-tools package simplifies and speeds up Hyvä theme upgrades. Instead of manually updating many files, developers can use automated scripts to handle most of the work. It also helps make Tailwind CSS and Alpine.js upgrades easier to manage.
These tools save development time and help keep Magento 2 stores updated with the latest frontend standards.
However, real store upgrades still require careful handling, as custom themes, third-party modules, and frontend changes can sometimes cause design or functionality issues during migration.
At Meetanshi, we regularly help Magento store owners upgrade and optimize Hyvä-based websites with minimal disruption. From Tailwind and Alpine.js migrations to custom frontend fixes and performance improvements, our Hyvä experts handle the complete upgrade process smoothly.
