Hydrogen 2026-10 Migration: Scope It Before April 2027
Hydrogen 2026-10 is not an upgrade, it is a rewrite of your storefront's plumbing. Released on October 9, 2026, it turns Hydrogen from a framework into a library, and 81 of the 88 runtime exports in the last legacy release (2026.4.8) no longer exist in 2026.10.3. Shopify's own shopify hydrogen upgrade command does not cross that line. If you run a legacy Hydrogen storefront, the date to plan around is April 16, 2027, when Storefront API 2026-04 (the version Hydrogen 2026.4.8 pins) stops being accessible.
Key takeaways
- 23.1% of
@shopify/hydrogennpm downloads in the seven days before November 11, 2026 were 2026.10.x. Most installs are still on legacy lines, so most teams have this migration ahead of them. - In Shopify's own legacy skeleton template, 30 of 70 TypeScript files import something that 2026-10 removed (51 imports in total), and 22 more call sites read the old load context.
- The expensive part is not the imports. Analytics events and the cart drawer can break while the build stays green.
- You can stay on React Router and Oxygen, or move to Next.js 16 with Vercel Shop. The second path is a rebuild of your routes, not a migration.
What actually changed in Hydrogen 2026-10?
Your app now owns the whole request pipeline, and Hydrogen supplies commerce primitives you compose into each request. In Shopify's migration guide, legacy Hydrogen "owned the request": createHydrogenContext() built the Storefront API client, the cart and the customer account client, and handed them to loaders. In 2026-10 you build that request yourself in a root middleware, and handleShopifyRoutes() answers the paths Shopify owns (/api/cart, /checkout, cart permalinks, account login) before your router runs.
The package itself shows the scale. We extracted both tarballs from npm and diffed the runtime export lists:
| 2026.4.8 (legacy) | 2026.10.3 | |
|---|---|---|
| Runtime exports | 88 (root entry) | 109 (core, React and customer-account entries) |
| Legacy names still exported | 7 | |
| Peer dependencies | react-router ~7.16, @react-router/dev, React, Vite | None required (React, Vue and Vite are optional peers) |
| Storefront API version pinned | 2026-04 | 2026-10 |
| Dev and build | shopify hydrogen dev / build | plain Vite and React Router commands |
The seven names that survive are AnalyticsEvent, ShopPayButton, createContentSecurityPolicy, createCustomerAccountClient, createStorefrontClient, flattenConnection and getSelectedProductOptions. Two of those moved entry points and createStorefrontClient() takes new options, so even the survivors need edits. <Image>, <Money>, <Pagination>, CartForm, VariantSelector, Analytics.Provider, getSitemap() and the CacheLong() family are gone. Shopify's guide lists replacements for most of them; for Video, ModelViewer, RichText, parseMetafield() and a few others it says there is no replacement and the code becomes yours.
How much of a typical storefront does it touch?
43% of the TypeScript files in a stock storefront. We ran the scanner below against Shopify's legacy skeleton template (the 2026-04 branch of Shopify/hydrogen, commit e5fcac1), the starter Shopify maintained for legacy Hydrogen:
| Migration area | Removed imports | Files |
|---|---|---|
UI components (Image 11, Money 8, pagination 9) | 28 | 18 |
| Cart | 6 | 6 |
| Analytics | 6 | 5 |
| Server wiring | 4 | 3 |
| Product options | 3 | 1 |
| CSP and nonce | 2 | 2 |
| SEO and sitemaps | 2 | 2 |
| Total | 51 | 30 of 70 |
On top of that, 22 call sites read context.storefront, context.cart or context.customerAccount, which all move to a typed React Router context with a new client (storefrontClient.graphql() replaces storefront.query()).
Treat the skeleton numbers as a floor. Production storefronts usually add custom sections and third-party tracking on top, and those sit in the areas with the most removals.
Which breakages will not fail the build?
The ones that cost money, starting with tracking and the cart drawer. Shopify's guide is unusually direct about changes where "nothing reports an error", and we pulled them into one list because they are what a QA pass has to target:
- Analytics events.
ShopifyScriptsdoes not publish page views, product views, cart views or cart changes. Your app publishes every event towindow.Shopify.analytics. A rewrite that only sends page views drops the rest silently, and GA4 or Shopify analytics show a conversion dip that is really missing data. - The cart drawer. If your layout still passes a deferred
cartfrom the root loader to<Await>, the header count updates but the drawer and cart page stay empty. Opening the drawer from a fetcher also stops working, becauseuseCartForm()submits through the cart store. - Response headers. Forget
requestContext.applyResponseHeaders()in the middleware and Shopify's headers vanish from every page. - Variant links. Leave
routeTemplatesout ofhandleShopifyRoutes()and?variant=links on custom product paths stop redirecting. - Deploys that upload nothing. React Router builds to
build/, the deploy script uploads fromdist/. WithoutbuildDirectory: 'dist'the build succeeds and the deploy ships an empty bundle. - Deferred loaders. A
defer()you convert incorrectly can leave a page section loading forever with no error. - Routes without middleware. Middleware runs only for matched routes, so the catch-all
$.tsxhas to stay or Shopify redirects stop working on unknown paths.
Items 1 and 2 are where we would put the most test time. A storefront can pass every build and typecheck step with both broken.
When does staying on legacy Hydrogen stop working?
The hard date is April 16, 2027 at 15:00 UTC. Hydrogen 2026.4.8 pins Storefront API version 2026-04 (the string is in the published bundle), and Shopify's versioning page lists 2026-04 as accessible until then. After that, Shopify says requests to a retired version fall forward to the oldest accessible stable version. Your storefront will not go dark that afternoon, but it will be running queries against a schema it was never tested on, and any field removed in between becomes a production bug.
There is also no newer legacy line to move to. Shopify shipped 2026.4.8 on October 21, 2026 as a patch, but there is no 2026.7 release, and Shopify's legacy docs now recommend migrating. Plan on legacy Hydrogen getting fixes, not features.
That leaves roughly five months from today. For a team that also has a Q4 code freeze, the realistic window is January to March 2027.
Should you migrate in place or move to Next.js?
Migrate in place if your storefront is healthy and your team knows React Router. Shopify's guide keeps you on React Router 7 and Oxygen, and the work is mostly mechanical once the root middleware exists.
Consider Next.js if you were already planning a redesign. Hydrogen 2026-10 now supports Next.js 16 officially: the request handler docs wire Hydrogen into proxy.ts (the Next.js 16 replacement for middleware.ts) and run the redirect check in app/not-found.tsx. Vercel maintains the Vercel Shop template on Next.js 16 App Router. Moving there means rewriting every route as an App Router page and hosting on Vercel instead of Oxygen, so price it as a rebuild that happens to reuse your GraphQL queries.
Vercel's two-minute announcement (August 26, 2026), published before the 2026-10 release. It describes the rebuild as open source and runtime agnostic.
Neither path keeps your UI components. Both lose <Image> and <Money>, so the component work in the table above is the same either way.
How do you scope your own storefront?
Run this from your project root. It has no dependencies. We tested it with Node 22.22.0 against the legacy skeleton; the table above comes from that run.
// hydrogen-scope.mjs: count legacy Hydrogen (2026-04 and earlier) imports
// that Hydrogen 2026-10 removed, grouped by migration area.
// Usage: node hydrogen-scope.mjs ./app
import {readdirSync, readFileSync, statSync} from 'node:fs';
import {join, extname} from 'node:path';
const AREAS = {
'server wiring': ['createHydrogenContext', 'hydrogenContext', 'createRequestHandler',
'hydrogenRoutes', 'hydrogenPreset', 'storefrontRedirect', 'graphiqlLoader'],
caching: ['CacheLong', 'CacheShort', 'CacheNone', 'CacheCustom', 'createWithCache'],
cart: ['CartForm', 'OptimisticInput', 'useOptimisticCart', 'useOptimisticData',
'createCartHandler'],
'product options': ['VariantSelector', 'useOptimisticVariant', 'getProductOptions',
'getAdjacentAndFirstAvailableVariants'],
'UI components': ['Image', 'MediaFile', 'Money', 'useMoney', 'Pagination',
'getPaginationVariables', 'Video', 'ExternalVideo', 'ModelViewer', 'RichText', 'Script'],
'SEO and sitemaps': ['Seo', 'getSeoMeta', 'getSitemap', 'getSitemapIndex'],
'CSP and nonce': ['NonceProvider', 'useNonce'],
analytics: ['Analytics', 'useAnalytics', 'getShopAnalytics', 'useCustomerPrivacy'],
'moved import': ['ShopPayButton', 'createCustomerAccountClient'],
};
const lookup = new Map();
for (const [area, names] of Object.entries(AREAS)) for (const n of names) lookup.set(n, area);
const IMPORT = /import\s+(?:type\s+)?\{([^}]*)\}\s+from\s+['"](@shopify\/hydrogen|@remix-run\/[\w-]+)['"]/g;
function* walk(dir) {
for (const name of readdirSync(dir)) {
if (name === 'node_modules' || name.startsWith('.')) continue;
const p = join(dir, name);
if (statSync(p).isDirectory()) yield* walk(p);
else if (['.ts', '.tsx', '.js', '.jsx'].includes(extname(p))) yield p;
}
}
const hits = new Map(); // area -> {count, files}
let remixImports = 0;
let contextCalls = 0;
const CONTEXT = /\bcontext\.(storefront|cart|customerAccount)\b|\bstorefront\.Cache(Long|Short|None|Custom)\b/g;
for (const file of walk(process.argv[2] ?? './app')) {
const src = readFileSync(file, 'utf8');
contextCalls += [...src.matchAll(CONTEXT)].length;
for (const m of src.matchAll(IMPORT)) {
if (m[2].startsWith('@remix-run/')) { remixImports++; continue; }
for (const raw of m[1].split(',')) {
const name = raw.trim().replace(/^type\s+/, '').split(/\s+as\s+/)[0];
const area = lookup.get(name) ?? (/^cart\w+Default$/.test(name) ? 'cart' : null);
if (!area) continue;
const h = hits.get(area) ?? {count: 0, files: new Set()};
h.count++;
h.files.add(file);
hits.set(area, h);
}
}
}
const rows = [...hits].sort((a, b) => b[1].count - a[1].count);
for (const [area, h] of rows) console.log(`${area.padEnd(18)} ${String(h.count).padStart(3)} imports in ${h.files.size} files`);
console.log(`@remix-run imports: ${remixImports}`);
console.log(`Legacy load-context calls (context.storefront, context.cart, ...): ${contextCalls}`);
const files = new Set(rows.flatMap(([, h]) => [...h.files]));
console.log(`Total: ${rows.reduce((s, [, h]) => s + h.count, 0)} legacy imports in ${files.size} files`);Run it as node hydrogen-scope.mjs . to include server.ts. Read the output as a map of where the work is, not as the full bill. It only sees named imports from @shopify/hydrogen and Remix packages, and it skips removed types such as OptimisticCart and HydrogenSession, which npm run typecheck will report anyway. It will not find the analytics and cart problems in the list above, because those live in code that compiles fine. A @remix-run count above zero means you also need the Remix to React Router 7 migration, which Shopify documents as a separate step.
What should a migration budget include?
Budget the code migration and a QA pass aimed at the silent failures as separate lines, and book your analytics owner for a before-and-after comparison at cutover. The QA line is the one teams skip, and the analytics comparison is the only check that catches item 1 above.
For reference, our custom Hydrogen builds take 3 to 7 weeks and start at $3,400. A migration of an existing storefront depends on what the scanner finds plus your custom sections and integrations, so we scope each one with a fixed estimate within 48 hours instead of quoting a flat rate. If you want that estimate, send us the scanner output through our Hydrogen development page or contact form.
Two of our earlier pieces cover the decisions that sit behind this one: what Hydrogen costs to own (written for 2026.4, before this release) and how Hydrogen and Liquid stores compare in field data, which also covers the new Cache.long() caching API.
Method notes. Export counts come from the export {} statements in dist/production/index.js (2026.4.8) and the core, React and customer-account index.mjs files (2026.10.3), downloaded from the npm registry on November 11, 2026. Download shares come from npm's per-version endpoint for the previous seven days; downloads include CI installs, so they indicate adoption rather than count stores. Release dates are from the npm registry.
Do you want secure, fast website or application?