Updates

Our latest release delivers major improvements to the Hydrogen toolkit, adding support for the Storefront API 2025-07 and updating key dependencies like React Router 7.9.2 and Miniflare v3.

With this release, we’re making sure it’s clear which configurations are supported out of the box by pinning to specific versions of dependencies by default in the provided package.json file. You can still update or enable different RR7 feature flags, but note that those paths might introduce breaking changes.

This release also makes vibe coding with Hydrogen even better, and includes 10 new ways to easily extend and customize your build. We’ve replaced the set of static feature templates with new additions to the Hydrogen Cookbook, adding new recipes for use cases like working with metaobjects, using infinite scroll for pagination, building for B2B, and more.

Here’s the full breakdown of everything included in this release:

React Router 7 updates

Hydrogen is now up to date with the latest version of React Router, which means developers can now get access to two big benefits:

1. Route Module Type Safety: React Router now automatically generates route-specific types to power type inference for URL params, loader data, and more.
2. Middleware: Middleware lets you run code before and after the Response generation for the matched path. This enables common patterns like authentication, logging, error handling, and data preprocessing in a reusable way.

To start using middleware and working with the new context object format in React Router, we’ve added a createHydrogenContext helper and a HydrogenRouterContextProvider type to make integrating with Hydrogen simple.

For full details on React Router, refer to the v7.9.2 changelog.

Miniflare v3

Local development has been upgraded to use Miniflare v3, based on workerd. Hydrogen’s CLI already used a workerd runtime (unlike Miniflare v2), so you won’t see any changes to your local development workflow—but if you had seen deprecation warnings about Miniflare v2, those are now gone.

Storefront API 2025-07 support

• USDC currency support: The Money component and useMoney hook have been updated, adding support for USDC.
• Hydrogen’s default scaffold now has improved order filtering support, letting customers filter their orders by fulfillmentStatus.
• For full changes to the GraphQL APIs, refer to the Customer Accounts API and Storefront API changelogs.

Hydrogen Cookbook updates

The --template flag has been removed from the init command, and our previous Example templates have now been replaced with individual recipes in the Hydrogen Cookbook.

We’ve added new Cookbook recipes for:

• B2B
• Customer cart methods
• Express
• GTM
• Infinite scroll
• Legacy customer account flow
• Markets (improved)
• Metaobjects
• Partytown
• Third-party APIs

Updates, optimizations, and fixes

As always, this release includes additional optimizations, bug fixes, and quality-of-life improvements.

To take advantage of all the latest features and improvements in Hydrogen, run npx shopify hydrogen upgrade.

Future Flag Migration for React Router 7

Before upgrading to React Router 7, you need to make sure to adopt all Remix future flags. The CLI upgrade command (npx shopify hydrogen upgrade) provides guides on how to do this, but this guide consolidates all the steps.

First of all, the legacy classic Remix compiler is no longer supported, and you must upgrade to Vite if you haven't already. After running npx shopify hydrogen upgrade, run npx shopify hydrogen setup vite to migrate to Vite.

Next enable each of these future flags. It's easiest to do one at a time, making sure the app is functional after each step. At the end you should have all future flags enabled within the remix vite plugin:

Code Example
Copy

remix({
  presets: [hydrogen.v3preset()],
  future: {
    v3_fetcherPersist: true,
    v3_relativeSplatPath: true,
    v3_throwAbortReason: true,
    v3_lazyRouteDiscovery: true,
    v3_routeConfig: true,
    v3_singleFetch: true,
  },
})
  

v3_fetcherPersist

Enabling this flag is unlikely to affect your app. See the Remix docs for more information.

v3_relativeSplatPath

If you have any routes with a path + a splat like dashboard.$.tsx that have relative links like <Link to="relative"> or <Link to="../relative"> beneath it, you will need to update your code.

See the Remix docs for more information.

v3_throwAbortReason

When a server-side request is aborted, such as when a user navigates away from a page before the loader finishes, Remix will throw the request.signal.reason instead of an error like new Error("query() call aborted..."). Enabling this is unlikely to affect your app.

See the Remix docs for more information.

v3_lazyRouteDiscovery

Unlikely to affect your app. See the Remix docs for more information.

v3_singleFetch

Single Fetch is a new data loading strategy and streaming format. For more detailed upgrade instructions, see the v3_singleFetch PR or refer to the Remix guide.

1. In your entry.server.tsx, add nonce to the <RemixServer>:

   Code Example
   Copy
   
   const body = await renderToReadableStream(
     <NonceProvider>
       <RemixServer
         context={remixContext}
         url={request.url}
   +     nonce={nonce}
       />
     </NonceProvider>
   );

2. Return plain objects from loaders and actions instead of using json or defer:

   Code Example
   Copy
   
   // Before
   import {json} from "@shopify/remix-oxygen";
   
   export async function loader({}: LoaderFunctionArgs) {
     let tasks = await fetchTasks();
     return json(tasks);
   }
   
   // After
   export async function loader({}: LoaderFunctionArgs) {
     let tasks = await fetchTasks();
     return tasks;
   }
         

   Code Example
   Copy
   
   // When setting headers
   import {data} from "@shopify/remix-oxygen";
   
   export async function loader({}: LoaderFunctionArgs) {
     let tasks = await fetchTasks();
     return data(tasks, {
       headers: {
         "Cache-Control": "public, max-age=604800"
       }
     });
   }
         

Update your shouldRevalidate in root.tsx:

Code Example
Copy

export const shouldRevalidate: ShouldRevalidateFunction = ({
 formMethod,
 currentUrl,
 nextUrl,
}) => {
  if (formMethod && formMethod !== 'GET') return true;
  if (currentUrl.toString() === nextUrl.toString()) return true;

  // Defaulting to no revalidation for root loader data to improve performance.
  // When using this feature, you risk your UI getting out of sync with your server.
  // Use with caution. If you are uncomfortable with this optimization, update the
  // line below to `return defaultShouldRevalidate` instead.
  // For more details see: https://remix.run/docs/en/main/route/should-revalidate
  return false;
};
  

v3_routeConfig

Config-based routing is the new default in React Router v7, configured via the routes.ts file. Support for routes.ts in Remix is a migration path toward React Router v7.

1. Install the package: npm install -D @remix-run/route-config @remix-run/route-config
2. Add a routes.ts file:

   Code Example
   Copy
   
   import {flatRoutes} from '@remix-run/fs-routes';
   import {type RouteConfig} from '@remix-run/route-config';
   import {hydrogenRoutes} from '@shopify/hydrogen';
   
   export default hydrogenRoutes([
     ...(await flatRoutes()),
   ]) satisfies RouteConfig;
         

Update vite.config.js to use hydrogen.v3preset() and enable v3_routeConfig:

Code Example
Copy

export default defineConfig({
  plugins: [
    hydrogen(),
    oxygen(),
    remix({
      presets: [hydrogen.v3preset()],
      future: {
        v3_fetcherPersist: true,
        v3_relativeSplatPath: true,
        v3_throwAbortReason: true,
        v3_lazyRouteDiscovery: true,
        v3_singleFetch: true,
        v3_routeConfig: true,
      },
    }),
    tsconfigPaths(),
  ],
});
  

See the Remix docs for more information.

Welcome to the April release! In this release, we bring fixes to internationalization, cart functionality, and template improvements. Let's dive into what's new.

Internationalization Improvements

Fixed duplicate content issues with internationalized product handles (#2821). Previously, translated product handles could create duplicate content at multiple URLs. For example:

https://hydrogen.shop/de-de/products/das-chaos
https://hydrogen.shop/de-de/products/the-havoc

The starter template now redirects to the localized URL, improving SEO and user experience.

Cart and Customer Account Enhancements

• Fixed cart quantity validation (#2855)
• Improved customer account logout handling (#2843)
  • Now clears all session data by default
  • Added keepSession option for custom data retention

Product Management Updates

• Deprecated <VariantSelector /> (#2837)
  • We recommend using the getProductOptions utility instead.
  • Please refer to the implementation in our skeleton template, which has already made this transition
• Refactored ProductItem into a separate component (#2872)

Cart Delivery Features

Added support for cart delivery address mutations (#2850):

• cartDeliveryAddressesAdd

• cartDeliveryAddressesRemove

• cartDeliveryAddressesUpdate

Migration Notes

Upgrading from VariantSelector

When migrating from VariantSelector to getProductOptions:

1. Update SFAPI product query with new fields:

• • encodedVariantExistence
  • encodedVariantAvailability

1. Remove VARIANTS_QUERY from loadDeferredData
2. Update Product component to use getAdjacentAndFirstAvailableVariants
3. Implement URL parameter handling for variant selection

For more detailed instructions, please refer to the changelog.

To take advantage of all the latest features and improvements in Hydrogen, just run npx shopify hydrogen upgrade. That’s it for the April release!

Welcome to our March release! In this release, we’ve added support for Vite 6 and the Remix v3_routeConfig future flag. 

Support for Vite 6

Hydrogen has completed the migration from Vite 5 to Vite 6, following the Remix upgrade to Vite 6 in version 2.16.0. Vite 6 offers performance enhancements and improved HMR (Hot Module Replacement). If you have any custom Vite integrations, please refer to vite migration guide for more information.

Turn on Remix future flag: v3_routeConfig

Remix is merging with React Router 7. Enabling v3_routeConfig future flag is the recommended migration path to React Router 7.

Update your vite.config.ts:

   export default defineConfig({
  plugins: [
    hydrogen(),
    oxygen(),
    remix({
      presets: [hydrogen.v3preset()], // Update this to hydrogen.v3preset()
      future: {
        v3_fetcherPersist: true,
        v3_relativeSplatPath: true,
        v3_throwAbortReason: true,
        v3_lazyRouteDiscovery: true,
        v3_singleFetch: true,
        v3_routeConfig: true, // add this flag
      },
    }),
    tsconfigPaths(),
  ],

Update your package.json and install the new packages. Make sure to match the Remix version along with other Remix npm packages and ensure the versions are 2.16.1 or above:

"devDependencies": {
 ...
 "@remix-run/fs-routes": "^2.16.1",
 "@remix-run/route-config": "^2.16.1",

Add a routes.ts file. This is your new Remix route configuration file.

export default hydrogenRoutes([
  ...(await flatRoutes()),
  // Manual route definitions can be added to this array, in addition to or instead of using the `flatRoutes` file-based routing convention.
  // See https://remix.run/docs/en/main/guides/routing for more details
]) satisfies RouteConfig;

For more detailed upgrade instructions, see the v3_routeConfig PR or refer to the Remix guide.

To take advantage of all the latest features and improvements in Hydrogen, just run npx shopify hydrogen upgrade. That’s it for the March release — see you in April!