[2025.7.0] Add changelog entry for Hydrogen 2025.7.0 release

[juanpprieto]

WHY are these changes introduced?

The Hydrogen 2025.7.0 release introduces major breaking changes including the migration from Remix to React Router 7.8.x and updates to Storefront API version 2025-07. The changelog.json file needs to be updated to enable the h2 upgrade command for developers migrating to this version.

Without this changelog entry, developers cannot use the CLI upgrade command to migrate their projects from 2025.4.x to 2025.7.0, leaving them to manually update dependencies and apply migration steps.

WHAT is this pull request doing?

This PR adds a comprehensive changelog entry for the Hydrogen 2025.7.0 release to docs/changelog.json. The entry documents all changes from the CI release PR #3166.

Key Dependency Changes

dependencies:
+ "@shopify/hydrogen": "2025.7.0" # Pinned version
+ "react-router": "7.9.2"         # Pinned version
+ "react-router-dom": "7.9.2"     # Pinned version
- "@shopify/remix-oxygen"         # Deprecated

devDependencies:
+ "@shopify/mini-oxygen": "4.0.0" # Pinned version
+ "@shopify/cli": "~3.83.3" 

Upgrading hydrogen-demo-store

WIP Generated upgrade-2025.4.1-to-2025.7.0.md

Details

Hydrogen upgrade guide: 2025.4.1 to 2025.7.0

---

Breaking changes

Migrate to React Router 7.9.x #3141

Step: 1. Run the automated migration codemod #3141

This codemod will automatically update most imports and references from Remix to React Router
#3141

npx codemod@latest remix/2/react-router/upgrade

Step: 2. Create react-router.config.ts with hydrogenPreset #3141

Create a React Router configuration file with Hydrogen's optimized preset for enhanced routing and build performance
#3141

// react-router.config.ts
import type {Config} from "@react-router/dev/config";
import {hydrogenPreset} from "@shopify/hydrogen/react-router-preset";

export default {
  presets: [hydrogenPreset()],
} satisfies Config;

Step: 3. Update vite.config.ts to use React Router plugin #3141

Replace the Remix Vite plugin with React Router's plugin and add vite-tsconfig-paths for better path resolution
#3141

// vite.config.ts
import {defineConfig} from 'vite';
- import {vitePlugin as remix} from '@remix-run/dev';
+ import {reactRouter} from '@react-router/dev/vite';
import {hydrogen} from '@shopify/hydrogen/vite';
import {oxygen} from '@shopify/mini-oxygen/vite';
+ import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [
+   hydrogen(),
+   oxygen(),
+   reactRouter(),
+   tsconfigPaths()
-   remix({
-     presets: [hydrogen.preset()],
-   }),
  ],
});

Step: 4. Update tsconfig.json for React Router type generation #3141

Update TypeScript configuration to include React Router's generated types and optimize type checking
#3141

// tsconfig.json
{
  "include": [
    "env.d.ts",
    "app/**/*.ts",
    "app/**/*.tsx",
+   "app/**/*.d.ts",
+   "*.ts",
+   "*.tsx",
+   "*.d.ts",
+   ".graphqlrc.ts",
+   ".react-router/types/**/*"
-   "**/*.ts",
-   "**/*.tsx"
  ],
  "compilerOptions": {
    "types": [
      "@shopify/oxygen-workers-types",
+     "react-router",
+     "@shopify/hydrogen/react-router-types",
+     "vite/client"
-     "@remix-run/node",
-     "vite/client"
    ],
+   "rootDirs": [".", "./.react-router/types"],
    "baseUrl": ".",
    "paths": {
      "~/*": ["app/*"]
    }
  }
}

Step: 5. Create app/lib/context.ts with createHydrogenRouterContext #3141

Create a new context file that exports createHydrogenRouterContext function with support for additional context properties and type augmentation
#3141

// app/lib/context.ts
import {createHydrogenContext} from '@shopify/hydrogen';
import {AppSession} from '~/lib/session';
import {CART_QUERY_FRAGMENT} from '~/lib/fragments';

const additionalContext = {
  // Additional context for custom properties, CMS clients, 3P SDKs, etc.
} as const;

type AdditionalContextType = typeof additionalContext;

declare global {
  interface HydrogenAdditionalContext extends AdditionalContextType {}
}

export async function createHydrogenRouterContext(
  request: Request,
  env: Env,
  executionContext: ExecutionContext,
) {
  if (!env?.SESSION_SECRET) {
    throw new Error('SESSION_SECRET environment variable is not set');
  }

  const waitUntil = executionContext.waitUntil.bind(executionContext);
  const [cache, session] = await Promise.all([
    caches.open('hydrogen'),
    AppSession.init(request, [env.SESSION_SECRET]),
  ]);

  const hydrogenContext = createHydrogenContext(
    {
      env,
      request,
      cache,
      waitUntil,
      session,
      i18n: {language: 'EN', country: 'US'},
      cart: {
        queryFragment: CART_QUERY_FRAGMENT,
      },
    },
    additionalContext,
  );

  return hydrogenContext;
}

Step: 6. Update server.ts to use createHydrogenRouterContext #3141

Replace @shopify/remix-oxygen with @shopify/hydrogen/oxygen and use the new context creation function with session handling
#3141

// server.ts
- import {createRequestHandler} from "@shopify/remix-oxygen";
+ import {createRequestHandler} from "@shopify/hydrogen/oxygen";
+ import {createHydrogenRouterContext} from "~/lib/context";

export default {
  async fetch(request: Request, env: Env, executionContext: ExecutionContext): Promise<Response> {
+   const hydrogenContext = await createHydrogenRouterContext(
+     request,
+     env,
+     executionContext,
+   );

    const handleRequest = createRequestHandler({
-     build: await import('virtual:remix/server-build'),
+     build: await import('virtual:react-router/server-build'),
      mode: process.env.NODE_ENV,
-     getLoadContext: () => ({...}),
+     getLoadContext: () => hydrogenContext,
    });

    const response = await handleRequest(request);
+
+   if (hydrogenContext.session.isPending) {
+     response.headers.set('Set-Cookie', await hydrogenContext.session.commit());
+   }

    return response;
  }
};

Step: 7. Update entry.server.tsx with new context types #3141

Replace Remix types with React Router types and use HydrogenRouterContextProvider for enhanced type safety
#3141

// app/entry.server.tsx
- import type {AppLoadContext} from "@shopify/remix-oxygen";
- import type {EntryContext} from "@remix-run/server-runtime";
+ import type {EntryContext} from "react-router";
import {
  createContentSecurityPolicy,
+ type HydrogenRouterContextProvider,
} from "@shopify/hydrogen";

export default async function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
- remixContext: EntryContext,
+ reactRouterContext: EntryContext,
- context: AppLoadContext,
+ context: HydrogenRouterContextProvider,
) {
  const {nonce, header, NonceProvider} = createContentSecurityPolicy({...});

  const body = await renderToReadableStream(
    <NonceProvider>
      <ServerRouter
-       context={remixContext}
+       context={reactRouterContext}
        url={request.url}
        nonce={nonce}
      />
    </NonceProvider>,
  );
}

Step: 8. Update entry.client.tsx with NonceProvider and HydratedRouter #3141

Replace RemixBrowser with HydratedRouter and wrap with NonceProvider for CSP support during client-side hydration
#3141

// app/entry.client.tsx
- import {RemixBrowser} from "@remix-run/react";
+ import {HydratedRouter} from "react-router/dom";
import {startTransition, StrictMode} from "react";
import {hydrateRoot} from "react-dom/client";
+ import {NonceProvider} from "@shopify/hydrogen";

if (!window.location.origin.includes("webcache.googleusercontent.com")) {
  startTransition(() => {
+   const existingNonce = document
+     .querySelector<HTMLScriptElement>("script[nonce]")
+     ?.nonce;
+
    hydrateRoot(
      document,
      <StrictMode>
-       <RemixBrowser />
+       <NonceProvider value={existingNonce}>
+         <HydratedRouter />
+       </NonceProvider>
      </StrictMode>,
    );
  });
}

Step: 9. Update @shopify/remix-oxygen imports in route files #3141

Replace @shopify/remix-oxygen imports with react-router equivalents in your route files
#3141

- import {redirect, type LoaderFunctionArgs} from "@shopify/remix-oxygen";
+ import {redirect} from "react-router";
+ import type {LoaderFunctionArgs} from "@shopify/hydrogen/oxygen";

Step: 10. Update @remix-run/react imports in route files #3141

Replace @remix-run/react imports with react-router equivalents in your route files
#3141

- import {useLoaderData, type MetaFunction} from "@remix-run/react";
+ import {useLoaderData} from "react-router";

Step: 11. Add React Router 7 route type imports #3141

Import route-specific types from React Router 7's new type generation system
#3141

+ import type {Route} from "./+types/route-name";

Step: 12. Add .react-router to .gitignore #3141

React Router 7 generates type files that should not be committed to version control
#3141

echo ".react-router/" >> .gitignore

Step: 13. Update package.json scripts to use react-router typegen #3141

Add React Router type generation to your dev script for automatic type updates during development
#3141

- "dev": "shopify hydrogen dev --codegen",
+ "dev": "react-router typegen --watch && shopify hydrogen dev --codegen",

Step: 14. Verify your app starts and builds correctly #3141

Test that your application runs without errors after the migration
#3141

npm run dev
npm run build

---

Features

Added countryCode parameter to Customer Account API methods #3148

Add countryCode parameter to Customer Account API method calls

Pass the customer account country code to any Customer Account API method. Example shown with login method.
#3148

// app/routes/account_.login.tsx (example)
export async function loader({request, context}: Route.LoaderArgs) {
  return context.customerAccount.login({
+   countryCode: context.customerAccount.i18n.country,
  });
}

// The countryCode parameter is now available on all Customer Account API methods
// and can be passed from context.customerAccount.i18n.country

Add support for removing individual gift cards from cart #3128

Step: 1. Add GiftCardCodesRemove case to cart action handler #3128

Handle the new GiftCardCodesRemove action in your cart route to enable individual gift card removal
#3128

// app/routes/cart.tsx
export async function action({request, context}: Route.ActionArgs) {
  const {cart} = context;
  const formData = await request.formData();
  const {action, inputs} = CartForm.getFormInput(formData);

  switch (action) {
    // ... existing cases ...
+   case CartForm.ACTIONS.GiftCardCodesRemove: {
+     const appliedGiftCardIds = inputs.giftCardCodes as string[];
+     result = await cart.removeGiftCardCodes(appliedGiftCardIds);
+     break;
+   }
  }
}

Step: 2. Add RemoveGiftCardForm component #3128

Create a new form component to handle individual gift card removal
#3128

// app/components/CartSummary.tsx
+function RemoveGiftCardForm({
+  giftCardId,
+  children,
+}: {
+  giftCardId: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <CartForm
+      route="/cart"
+      action={CartForm.ACTIONS.GiftCardCodesRemove}
+      inputs={{
+        giftCardCodes: [giftCardId],
+      }}
+    >
+      {children}
+    </CartForm>
+  );
+}

Step: 3. Update CartGiftCard to display gift cards with remove buttons #3128

Render applied gift cards with individual remove buttons for better UX
#3128

// app/components/CartSummary.tsx
function CartGiftCard({giftCardCodes}: {...}) {
  return (
    <div>
+     {giftCardCodes && giftCardCodes.length > 0 && (
+       <dl>
+         <dt>Applied Gift Card(s)</dt>
+         {giftCardCodes.map((giftCard) => (
+           <RemoveGiftCardForm key={giftCard.id} giftCardId={giftCard.id}>
+             <div className="cart-discount">
+               <code>***{giftCard.lastCharacters}</code>
+               <Money data={giftCard.amountUsed} />
+               <button type="submit">Remove</button>
+             </div>
+           </RemoveGiftCardForm>
+         ))}
+       </dl>
+     )}
    </div>
  );
}

Add order filtering support to Customer Account API orders route #3125

Step: 1. Create app/lib/orderFilters.ts utility #3125

Create helper functions to parse URL parameters and build Customer Account API search queries
#3125

// app/lib/orderFilters.ts
export const ORDER_FILTER_FIELDS = {
  NAME: 'name',
  CONFIRMATION_NUMBER: 'confirmation_number',
} as const;

export interface OrderFilterParams {
  name?: string;
  confirmationNumber?: string;
}

function sanitizeFilterValue(value: string): string {
  return value.replace(/[^a-zA-Z0-9_\-]/g, '');
}

export function buildOrderSearchQuery(
  filters: OrderFilterParams,
): string | undefined {
  const queryParts: string[] = [];

  if (filters.name) {
    const cleanName = filters.name.replace(/^#/, '').trim();
    const sanitizedName = sanitizeFilterValue(cleanName);
    if (sanitizedName) {
      queryParts.push(`name:${sanitizedName}`);
    }
  }

  if (filters.confirmationNumber) {
    const cleanConfirmation = filters.confirmationNumber.trim();
    const sanitizedConfirmation = sanitizeFilterValue(cleanConfirmation);
    if (sanitizedConfirmation) {
      queryParts.push(`confirmation_number:${sanitizedConfirmation}`);
    }
  }

  return queryParts.length > 0 ? queryParts.join(' AND ') : undefined;
}

export function parseOrderFilters(
  searchParams: URLSearchParams,
): OrderFilterParams {
  const filters: OrderFilterParams = {};

  const name = searchParams.get(ORDER_FILTER_FIELDS.NAME);
  if (name) filters.name = name;

  const confirmationNumber = searchParams.get(ORDER_FILTER_FIELDS.CONFIRMATION_NUMBER);
  if (confirmationNumber) filters.confirmationNumber = confirmationNumber;

  return filters;
}

Step: 2. Update loader to parse filters and build search query #3125

Parse URL search parameters and build the Customer Account API query string for order filtering
#3125

// app/routes/account.orders._index.tsx
+import {
+  buildOrderSearchQuery,
+  parseOrderFilters,
+  type OrderFilterParams,
+} from '~/lib/orderFilters';

export async function loader({request, context}: Route.LoaderArgs) {
  const {customerAccount} = context;
  const paginationVariables = getPaginationVariables(request, {
    pageBy: 20,
  });

+ const url = new URL(request.url);
+ const filters = parseOrderFilters(url.searchParams);
+ const query = buildOrderSearchQuery(filters);

  const {data, errors} = await customerAccount.query(CUSTOMER_ORDERS_QUERY, {
    variables: {
      ...paginationVariables,
+     query,
      language: customerAccount.i18n.language,
    },
  });

  if (errors?.length || !data?.customer) {
    throw Error('Customer orders not found');
  }

- return {customer: data.customer};
+ return {customer: data.customer, filters};
}

Step: 3. Add OrderSearchForm component #3125

Create a search form with order number and confirmation number inputs
#3125

// app/routes/account.orders._index.tsx
+import {useSearchParams, useNavigation} from 'react-router';
+import {useRef} from 'react';
+import {ORDER_FILTER_FIELDS} from '~/lib/orderFilters';

+function OrderSearchForm({currentFilters}: {currentFilters: OrderFilterParams}) {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const navigation = useNavigation();
+  const isSearching = navigation.state !== 'idle' && navigation.location?.pathname?.includes('orders');
+  const formRef = useRef<HTMLFormElement>(null);
+
+  const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const formData = new FormData(event.currentTarget);
+    const params = new URLSearchParams();
+
+    const name = formData.get(ORDER_FILTER_FIELDS.NAME)?.toString().trim();
+    const confirmationNumber = formData.get(ORDER_FILTER_FIELDS.CONFIRMATION_NUMBER)?.toString().trim();
+
+    if (name) params.set(ORDER_FILTER_FIELDS.NAME, name);
+    if (confirmationNumber) params.set(ORDER_FILTER_FIELDS.CONFIRMATION_NUMBER, confirmationNumber);
+
+    setSearchParams(params);
+  };
+
+  return (
+    <form ref={formRef} onSubmit={handleSubmit}>
+      <input type="search" name={ORDER_FILTER_FIELDS.NAME} placeholder="Order #" defaultValue={currentFilters.name || ''} />
+      <input type="search" name={ORDER_FILTER_FIELDS.CONFIRMATION_NUMBER} placeholder="Confirmation #" defaultValue={currentFilters.confirmationNumber || ''} />
+      <button type="submit" disabled={isSearching}>{isSearching ? 'Searching' : 'Search'}</button>
+    </form>
+  );
+}

Step: 4. Update Orders component to use filters and add EmptyOrders #3125

Pass filters to components and add conditional empty state messaging based on whether filters are active
#3125

// app/routes/account.orders._index.tsx
export default function Orders() {
- const {customer} = useLoaderData<OrdersLoaderData>();
+ const {customer, filters} = useLoaderData<OrdersLoaderData>();
  const {orders} = customer;

  return (
    <div className="orders">
+     <OrderSearchForm currentFilters={filters} />
-     <OrdersTable orders={orders} />
+     <OrdersTable orders={orders} filters={filters} />
    </div>
  );
}

-function OrdersTable({orders}: {orders: CustomerOrdersFragment['orders']}) {
+function OrdersTable({orders, filters}: {orders: CustomerOrdersFragment['orders']; filters: OrderFilterParams}) {
+  const hasFilters = !!(filters.name || filters.confirmationNumber);
+
  return (
    <div>
      {orders?.nodes.length ? (
        <PaginatedResourceSection connection={orders}>
          {({node: order}) => <OrderItem key={order.id} order={order} />}
        </PaginatedResourceSection>
      ) : (
-       <p>You haven't placed any orders yet.</p>
+       <EmptyOrders hasFilters={hasFilters} />
      )}
    </div>
  );
}

+function EmptyOrders({hasFilters}: {hasFilters?: boolean}) {
+  return hasFilters ? (
+    <p>No orders found matching your search. <Link to="/account/orders">Clear filters</Link></p>
+  ) : (
+    <p>You haven't placed any orders yet.</p>
+  );
+}

Add fulfillmentStatus to Customer Account API order query #3039-fulfillment

Add fulfillmentStatus field to Order fragment

Include fulfillmentStatus in your Customer Account API order queries
#3039-fulfillment

// app/graphql/customer-account/CustomerOrderQuery.ts
fragment Order on Order {
  id
  name
  confirmationNumber
  statusPageUrl
+ fulfillmentStatus
  processedAt
  fulfillments(first: 1) {
    nodes {
      status
    }
  }
}

Add @incontext language support to Customer Account API mutations #3039-incontext

Add @incontext directive to all Customer Account API operations

Add $language parameter and @incontext directive to queries and mutations for localized content
#3039-incontext

// app/graphql/customer-account/*.ts (apply to all queries and mutations)
// Example: CustomerDetailsQuery.ts
- query CustomerDetails {
+ query CustomerDetails($language: LanguageCode) @inContext(language: $language) {
    customer {
      ...Customer
    }
  }

// Example: CustomerAddressMutations.ts  
  mutation CustomerAddressUpdate(
    $address: MailingAddressInput!
    $addressId: ID!
    $defaultAddress: Boolean
+   $language: LanguageCode
- ) {
+ ) @inContext(language: $language) {
    customerAddressUpdate(...)
  }

// Apply this pattern to all Customer Account API queries and mutations:
// - CustomerDetailsQuery.ts
// - CustomerOrderQuery.ts
// - CustomerOrdersQuery.ts
// - CustomerUpdateMutation.ts
// - CustomerAddressMutations.ts (all 3 mutations)

Add GraphQL @defer directive support to storefront client #2993

Use @defer directive in Storefront API queries

Wrap non-critical fields with @defer to improve initial page load performance
#2993

// app/routes/your-route.tsx (example)
+import {LoaderFunctionArgs, useLoaderData} from 'react-router';

export async function loader({context}: LoaderFunctionArgs) {
  const data = await context.storefront.query(
    `
  query ProductQuery($handle: String) {
    product(handle: $handle) {
      id
      handle
+     ... @defer(label: "deferredFields") {
+       title
+       description
+     }
    }
  }
`,
    {
      variables: {
        handle: 'v2-snowboard',
      },
    },
  );
  return data;
}

// The @defer directive allows you to defer loading of non-critical fields
// improving initial page load performance

---

---

Fixes

Stabilize Customer Account API development flag #3082-flag

Update command to use stable flag

Remove the __unstable suffix from the customer-account-push command
#3082-flag

- shopify hydrogen customer-account-push__unstable [flags]
+ shopify hydrogen customer-account-push [flags]

// The --customer-account-push flag is now stable and no longer requires __unstable suffix

Add TypeScript ESLint rules for promise handling #3146

Add promise handling rules to ESLint config

Enable no-floating-promises and no-misused-promises rules to catch unhandled promises that cause deployment failures
#3146

// eslint.config.js
export default tseslint.config(
  {
    rules: {
      // ... existing rules ...
+     '@typescript-eslint/no-floating-promises': 'error',
+     '@typescript-eslint/no-misused-promises': 'error',
    },
  },
);

// These rules prevent unhandled promises and promise misuse
// Helps avoid 'The script will never generate a response' errors on Oxygen/Cloudflare Workers

Post-merge steps

After merging:

1. Changelog will be available at https://hydrogen.shopify.dev/changelog.json
2. Developers can immediately use h2 upgrade to migrate to 2025.7.0

Checklist

• I've read the Contributing Guidelines
• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've added a changeset if this PR contains user-facing or noteworthy changes
• I've added tests to cover my changes
• I've added or updated the documentation

[shopify]

Oxygen deployed a preview of your upgrade-2025-7-0 branch. Details:

Storefront	Status	Preview link	Deployment details	Last update (UTC)
Skeleton (skeleton.hydrogen.shop)	✅ Successful (Logs)	Preview deployment	Inspect deployment	September 30, 202511:12 PM

Learn more about Hydrogen's GitHub integration.

[github-actions]

We detected some changes in packages/*/package.json or packages/*/src, and there are no updates in the .changeset.
If the changes are user-facing and should cause a version bump, run npm run changeset add to track your changes and include them in the next release CHANGELOG.
If you are making simple updates to examples or documentation, you do not need to add a changeset.