Export PreloadQueryRef by teodorszeltins · Pull Request #549 · apollographql/apollo-client-integrations

teodorszeltins · 2026-04-09T23:05:02Z

This exports PreloadQueryRef as a public API and adds it to the object returned by registerApolloClient.

Until now, it only existed as an internal helper used by PreloadQuery under the name SimulatePreloadedQuery.

Why

PreloadQuery starts the query from where it appears in the render tree, so the request does not begin until React gets there.

This makes it harder to parallelise GraphQL queries with other async work (REST calls, auth checks, etc.) at the top of a Server Component.

PreloadQueryRef makes that flow a bit more flexible. You can create the queryRef early with createTransportedQueryPreloader, start the query right away, and render <PreloadQueryRef> later to hydrate it into the client tree.

Usage

export default async function Page() {
  const preloader = createTransportedQueryPreloader(await getClient());

  const queryRef = preloader(MY_QUERY, {
    variables: { id: "1" },
  });

  const otherData = await fetchSomeRestEndpoint();

  return (
    <ApolloWrapper>
      <PreloadQueryRef queryRef={queryRef}>
        <Suspense fallback={<>loading...</>}>
          <ClientChild queryRef={queryRef} otherData={otherData} />
        </Suspense>
      </PreloadQueryRef>
    </ApolloWrapper>
  );
}

Summary by CodeRabbit

Release Notes

New Features
- Exported PreloadQueryRef as a public API, now available through registerApolloClient, enabling query-ref-first preloading workflows for improved data fetching patterns.

apollo-cla · 2026-04-09T23:05:04Z

@teodorszeltins: Thank you for submitting a pull request! Before we can merge it, you'll need to sign the Apollo Contributor License Agreement here: https://contribute.apollographql.com/

changeset-bot · 2026-04-09T23:05:05Z

🦋 Changeset detected

Latest commit: 04017bd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@apollo/client-react-streaming	Minor
@apollo/client-integration-nextjs	Minor
@apollo/client-integration-react-router	Minor
@apollo/client-integration-tanstack-start	Minor
@apollo/experimental-nextjs-app-support	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

netlify · 2026-04-09T23:05:06Z

👷 Deploy request for apollo-client-nextjs-docmodel pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	`04017bd`

vercel · 2026-04-09T23:05:06Z

@teodorszeltins is attempting to deploy a commit to the Apollo Client - Next package - integration tests Team on Vercel.

A member of the Team first needs to authorize it.

coderabbitai · 2026-04-09T23:05:15Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5ddedd8e-52e4-481c-9c8a-dd06ec1ef7e7

📥 Commits

Reviewing files that changed from the base of the PR and between 15eda44 and 04017bd.

⛔ Files ignored due to path filters (1)

yarn.lock is excluded by !**/yarn.lock, !**/*.lock

📒 Files selected for processing (13)

.changeset/tidy-taxis-jam.md
integration-test/nextjs/package.json
integration-test/nextjs/src/app/rsc/client.ts
integration-test/nextjs/src/app/rsc/dynamic/PreloadQueryRef/queryRef-useReadQuery/page.tsx
integration-test/playwright/src/preloadQuery.test.ts
packages/client-react-streaming/package-shape.json
packages/client-react-streaming/src/PreloadQuery.tsx
packages/client-react-streaming/src/PreloadQueryRef.cc.ts
packages/client-react-streaming/src/index.cc.tsx
packages/client-react-streaming/src/index.rsc.ts
packages/client-react-streaming/src/index.ts
packages/client-react-streaming/src/registerApolloClient.tsx
packages/client-react-streaming/tsup.config.ts

📜 Recent review details

🧰 Additional context used

🧠 Learnings (5)