migrate-to-hydrogen-2026-10
Skill218 starsChanged 5 days agoMITView on GitHub
Migrate a classic Hydrogen storefront (Remix or React Router 7) to Hydrogen 2026-10 (`@shopify/hydrogen@^2026.10.0`), where Hydrogen is a server-handler library you compose instead of a framework that owns the request. Use when the user asks to migrate or upgrade a Hydrogen storefront to Hydrogen 2026-10 ("migrate to hydrogen 2026-10", "migrate to hydrogen preview", "upgrade Hydrogen to the new library").
- Reads credentials
1 other project uses a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- Shopify/hydrogenedited, first seen Oct 20, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 1
- Shopify/hydrogen★ 2.2k99% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository23 other files it gives its agents.
- AGENTS.mdAGENTS.md
- hydrogen-analyticsSkill
- hydrogen-cart-drawerSkill
- hydrogen-cart-metafieldsSkill
- hydrogen-cart-uiSkill
- hydrogen-collection-browserSkill
- hydrogen-customer-accountSkill
- hydrogen-imageSkill
- hydrogen-local-httpsSkill
- hydrogen-marketsSkill
- hydrogen-moneySkill
- hydrogen-oxygenSkill
- hydrogen-predictive-searchSkill
- hydrogen-request-handlersSkill
- hydrogen-robots-txtSkill
- hydrogen-routingSkill
- hydrogen-setupSkill
- hydrogen-shop-paySkill
- hydrogen-smoke-testSkill
- hydrogen-storefront-clientSkill
- hydrogen-variant-formSkill
- remix-storeSkill
- testing-practicesSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 26
Before wiring any subsystem, read the matching packaged skill in node_modules/@shopify/hydrogen/skills/ (hydrogen-setup, …
- Distinctive: line 32
Do these in order; verify each against the installed package rather than assuming.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Migrate to Hydrogen 2026-10
Migrate a classic-Hydrogen storefront (Remix- or React-Router-based) to Hydrogen 2026-10 — the release where Hydrogen becomes a server-handler library. Install @shopify/hydrogen@^2026.10.0 (npm view @shopify/hydrogen dist-tags shows the current latest; do not install the preview dist-tag, which is older than latest). This skill is storefront-agnostic — it captures the migration shape and, most importantly, the traps that agents get wrong.
The mental model (get this right first)
- Hydrogen 2026-10 is a server-handler library, not a framework. (A
@shopify/hydrogenversion before2026.10is still the old framework, not the library — the classic line runs through2026.4.x— so an installed version below2026.10means the store hasn't been migrated yet, regardless of its React Router status.) You compose the request lifecycle yourself:createShopifyRequestContext({request, i18n, buyerIp})→createStorefrontClient({type: 'private', requestContext, config})(config carriesstoreDomain,privateStorefrontToken,storefrontId,cache,waitUntil; a store without a private token usestype: 'public'instead — see thehydrogen-storefront-clientpackaged skill for the choice) →handleShopifyRoutes({request, requestContext, storefrontClient, routeTemplates, handlers}), plussessionManagerwhen a registered handler reads the session (returns aPromise<Response>for handler-owned paths, elsenull— decided synchronously, so truthy-check it withoutawait) →handleShopifyRedirectson 404 → handler groups for the rest:createCartServerHandlers()for cart andcreateCustomerAccountServerHandlers(…)(from@shopify/hydrogen/customer-account) for auth, both registered through thehandlersarray. Hydrogen no longer owns routing or the entry — you wire these into your React Router server/middleware. - Dev and build are plain Vite/React Router — the classic
shopify hydrogen dev|buildcommands and thehydrogen()Vite plugin are gone.devisvite devwith theoxygen()plugin from@shopify/mini-oxygen/vite(workerd runtime,.envinjection);buildisreact-router build;previewisvite previewafter a build. Thehydrogenbin that ships with the library covers the rest:hydrogen setup,hydrogen skills check|sync,hydrogen gql check,npx hydrogen certs install|uninstallfor local HTTPS.@shopify/clistays a devDependency for theshopify hydrogencommands the library does not replace:deploy,link,env pull. Do not add@shopify/hydrogen-classicor any aliased classic package — the 2026-10 library has no classic sibling.
Before wiring any subsystem, read the matching packaged skill in node_modules/@shopify/hydrogen/skills/ (hydrogen-setup, hydrogen-request-handlers, hydrogen-routing, hydrogen-storefront-client, hydrogen-cart-ui, hydrogen-cart-drawer, hydrogen-collection-browser, hydrogen-variant-form, hydrogen-predictive-search, hydrogen-customer-account, hydrogen-analytics, hydrogen-markets, hydrogen-shop-pay, …). They are the authoritative, version-correct reference — prefer them over memory.
Migration outline
First, determine whether the Remix→React Router move is already done. The Remix→React Router migration and the Hydrogen-framework→Hydrogen-library migration are independent axes. The classic Hydrogen framework runs on either Remix or React Router 7, so a store can already be on React Router while still being unmigrated. Check package.json and imports: if there are no @remix-run/react, @remix-run/node, @remix-run/server-runtime or @shopify/remix-oxygen deps or imports and react-router + @react-router/* are present (with a react-router.config.ts), the RR migration is already complete (@remix-run/cookie and @remix-run/session are standalone packages the 2026-10 template itself uses for cookie sessions — not a Remix tell) — skip the Remix swaps (steps 1 and 6 below) and do only the framework→library conversion. "Already on React Router" does not mean "already migrated." The tell for the Hydrogen axis is the package: a @shopify/hydrogen calendar version before 2026.10 is still classic (framework) Hydrogen — not yet migrated (the latest classic releases are on the 2026.4.x line).
Do these in order; verify each against the installed package rather than assuming. Copy this checklist and track progress as you go:
Hydrogen migration:
- [ ] Determine if already on React Router (if so, skip the Remix swaps in steps 1 and 6)
- [ ] 1. Dependencies + version pins (@shopify/hydrogen ^2026.10.0 and the seed below; drop classic-era deps)
- [ ] 2. Scripts: hydrogen skills check --mode=warn && vite dev / react-router build / vite preview; deploy via @shopify/cli
- [ ] 3. vite.config plugins: [localHttps({enabled}), ...oxygen(), reactRouter()]
- [ ] 4. react-router.config.ts added (middleware enabled for your React Router version, buildDirectory 'dist')
- [ ] 5. Request wiring (request context + storefront client + route templates, plus a session manager when a handler needs one)
- [ ] 6. Route filename + import + json()/defer() sweep
- [ ] CSP/nonce: create a per-document policy with `createContentSecurityPolicy({shop})` and apply it with `csp.applyResponseHeaders(response.headers)`; keep React nonce context in app code, then check the browser console for CSP violations
- [ ] 7. Connect a store — env vars in .env (private token, or public token), or MOCK_SHOP=1 for the tokenless mock.shop demo
- [ ] Optional subsystems: detect each → migrate or skip, and report every skip
- [ ] Root middleware runs: GET /api/cart returns 200 JSON from the cart handler; a 404 or the app's 404 page means middleware isn't enabled for your React Router version (step 4)
- [ ] 8. Verify (build/typecheck gate, hydrogen-smoke-test, browser console on the home page), then hand off to the user- Dependencies — (Remix swap only if not already on React Router) replace
@remix-run/react,@remix-run/node,@remix-run/server-runtime,@remix-run/devand@shopify/remix-oxygenwithreact-router+@react-router/dev(pin all React Router packages to one version;react-router-domis not needed). Add@shopify/hydrogen,@shopify/mini-oxygen,vite, the@types/*packages and@shopify/cliat the versions in the seed below. Remove@shopify/cli-hydrogenand any@shopify/hydrogen-classic-style alias if present. Align versions to the seed rather than picking latest of each independently, and never pin React Router below the version the app already runs. - Scripts —
dev:hydrogen skills check --mode=warn && vite dev(the prefix prints the resync command after a later@shopify/hydrogenbump without blocking dev; plainhydrogen skills checkbelongs in CI);build:react-router build;preview:react-router build && vite preview;deploy:shopify hydrogen deploy --assets-dir dist/client --worker-dir dist/server. Adddev:httpswith the same command — the vite.config computes thelocalHttpsenabledflag fromnpm_lifecycle_event(step 3), not the script body. vite.config— plugins are[localHttps({enabled}), ...oxygen(), reactRouter()], withlocalHttpsfrom@shopify/hydrogen/viteandoxygenfrom@shopify/mini-oxygen/vite(it returns an array — spread it).localHttpstakes a requiredenabled: boolean— it does not self-detect; compute it in the config:const enabled = process.env.npm_lifecycle_event === 'dev:https'. There is nohydrogen()plugin anymore. You do not pass an oxygenentry— it picks up the React Router server build.react-router.config.ts— add it (React Router framework config + future flags). Make sure middleware is enabled for your version of React Router — the middleware skeleton below depends on it. SetbuildDirectory: 'dist'— React Router defaults tobuild/, and the deploy script's--assets-dir dist/client --worker-dir dist/serverflags silently point at nothing without it. Explicitroutes.tsroute config and flat routes via@react-router/fs-routesboth work — for a migration, fs-routes preserves the existing flat route filenames with the least churn.- Request wiring — in your server entry or a root middleware, build the request context and clients (mental-model step 1) and expose the storefront client to loaders via typed React Router contexts. If you already thread Oxygen
env/executionContextthrough a context provider, keep it — the library does not force a specific context shape. - Routes & imports — (skip the import swap if already on React Router) swap
@remix-run/*imports toreact-router; migratejson()/defer()loader/action return helpers. - Connect a store — set
PUBLIC_STORE_DOMAIN,PUBLIC_STOREFRONT_IDandPRIVATE_STOREFRONT_API_TOKENin.env(on Oxygen, a linked storefront injects them); a store with onlyPUBLIC_STOREFRONT_API_TOKENstill uses the real store through the public client. Customer accounts addSHOP_ID,PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_IDandSESSION_SECRET(full list inreferences/dependencies-and-tooling.md). WithMOCK_SHOP=1, or no store domain at all, the skeleton's client factory falls back to the tokenless mock.shop demo store — useful to verify the migration before the user supplies credentials. mock.shop only accepts a tokenless public client (it rejects the private-token header with a 401), and it is a catalog of fictional stores: https://mock.shop/llms.txt lists them. - Verify — build/typecheck gate, then the
hydrogen-smoke-testskill, then the browser console check, then hand off to the user (see Verification).
The exact config, version pins, and handler signatures change between builds — read them from the installed package (node_modules/@shopify/hydrogen, its skills/, and its .d.ts), not from this doc. The two things that are not in the installed package — the version seed and the React Router wiring skeleton — are below.
Bootstrapping versions
Step 1 has a chicken-and-egg problem: you cannot "read pins from the installed package" before anything is installed. The version identities are a bootstrap input, distinct from the config shapes you read post-install. Pin by these coupling rules, not by "latest of each":
- One React Router version across
react-router,@react-router/dev(and@react-router/fs-routesif you use it). - Floors with a reason —
@shopify/mini-oxygen≥4.2.0(vite preview) and@shopify/cli≥4.4.0(deploy flags);references/dependencies-and-tooling.mdexplains both. The seed already satisfies them. - Majors that move together:
vite@^8,react/react-dom@^19, node^22.12 || ^24(Vite 8's own engine floor for Node 22 is22.12.0— a bare22.xbelow that installs but fails Vite's engine check). - Align to the seed, not to "latest of each". Newer majors of the seed's packages can exist on npm (React Router 8 does) while the library's own template still pins the seed line — a solo bump breaks the coupling rules above. The one exception: never pin React Router below what the app already runs.
Known-good seed, copied from the 2026-10 release's own React Router template — verify against the current published build and update this block in place when it moves:
// package.json — align to a known-good release set (the 2026-10 template)
"@shopify/hydrogen": "^2026.10.0",
"react" | "react-dom": "^19.2.7", "react-router": "7.15.1", "isbot": "^5.1.36",
// devDependencies:
"@react-router/dev": "7.15.1", // same version as react-router; never below the app's current one
"@shopify/cli": "4.8.1",
"@shopify/mini-oxygen": "4.2.3",
"@shopify/oxygen-workers-types": "^4.1.6",
"@types/node": "^22", "@types/react": "^19.2.14", "@types/react-dom": "^19.2.3",
"gql.tada": "^1.9.2", "graphql": "^16.13.2", "typescript": "^5.9.3", "vite": "^8.0.3",
"engines.node": "^22.12 || ^24" // Vite 8 requires >=22.12 on the 22 line
// scripts:
"dev": "hydrogen skills check --mode=warn && vite dev",
"dev:https": "hydrogen skills check --mode=warn && vite dev", // same command — vite.config computes localHttps `enabled` from npm_lifecycle_event
"build": "react-router build",
"preview": "react-router build && vite preview",
"deploy": "shopify hydrogen deploy --assets-dir dist/client --worker-dir dist/server",
"typecheck": "react-router typegen && tsc && hydrogen gql check --fail-on-warn"Reference wiring (skeleton)
The framework→library conversion is mostly one context file plus one middleware. A store won't have a prior migration to copy from, so the durable shape is below — but verify every signature against the installed .d.ts, since they drift between builds.
server.ts shrinks to a bare fetch handler that only threads the Oxygen bindings (the template wraps this in a try/catch and adds a GET-body guard and a double-slash redirect):
import {createRequestHandler, RouterContextProvider} from 'react-router';
import * as serverBuild from 'virtual:react-router/server-build';
import {envContext} from '~/lib/storefront';
export default {
async fetch(request: Request, env: Env, executionContext: ExecutionContext): Promise<Response> {
const routerContext = new RouterContextProvider();
routerContext.cache = await caches.open('hydrogen-v1'); // Oxygen Cache API → storefront client cache
routerContext.set(envContext, env);
routerContext.env = env;
routerContext.waitUntil = executionContext.waitUntil.bind(executionContext);
const handleRequest = createRequestHandler(serverBuild, process.env.NODE_ENV);
return handleRequest(request, routerContext as never);
},
};env.d.ts — routerContext.cache/waitUntil above and context.cache/waitUntil in the middleware below only typecheck with this React Router module augmentation. It is app code, not something you can read from the package's .d.ts:
/// <reference types="vite/client" />
/// <reference types="react-router" />
/// <reference types="@shopify/oxygen-workers-types" />
import type {CacheInstance} from '@shopify/hydrogen';
declare global {
interface Env { // the Oxygen bindings (`.env` locally)
MOCK_SHOP?: string;
PUBLIC_STORE_DOMAIN?: string;
PUBLIC_STOREFRONT_ID?: string;
PUBLIC_STOREFRONT_API_TOKEN?: string;
PRIVATE_STOREFRONT_API_TOKEN?: string;
}
}
type HydrogenRouterContext = {cache: CacheInstance; env: Env; waitUntil: ExecutionContext['waitUntil']};
declare module 'react-router' {
interface AppLoadContext extends HydrogenRouterContext {}
interface RouterContextProvider extends HydrogenRouterContext {}
}app/lib/storefront.ts — typed RR contexts plus a per-request client factory (replaces the old AppLoadContext). buyerIp goes on the request context; cache/waitUntil/storefrontId go in the client config. The factory picks the private client when a private token exists, the public client against the real store otherwise (a public token works; tokenless can't read some fields), and the tokenless public client for mock.shop only when MOCK_SHOP=1 or no store domain is set:
import {createContext} from 'react-router';
import {
type CacheInstance,
type CachingStrategy,
createShopifyRequestContext,
createStorefrontClient,
defineShopifyI18n,
type PublicStorefrontClient,
type RequestScopedPrivateStorefrontClient,
type ShopifyRequestContext,
} from '@shopify/hydrogen';
// The bare client types default `Extra` to `{}`, which erases the per-call `cache`
// option from `graphql()` — every `Cache.long()` call-site then fails typecheck
// with an opaque "cache does not exist in type 'MergedOptions'". Carry the
// option through the alias instead.
type CacheOptions = {cache?: CachingStrategy};
export type RequestStorefrontClient =
| RequestScopedPrivateStorefrontClient<CacheOptions>
| PublicStorefrontClient<CacheOptions>;
export const envContext = createContext<Env>();
export const storefrontClientContext = createContext<RequestStorefrontClient>();
export const storefrontRequestContext = createContext<ShopifyRequestContext>();
// getBuyerIp is NOT a library export — it is app code (the template ships it in app/lib/shop.ts)
function getBuyerIp(headers: Headers) {
for (const header of ['oxygen-buyer-ip', 'cf-connecting-ip', 'x-forwarded-for']) {
const ip = headers.get(header)?.split(',')[0]?.trim();
if (ip) return ip;
}
if (process.env.NODE_ENV !== 'production') return '127.0.0.1';
throw new Error('No buyer IP header on the request');
}
// Module scope. Add `routing` to serve more locales by path prefix or hostname; the request context matches the locale from the URL.
const i18n = defineShopifyI18n({defaultLocale: {country: 'US', language: 'EN'}});
export function createRequestStorefrontClient(
request: Request,
env: Env,
cache: CacheInstance,
waitUntil: ExecutionContext['waitUntil'],
): RequestStorefrontClient {
// mock.shop is auth-free and 401s any token header, so it always gets the tokenless public client.
if (env.MOCK_SHOP === '1' || !env.PUBLIC_STORE_DOMAIN) {
return createStorefrontClient({
type: 'public',
requestContext: createShopifyRequestContext({request, i18n}),
config: {storeDomain: 'mock.shop', cache, waitUntil},
});
}
if (env.PRIVATE_STOREFRONT_API_TOKEN) {
return createStorefrontClient({
type: 'private',
requestContext: createShopifyRequestContext({request, i18n, buyerIp: getBuyerIp(request.headers)}),
config: {
storeDomain: env.PUBLIC_STORE_DOMAIN,
privateStorefrontToken: env.PRIVATE_STOREFRONT_API_TOKEN,
storefrontId: env.PUBLIC_STOREFRONT_ID,
cache,
waitUntil,
},
});
}
// Many stores run locally with only a public token — don't send them to mock.shop.
// Tokenless access can't read some fields (product tags, metaobjects, metafields, menus).
return createStorefrontClient({
type: 'public',
requestContext: createShopifyRequestContext({request, i18n}),
config: {
storeDomain: env.PUBLIC_STORE_DOMAIN,
publicStorefrontToken: env.PUBLIC_STOREFRONT_API_TOKEN,
storefrontId: env.PUBLIC_STOREFRONT_ID,
cache,
waitUntil,
},
});
}app/lib/route-templates.ts — maps Shopify entities to your route shapes. Pass it to handleShopifyRoutes (optional in the type, but handler-owned URLs come out wrong without it), to handleShopifyRedirects (required there), and to the routes prop of ShopifyScripts:
import {defineShopifyRouteTemplates} from '@shopify/hydrogen';
export const routeTemplates = defineShopifyRouteTemplates({
productInCollection: '/products/:productHandle',
});Classic data-layer call-sites map mechanically: storefront.query() → client.graphql(QUERY, {variables, cache}), which returns {data, errors, headers} instead of merging errors into the result — check errors before reading data; $country/$language are auto-injected, so drop them from variables; storefront.CacheLong() → the per-call Cache.long() (classic's implicit default caching is gone, so give every query that relied on it an explicit cache, Cache.short() or Cache.long(), or it hits the API on every request); storefront.i18n → client.locale (the resolved {language, country, pathPrefix}; client.i18n is a deprecated alias of it).
Root middleware in app/root.tsx (needs middleware enabled, see step 4) — the request lifecycle from mental-model step 1:
import {handleShopifyRedirects, handleShopifyRoutes} from '@shopify/hydrogen';
import {cartHandlers} from '~/lib/cart-handlers';
import {routeTemplates} from '~/lib/route-templates';
import {
createRequestStorefrontClient, envContext, storefrontClientContext, storefrontRequestContext,
} from '~/lib/storefront';
import type {Route} from './+types/root';
export const middleware: Route.MiddlewareFunction[] = [
async ({context, request}, next) => {
const env = context.get(envContext);
const storefrontClient = createRequestStorefrontClient(request, env, context.cache, context.waitUntil);
const requestContext = storefrontClient.requestContext; // reuse — a fresh one throws in handleShopifyRoutes
const shopifyRoute = handleShopifyRoutes({ // handler-owned paths (e.g. /api/cart) return early
request, requestContext, storefrontClient, routeTemplates, handlers: [cartHandlers], // cart handlers don't read the session
});
if (shopifyRoute) return shopifyRoute; // Promise<Response> or null — do NOT await the call
context.set(storefrontClientContext, storefrontClient);
context.set(storefrontRequestContext, requestContext);
const response = await next();
if (response.status === 404) { // 404 → Shopify URL redirects
const redirect = await handleShopifyRedirects({request, storefrontClient, routeTemplates});
if (redirect) return redirect; // headers already applied by the library
}
requestContext.applyResponseHeaders(response.headers); // MUST run or Shopify response headers vanish
return response;
},
];Session manager — only when a handler reads the session. Plain createCartServerHandlers() doesn't, so the cart-only middleware above passes no sessionManager. Customer Account handlers and cart handlers created with customerSession do, and handleShopifyRoutes then requires one at the type level. The sessionManager contract is four required methods (item values are typed unknown, not string) plus an optional commit() that returns cookie headers; after next(), append those headers to the response before the 404 check, as the template's root middleware does. For customer accounts, copy the template's cookie-backed createRequestSessionManager from app/lib/session.ts (a signed __Host-session cookie built on @remix-run/cookie + @remix-run/session, keyed by SESSION_SECRET). An in-memory map can't complete Customer Account login: the OAuth state is written on /account/login and read back on /account/authorize, two different requests. If you register the account handlers only when Customer Accounts are configured, as the template does, the handler types still require a session manager on every request. For requests without Customer Accounts, the template passes an in-memory stand-in:
import type {WritableCustomerSessionManager} from '@shopify/hydrogen/customer-account';
export function createEphemeralSessionManager(request: Request): WritableCustomerSessionManager {
const data = new Map<string, unknown>();
const origin = new URL(request.url).origin;
return {
getSessionOrigin: () => origin,
getSessionItem: (key) => data.get(key),
setSessionItem: (key, value) => {
data.set(key, value);
},
removeSessionItem: (key) => {
data.delete(key);
},
};
}Supporting files: app/lib/cart-handlers.ts → export const cartHandlers = createCartServerHandlers() (options: fragment to extend the cart query, customerSession to sync buyer identity — see references/cart.md); app/lib/cart.ts → createCartComponents<typeof cartHandlers>() yields CartProvider/useCart/useCartForm; when the store has customer accounts, add the createCustomerAccountServerHandlers({customerSession, …}) group next to cartHandlers in the middleware's handlers array and pass the cookie-backed session manager as sessionManager (see references/customer-account.md); react-router.config.ts → {buildDirectory: 'dist'} plus middleware enabled for your version of React Router (step 4).
Two lines in that middleware are easy to omit and fail silently: applyResponseHeaders on the normal response path (Shopify response headers disappear) and routeTemplates into both handler calls (handler-owned URLs and redirect targets come out wrong). A third, buyerIp into createShopifyRequestContext, fails loudly for the private client (TypeError: requestContext.buyerIp is required for private Storefront API clients) — keep the getBuyerIp helper rather than deleting the option to silence it. For the customer-account session wiring, follow the hydrogen-customer-account packaged skill rather than extending the in-memory stand-in by hand.
Optional subsystems
The outline above is the mandatory base; everything else (localization, customer accounts, analytics + consent, search, subscriptions, B2B, content routes, SEO/sitemap, gift cards, redirects, recommendations, third-party integrations) is store-specific. Before touching optional features, read references/optional-subsystems.md — it gives the detection grep for each, the sequence that matters (localization → auth → analytics+consent, since later ones consume the earlier ones' output, then the lower-coupling features in any order), and the rule to report every skip explicitly so a missing subsystem never reads as "migrated."
Traps by area — read the matching reference when you touch that area
Most "builds fine but silently broken at runtime" failures live in the references/ files below, grouped by the surface they hit. Read the file for a surface before you migrate that surface, and skip the ones the store doesn't have — don't preload them all. Loading only the relevant slice leaves context for the app's own files, which is what one-shot success actually depends on.
| Surface you're migrating | Read |
Dependencies, scripts, Vite config, .gitignore | references/dependencies-and-tooling.md |
Routes, loaders, @remix-run→react-router sweep, useMatches handles | references/routing-and-loaders.md |
TypeScript + gql (these surface at tsc / hydrogen gql check) | references/typescript-and-gql-tada.md |
Data layer call-sites: storefront.query, CacheLong(), i18n variables, generated types | this page's mapping above + references/typescript-and-gql-tada.md + the hydrogen-storefront-client packaged skill |
Cart drawer, /cart page, optimistic lines, initialData | references/cart.md |
| Customer accounts, OAuth, login | references/customer-account.md |
| Analytics + consent | references/analytics.md |
| Variant form, presentational primitives, pagination, a11y, dead client glue | references/ui-and-components.md |
| Sitemap / SEO | references/sitemap-and-seo.md |
Each file is a short list of the specific "it renders but is wrong" traps for that surface — the failures you can't discover by reading the installed package. For deploying to Oxygen, read the hydrogen-oxygen packaged skill; the seed's --assets-dir/--worker-dir flags are the template's layout, one of the layouts that skill accepts.
Verification
Don't trust "it renders." Gate on the build first: react-router build and react-router typegen && tsc && hydrogen gql check --fail-on-warn must both exit 0 (most import/return-helper and gql traps surface here — fix the root cause, don't suppress it; a red build makes everything downstream meaningless). Next, prove the root middleware actually runs: with the dev server up, GET /api/cart must return 200 JSON from the Hydrogen cart handler. A 404, or the app's own 404 page, means middleware isn't enabled for your React Router version (step 4), so cart routes, redirects, the storefront context and response headers are all silently skipped. Then run the local hydrogen-smoke-test skill for functional/runtime verification — request handlers, product, cart, collection/search, analytics, money, and the production pass. That skill owns "does the storefront work"; don't restate its checks here.
After the build gate and smoke test pass, keep the dev server running and load the home page in a browser. Fix every console error and warning before handing off. If you have no browser tool, say so in the handoff and ask the user to check the console themselves. Then hand off to the user. Tell them to test the migrated code with npm run dev (or npm run dev:https when they need customer login locally), and to pay special attention to the areas a migration most often gets subtly wrong while still compiling:
- CSP/nonce — use
createContentSecurityPolicy({shop})from@shopify/hydrogen. The returned policy exposesnonceandheader;csp.applyResponseHeaders()sends the policy and prevents nonce-bearing HTML from being cached. Apply Shopify request-context headers separately withrequestContext.applyResponseHeaders(response.headers). KeepNonceProvider/useNoncein app code and pass the nonce to the server renderer, framework scripts, andShopifyScripts. For cached HTML or a prerendered shell, usenonce: falseand authorize inline scripts explicitly; CSP then leaves cache headers unchanged. Move classic's top-level directive properties underdirectives; arrays still extend defaults, with a replacement exception for defaults consisting only of'none'. Convert source strings to arrays andfalseomissions tonull. ReviewdefaultSrccustomizations: the new policy has explicit script, image, font, media, and frame directives that take precedence over the fallback. The development build adds common local connection sources automatically. Seehydrogen-request-handlers/references/content-security-policy.mdfor the full migration comparison and framework wiring. A dropped nonce can silently prevent hydration — verify browser behavior after migrating. - Analytics — the commerce funnel (
view_item/add_to_cart/…) silently dropping while page views still fire (references/analytics.md). - Cart actions — add / remove / quantity edits and the drawer opening on add (
references/cart.md). - Customer login — the full OAuth round-trip, which needs an HTTPS origin locally (
references/customer-account.md). - Product variant selection — options must update client-side, not trigger a full route navigation (
references/ui-and-components.md).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

