Add GraphQL @defer directive support to storefront client

[blittle]

Add PoC support for @defer in GraphQL queries. Hydrogen doesn't use @shopify/graphql-client, because we have a lot of custom caching and request tracking. @defer support was implemented in @shopify/graphql-client, and it's not trivial. This PoC adds support by conditionally calling the @shopify/graphql-client when we detect @defer is used. It's awkward though, because that client doesn't expose the raw Response object, so I have it overriding fetch just to get at the Response object.

Test it out by adding the following route:

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;
}

export default function Test() {
  const data = useLoaderData<typeof loader>();
  return <div>{data?.product?.title}</div>;
}

EDIT

You can test out the new network discount codes, that require defer, by loading the demo store, adding something to the cart, and trying to apply the discount code: NETWORK_CALL_DISCOUNT. It should take 1-2 seconds, and this discount code won't work on the main branch.

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 bl-defer-support branch. Details:

Storefront	Status	Preview link	Deployment details	Last update (UTC)
custom-cart-method	✅ Successful (Logs)	Preview deployment	Inspect deployment	July 9, 2025 5:29 PM
third-party-queries-caching	✅ Successful (Logs)	Preview deployment	Inspect deployment	July 9, 2025 5:29 PM
Skeleton (skeleton.hydrogen.shop)	✅ Successful (Logs)	Preview deployment	Inspect deployment	July 9, 2025 5:29 PM
metaobjects	✅ Successful (Logs)	Preview deployment	Inspect deployment	July 9, 2025 5:29 PM

Learn more about Hydrogen's GitHub integration.

[juanpprieto]

Yeah this is a good compromise, thanks!