From Vue PLP to Hyvä storefront cutover

2023-12-01 · Ben Williamson

Why I finally wrote this down

An aftermarket parts retailer planned a Hyvä storefront cutover while Live Search and YMM fitment facets were still moving weekly. Waiting for the theme project to finish would have frozen search UX for months. Product and SEO wanted category wins earlier. Engineering needed a place to learn which pieces were search-layer versus theme-layer.

We shipped an intermediate PLP using Vue 3 and InstantSearch on the existing Luma base, then migrated the useful contracts into Hyvä instead of rewriting everything twice.

Why an intermediate PLP

  • Iteration speed: Facet behavior and garage-aware filters changed faster than theme inheritance could safely absorb.

  • Stakeholder wins: Grid, sort, and fitment sidebar improvements shipped before the Hyvä launch window.

  • Learning: We tagged components as search core, theme chrome, or CMS slots before the cutover inventory.

Big-bang theme replays hide search regressions until launch week. A bridge PLP surfaces feed and facet issues when rollback is cheap.

What carried forward

Patterns and contracts, not stylesheets:

  • Facet state model (query params, selected YMM dimensions, sort key).

  • Garage-aware filter UX: empty garage prompts, URL-seeded first visit before account sync.

  • Grid/list toggle and mobile filter drawer behavior.

  • Search document field names for fitment IDs (stable across themes).

The abstraction that survived unchanged was the InstantSearch configuration and the SaaS feed field map. Hyvä replaced how the shell looked, not what the index thought a product was.

What we deliberately did not port twice

  • Luma layout CSS: Hyvä Tailwind replaced it entirely. Porting would have duplicated breakpoints for no gain.

  • Knockout bridges: One-off KO widgets became Alpine islands where needed.

  • Page Builder chrome on PLP: Category search shell stayed thin; CMS blocks reattached after Hyvä layout stabilized.

The temptation is to copy working Luma files because they exist. If Hyvä already owns that concern, reimplement the behavior, not the file.

Cutover checklist

  1. Inventory Vue components: search core vs chrome vs CMS slots.

  2. Reimplement the search shell in Hyvä with the same facet keys and query param names.

  3. Validate indexer health and SaaS feed parity on staging with Varnish on.

  4. Run indexer and cache flush in the launch window; tag a rollback theme.

  5. Compare PLP metrics (LCP, filter interaction, zero-result rate) for two weeks, not just launch-night smoke tests.

Quick review before you bridge

  • Can I list facet keys that must not rename between Luma and Hyvä?

  • Which components are theme chrome vs search core?

  • Is there a rollback path that does not require redeploying search feeds?

  • Did staging run with cache enabled during QA?