tRPC experimental_defer compatibility with useSuspenseQuery

Answer to the Core Questions

1. Does experimental_defer let useSuspenseQuery skip its immediate suspension?

No. The flag only postpones the network request until the component mounts; it does not change React’s Suspense behavior. useSuspenseQuery will still suspend the component until the deferred promise resolves.

2. What happens when a deferred query is executed inside a Suspense boundary?

The boundary shows its fallback until the promise resolves. The request starts after the first render cycle, but the component cannot render until the data arrives, so the initial render is still blocked by Suspense.

Practical Verification

1. Set up a minimal component:

   import { trpc } from "@trpc/next";
   import { Suspense } from "react";
   
   function User() {
     const { data } = trpc.user.get.useSuspenseQuery(undefined, {
       experimental_defer: true,
     });
     return <div>{data.name}</div>;
   }
   
   export default function Page() {
     return (
       <Suspense fallback={<p>Loading user…</p>}>
         <User />
       </Suspense>
     );
   }
   

2. Run the app. The fallback renders immediately; the network request starts after the first render, and the user data appears once the promise resolves.

3. For SSR, ensure the server does not defer the same query, or render the component only on the client to avoid hydration mismatches.

When to Use useQuery Instead

If you need the component to render without blocking, switch to useQuery and combine it with experimental_defer. This keeps the UI responsive while the data is fetched in the background.

Takeaway

There is no built‑in way for experimental_defer to bypass the suspension of useSuspenseQuery. They operate independently. Use useQuery or a manual useEffect if you want to avoid the initial suspension.