Migrate to Hydrogen 3 (storefront-kit working version, Remix → React Router 7)

[lucyxiang]

What

Migrates the demo store from Remix to React Router 7 on Hydrogen 3, now targeting the storefront-kit working version Hydrogen 3 is consumed as a server-handler library you compose, not a framework that owns the request.

• Vendored package: @shopify/hydrogen@0.0.1 is unpublished (storefront-kit workspace pkg), so it is packed to vendor/shopify-hydrogen-0.0.1.tgz and installed via a file: dependency.
• CLI dev restored: shopify hydrogen dev|build work again. The hydrogen() Vite plugin now ships in @shopify/hydrogen-classic/vite (@shopify/hydrogen-classic = npm:@shopify/hydrogen@2026.4.2); the CLI injects .env into MiniOxygen and serves /graphiql + /subrequest-profiler.
• Server-handler wiring (app/storefront.middleware.ts): createShopifyRequestContext → createStorefrontClient (private) → handleShopifyRoutes with cartHandlers → handleShopifyRedirects on 404, plus the customer-account client and session commit.
• Customer account (app/lib/customer-account.server.ts): a compat wrapper over @shopify/hydrogen/customer-account (createCustomerSession → prepareLoginUrl/handleOAuthCallback/logout), replacing the hand-rolled OAuth URL.
• Version set aligned to storefront-kit: react-router/@react-router/* 7.15.1, @shopify/cli 3.94.3, @shopify/mini-oxygen 4.1.0, vite ^8, React 18.3.1.

What the initial (preview) migration did NOT get right vs production

The first pass (npm 0.0.0-preview build) shipped several regressions against prod (hydrogen.shop). Status after this re-migration:

#	Initial-migration defect vs prod	Root cause	Status now
1	/account/login returned 400	Hand-rolled OAuth URL used the wrong path — …/auth/oauth/authorize instead of …/oauth/authorize. (The client_id was correct all along — the raw PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID UUID, not a shp_ value; that earlier theory was wrong.)	✅ Fixed — URL now built by @shopify/hydrogen/customer-account. Verified the constructed URL (path, redirect_uri, scope, PKCE). Local login requires an HTTPS tunnel (library refuses http origins by design); works on prod https.
2	Add-to-cart worked but the drawer never opened (and the quantity control looked off)	The client uses the library useCartForm(), which submits through its own cart store (store.handleFormSubmit + preventDefault), so React Router's useFetchers() never sees the request — the ported useCartFetchers drawer trigger could never fire. The quantity field also rendered the interactive <input>'s native chrome.	✅ Fixed — AddToCartButton rewritten on useCartForm(); the drawer now opens off the cart store via useCart((s) => s.pending.lines.size > 0) (a mutation signal, not absolute totalQuantity, which would auto-open on every page load). Quantity control restyled to match prod. /api/cart verified: POST intent=add → 303 + CartCreate + cart cookie; GET returns totalQuantity:1.
3	/collections/$handle pagination: "Next" button vs prod's "Load more" infinite-append	Hydrogen 3 removed <Pagination> + getPaginationVariables (confirmed still absent in 0.0.1); needs hand-rolled accumulate + IntersectionObserver	⚠️ Open — re-verified (2026-07-01): /collections/freestyle dev renders 12 products + "Next" (height 1926px) vs prod's full grid + "Load more products" (height 3684px). /products (=/collections/all) matches. This is the one remaining browse regression.
4	404 page missing the "Featured Products" swimlane; page never reached network-idle	Deferred (defer/<Await>) featured-data loader appeared to hang after the RR7 migration	✅ Resolved — re-verified (2026-07-01): dev's /notfound now renders the Featured Products swimlane pixel-identical to prod (heights match, 1451px). The deferred <Await> path works on this build.

Install notes

• Use npm, not pnpm. pnpm symlinks @shopify/hydrogen into .pnpm/, which defeats the Shopify CLI's realpath-based Hydrogen-project detection ("…outside of a Hydrogen project"). npm's flat install keeps it a real dir under the project root.
• legacy-peer-deps=true in .npmrc — @shopify/hydrogen-classic peers an exact @react-router/dev that differs from the app's pin.

Functional parity vs the previous store

This is a like-for-like port, not a feature addition — there is no net-new user-facing functionality:

• Route set is identical (32 route files before and after; none added or removed).
• Capabilities that look new already existed in the Hydrogen 2 store: OAuth customer login, CSP nonces, and Shopify analytics.
• The ~20 "new" files (Image, Money, MediaFile, Pagination, flatten-connection, csp/nonce, analytics, customer-account.server, …) are local reimplementations of things @shopify/hydrogen used to provide, because Hydrogen 3 is a slim server-handler library rather than a batteries-included framework. Pagination is currently a regression (see item 3 above), not a new feature.

Post-migration improvements (this PR)

Small, functionality-preserving polish surfaced by comparing against the storefront-kit examples/react-router template:

• Typed GraphQL was silently off. tsconfig pointed the gql.tada plugin at a nonexistent src/graphql/… schema path. Repointed to the packaged dist/*.schema.json under named storefront + customer-account schemas, and added gql.tada check to typecheck so query/field type errors fail the build.
• Accessibility. The skip-to-content link was permanently sr-only (unusable by keyboard) — now reveals on focus; #mainContent is focused on route change; the cart trigger got an accessible name + aria-haspopup.
• Local customer login. Added dev:customer (shopify hydrogen dev --customer-account-push) so the Customer Account OAuth flow works locally over the CLI tunnel (satisfies the HTTPS-origin requirement).
• Dead code. Removed the orphaned useCartFetchers hook (unused after the cart-drawer fix).

Notes

• .env is not committed with private tokens (shpat_ / PRIVATE_STOREFRONT_API_TOKEN stay local; only PUBLIC_* + SESSION_SECRET + SHOP_ID are tracked, pre-existing).
• Route-by-route pixel comparison re-run (2026-07-01) across home, collections, collection, products-all, product, journal, 404. All layouts match prod except item 3; item 4 now resolved. Remaining diff is the /collections/$handle load-more pagination (item 3); draft until that reaches parity.

🤖 Generated with Claude Code