Executive summary
- What: The September 2026 Hydrogen developer preview teaches the framework to honour ?variant= links, adds a cart refresh method, and generates local HTTPS certificates for Customer Account testing.
- Why: Variant links arriving from shopping feeds previously landed on the default variant at the default price, which quietly undermined paid and organic product traffic on headless storefronts.
- Who: Teams running Hydrogen storefronts, particularly those with wide variant catalogues, server side cart creation, or Customer Accounts in local development.
What changed
Three additions carry most of the weight. Variant links: Hydrogen now reads the ?variant= parameter on a product URL and renders that variant, provided you pass routeTemplates to handleShopifyRoutes. Product option links gain a builder, buildProductSelectionSearchParams(), which emits option parameters by default, produces a shareable ?variant= link with style variant, and stops stale selections accumulating in the query string. Cart refresh: when a server side cartCreate or a direct Storefront mutation changes the cart outside Hydrogen's own forms, call refresh() from useCartActions() in React or Vue, or CartStore.refresh() elsewhere. Local HTTPS: the localHttps() Vite plugin issues certificates on first run, and npx hydrogen certs install covers projects without the plugin.
The smaller changes matter more than their billing suggests. Route level redirects can set their own status code. getSelectedProductOptions no longer returns variant as a product option. The https:dev script is now dev:https. Changing a collection filter or sort order resets pagination cursors, fixing a stale cursor pointing past the end of a new result set.
Why it matters
On a headless storefront the variant link fix is the item with revenue attached. Shopping feeds, affiliate links, email campaigns, and support handoffs all carry ?variant= parameters. Landing every one of them on the default variant means the shopper sees the wrong size, colour, and often price, then has to reselect before buying. Where variants differ in price, the gap between advertised and displayed price is also a feed disapproval risk.
Cart refresh removes a class of desynchronisation bug that teams have typically worked around with a full page reload after any server side cart mutation. Certificate generation is smaller, but it removes a step every new developer hit before they could test Customer Account login.
Role-specific impact
- Marketers: variant level deep links from paid shopping, email, and affiliate traffic now resolve correctly, which makes landing page tests and price parity checks meaningful again.
- Developers: adopt routeTemplates on handleShopifyRoutes, replace hand built option query strings with buildProductSelectionSearchParams(), audit any code reading variant from getSelectedProductOptions, and rename https:dev to dev:https across scripts and CI.
- Store admins: expect fewer support contacts about wrong variants and prices on campaign links, and fewer manual feed corrections.
Use-case example
Real-world scenario
A Plus apparel merchant runs a Hydrogen storefront with roughly 40,000 variants and spends heavily on shopping feeds. Before this release every feed click opened the product at its default variant, so a shopper clicking a size 12 listing at 89 dollars arrived on the size 6 default at 69 dollars. Support logged the price confusion as a recurring complaint. After enabling routeTemplates, feed clicks resolve to the advertised variant. On comparable migrations we would expect add to cart rate on feed traffic to recover by several percentage points and price mismatch disapprovals to fall to zero. Track add to cart rate segmented by presence of a variant parameter, two weeks either side of the change.
Implementation checklist
- Upgrade a branch to the September 2 preview and read the diff between the bracketing commits first.
- Pass routeTemplates to handleShopifyRoutes, then confirm a ?variant= URL renders the correct variant and the correct price.
- Replace manual option query string construction with buildProductSelectionSearchParams(), using style variant for shareable links.
- Search the codebase for getSelectedProductOptions and remove any logic that expected variant in the returned options.
- Call refresh() from useCartActions(), or CartStore.refresh(), anywhere server side code or a direct Storefront mutation changes the cart.
- Add the localHttps() Vite plugin, or run npx hydrogen certs install, and verify Customer Account login works locally.
- Rename https:dev to dev:https in package.json, internal documentation, and CI configuration.
- Regression test collection filtering and sorting, since pagination cursors now reset when a filter or sort changes.
FAQ
Q: Is the developer preview safe to run on a production storefront?
A: Treat it as preview software. APIs on this track can change between releases, so run it on a branch, keep the upgrade behind a deployment you can roll back, and hold production until the capability you need reaches a stable release.
Q: Do we need the variant link change if we do not run shopping feeds?
A: Almost certainly yes. Any channel sharing a product URL with a variant parameter is affected: email, affiliates, marketplaces, and links your own support team sends.
Resources
Hydrogen developer preview documentation
Need guidance? Talk to Makro.