A Hyva frontend cutover is the moment the new theme goes live on your Magento or Adobe Commerce store, and a safe cutover is defined by one thing: how fast you can reverse it. Treat the theme switch as a reversible configuration change, keep Luma installed and warm, pre-build static content, and rehearse the rollback before go-live.
Most Luma to Hyva projects spend months on the rebuild and almost no time on the go-live. That is backwards. The rebuild is forgiving because it happens in staging. The cutover is not, because it touches real orders, real cache, and real revenue. This runbook covers the part that actually keeps you up at night: shipping the switch and knowing you can undo it inside minutes if something breaks.
What a Hyva cutover actually changes (and what it does not)
The cutover itself is small. Activating Hyva is a change under Content > Design > Configuration, where you set the applied theme for the scope you are launching. The Hyva getting-started documentation spells out the one rule teams forget: if you assign Hyva at the store or store-view level, you must still assign a theme at the website level, or the storefront breaks. Any theme at the website level is fine, as long as one is set.
What the config change does not do is reload your edge. Magento resolves the theme server-side and bakes the rendered HTML into full page cache. If you switch the theme and leave Varnish or the built-in FPC populated, returning visitors keep getting Luma HTML and new visitors get Hyva, which produces a confusing split and broken assets. The theme switch is only complete once static content is deployed and full page cache is flushed. If you run your own CDN and FPC, our write-up on Magento full page cache and Varnish on Hyva covers the invalidation details that bite during a cutover.
One more misconception worth killing early: Hyva does not silently fall back to Luma for individual modules. A third-party extension built for Luma will not render on Hyva unless it has a compatibility module or a Hyva build. “Keep Luma as a fallback” means fallback at the theme level, so you can revert the whole storefront, not a per-module safety net. Plan compatibility before go-live, not during rollback.
The three cutover models, compared
There is no single right way to go live. The model you pick depends on how much infrastructure you run and how much risk the business will tolerate on launch day.
| Cutover model | How it works | Rollback speed | Best for | Main cost |
|---|---|---|---|---|
| In-place theme switch | Flip the applied theme on the live store view, deploy static content, flush cache | Minutes (revert config, flush) | Most single-storefront merchants with a solid staging rehearsal | Brief cache-cold window after the switch |
| Separate store view first | Launch Hyva on a new or internal store view, route a subset of users, then promote to the primary view | Instant for the test view | Teams that want real users on Hyva before full exposure | Extra store view config and QA across two themes |
| Blue-green at infrastructure level | Two full Magento stacks (Luma and Hyva), switch origin traffic at the load balancer or CDN | Seconds (swap origin back) | Enterprise stores that already run blue-green deploys | Running and syncing two environments |
For the majority of mid-market stores, the in-place switch with a rehearsed rollback is the pragmatic choice. The separate-store-view model is the honest answer to “can we test on real traffic first,” and it works because Magento supports different themes per store view in one install. Blue-green is the gold standard for high-volume stores but only pays off if you already operate two environments for ordinary releases. Our Magento and Hyva CI/CD release pipeline guide covers the deploy mechanics that make blue-green realistic.
Pre-cutover: make the switch reversible before you flip it
Reversibility is engineered before launch, not improvised during an incident. Six things have to be true before you touch production.
Static content is pre-built. In production mode you deploy static view files ahead of the switch so assets exist the instant the theme changes. Adobe’s reference on deploying static view files documents setup:static-content:deploy, including deploying for specific themes and locales. Build both the Hyva and the Luma static content so a rollback does not leave you regenerating assets under pressure.
Luma stays installed. Do not uninstall the Luma theme or its parent packages on cutover day. The ability to revert depends on Luma’s templates and static files still being present. Removing them turns a two-minute rollback into a redeploy.
You have a release you can return to. If you deploy by atomic symlink, the previous release directory is your rollback target: switch the symlink back and you are on the prior build instantly. If you deploy from git, tag the pre-cutover commit so you can redeploy it without hunting through history.
Config is captured. Export configuration before the switch with config:export, and note the exact applied-theme value per scope. A rollback that guesses at the previous theme assignment is not a rollback.
A full backup exists. Take a database and file backup immediately before the switch. You are unlikely to need a restore for a theme change, but the one time schema or content staging changes rode along with the cutover, you will want it.
Rollback is rehearsed. Run the entire revert on staging and time it. The number you care about is your mean time to recover. If reverting takes forty minutes because nobody has done it, you do not have a rollback plan, you have a hope.
The go-live runbook, step by step
Schedule the switch for your lowest-traffic window and freeze unrelated deploys for the day. Then work the sequence.
- Freeze and snapshot. Pause marketing sends and promotions that would spike traffic, then take the pre-cutover backup and config export.
- Pre-deploy static content. Run
setup:static-content:deployfor the Hyva theme and your locales so assets are ready before the theme is live. - Switch the applied theme. In Content > Design > Configuration, set Hyva for the launch scope, confirming a website-level theme is assigned.
- Compile and clear. Run
setup:di:compileif your deploy requires it, then flush the Magento cache so layout and config changes take effect. - Flush the edge. Purge Varnish or your CDN full page cache so cached Luma HTML stops being served. Selective purge by cache tags is fine if you trust your tag coverage; a full purge is safer on launch day.
- Smoke test the critical path. Homepage, a category with layered navigation, a configurable product, add to cart, and the full checkout through payment. Test as guest and as a logged-in customer. Checkout is the test that matters most.
- Verify analytics and consent. Confirm your data layer, tag manager, and consent signals still fire on Hyva. A silent analytics break on cutover day costs you the data you need to judge the launch.
- Watch, do not walk away. Keep the team on the launch for the first few hours. Most cutover problems show up fast.
A clean in-place cutover with pre-built static content is usually a matter of minutes of real change. The hours around it are for verification, not for the switch itself.
Rollback: the four ways to undo a Hyva cutover
Pick your rollback method from the cutover model you chose, and know the trigger for each before you start.
- Revert the applied theme. Set the scope back to Luma in Content > Design > Configuration, flush Magento cache, and purge the edge. This is the primary rollback for an in-place switch and the reason Luma must stay installed and its static content pre-built. Expect a short cache-cold window as Luma pages repopulate.
- Revert the store-view routing. If you launched on a separate store view, stop routing users to it. The primary storefront never changed, so there is nothing to undo at the theme level.
- Swap the symlink or redeploy the tag. For atomic-symlink deploys, point the live symlink back at the previous release. For git-based deploys, redeploy the pre-cutover tag. Use this when the problem is in the build, not just the theme assignment.
- Swap origin back (blue-green). Move traffic from the Hyva stack to the Luma stack at the load balancer or CDN. This is the fastest rollback available and the reason enterprises invest in two environments.
Whatever the method, decide in advance who can call a rollback and on what signal. An incident is a bad time to debate whether a fifteen-point conversion drop is noise.
Why “10% of traffic to Hyva” is harder than it sounds
Teams coming from client-side feature flags assume they can send ten percent of traffic to Hyva and watch. On a single Magento install, you cannot, because the theme is resolved server-side per store view, not per request from a flag. A true percentage split needs one of three things: a separate store view with cookie or geo routing in front of it, a blue-green setup where the CDN splits traffic between two origins, or an internal-only store view you expose to staff first.
This is the detail most migration guides skip, and it changes your plan. If the business expects a gradual canary, you are choosing the separate-store-view or blue-green model up front, not bolting a split onto an in-place switch at the last minute. This server-side coupling is also where Magento differs from hosted platforms. On Shopify, BigCommerce, and Shopware, the theme and rollout model are shaped by the platform. On Magento and Adobe Commerce, you own the infrastructure, which means you own both the constraint and the flexibility to design the cutover that fits your risk tolerance.
The 72-hour watch: metrics and rollback triggers
The first three days decide whether the cutover holds. Watch real-user data, not just lab scores, because field data is what reflects customer experience. Baseline every number before launch so you are comparing against your own store, which is the point we make in measuring a Hyva migration properly.
| Signal | Where to watch | Rollback trigger |
|---|---|---|
| Checkout conversion rate | Analytics, real time first few hours | Sustained drop beyond normal variance with no other cause |
| JavaScript error rate | Error monitoring, console | Sharp spike versus the pre-launch baseline |
| Core Web Vitals (field) | Search Console, analytics | LCP, INP, or CLS worse than before, not better |
| Add-to-cart and checkout completion | Funnel analytics | Steps failing or stalling for real users |
| Support and complaint volume | Helpdesk, chat | Cluster of reports about broken pages or checkout |
Core Web Vitals thresholds are the published targets: LCP under 2.5 seconds, INP under 200 milliseconds, and CLS under 0.1, measured at the 75th percentile. A Hyva cutover should move these the right way quickly; if the field numbers get worse, that is a signal, not a rounding error.
Common cutover mistakes that force a rollback
The failures that send teams back to Luma are rarely exotic.
- Shipping with unported extensions. A Luma-only extension on a key page renders broken. Compatibility is a pre-launch task.
- Forgetting the website-level theme. Setting Hyva only at the store view with no website theme breaks the storefront, exactly as the Hyva docs warn.
- Leaving cache populated. Skipping the edge purge serves stale Luma HTML and mismatched assets after the switch.
- No pre-built Luma static content. The rollback stalls while assets regenerate under load.
- Launching into a traffic spike. A cutover during a promotion or peak hour magnifies every problem. Pick a quiet window.
- No owner for the rollback call. Without a named decision-maker and a clear trigger, teams hesitate while the damage compounds.
Frequently asked questions
How long does a Hyva cutover take?
The theme switch itself is a configuration change plus a cache flush, which is minutes when static content is pre-built. The surrounding work, smoke testing the critical path and watching metrics, runs for hours on launch day and for about 72 hours after. Budget the attention, not just the switch.
Can I roll back a Hyva cutover without losing orders or data?
Yes. A theme rollback only changes which templates render; it does not touch orders, customers, or catalog data. The caution is anything bundled into the same deploy, such as schema or content staging changes, which is why you take a backup and keep theme changes separate from data changes.
Do I have to take the store down to switch to Hyva?
No. With static content pre-built and a cache flush planned, the switch does not require maintenance mode for the theme change alone. Zero-downtime deploy patterns such as atomic symlinks or blue-green let you avoid a maintenance window entirely, which matters most for stores that cannot afford to stop selling.
Should I keep the Luma theme installed after a successful launch?
Keep Luma installed through your stabilization window, commonly a few weeks, so rollback stays available if a delayed issue surfaces. Once field data is healthy and the team is confident, you can remove it. There is no rush, and the disk cost is trivial against the safety it buys.
Can I run Hyva and Luma at the same time during migration?
Yes, across different store views in one install. This is the basis of the separate-store-view cutover model and of a phased rollout where some views move before others. It is the most honest way to get real users onto Hyva before committing the primary storefront.
Ship the switch with a team that has done it
A Hyva cutover is low-drama when the reversibility is engineered in and high-drama when it is not. The difference is rehearsal: pre-built static content, Luma kept warm, a named rollback owner, and a 72-hour watch against your own baseline. Get those right and the switch is the easy part.
Bemeir plans and ships these cutovers as the USA’s leading official Hyva partner, working as an extension of your team through launch and the stabilization window that follows. See our Hyva development services, the technology partners we integrate with across hosting, CDN, and payments, and more about how we work.
