feat: Update tRPC client to use new TanStack React Query client instead of Classic React Query Integration

[aidansunbury]

Is your feature request related to a problem? Please describe.

The new API is now the recommended client for integrating with TanStack Query. The introduction blog post states that the classic React Query integration will no longer "receive any significant new features"

Describe the solution you'd like to see

Replace all existing code using the legacy client with code using the updated client, following the migration guide

Describe alternate solutions

Leave CT3A out of date

Additional information

No response

[acho1833]

+1 for this. I wonder if the project is even supported, last commit is 2 months ago.

[juliusmarminge]

feel free to file a PR :)

[jwoyo]

My solution for gradual adoption:

I understand that this suggestion aims to revamp the whole t3 template to adopt the new pattern that useTRPC built via createTRPCContext from @trpc/tanstack-react-query (!= the older @tanstack/react-query) introduces.

However, I have a couple of t3 projects running and want to gradually adopt the new queryOptions and mutationOptions pattern.

Therefore, I'm using TRPCOptionsProxy to use both approaches in parallel.

// react.ts

// ...

// see here ⬇️
  const [optionsProxy] = useState(() =>
    createTRPCOptionsProxy<AppRouter>({ client: trpcClient, queryClient }),
  );
// ........ ⬆️


  return (
    <QueryClientProvider client={queryClient}>
      <api.Provider
        client={trpcClient}
        queryClient={queryClient}
      >
// see here ⬇️
        <TrpcInteropContext.Provider
          value={{
            optionsProxy,
          }}
        >
          {props.children}
        </TrpcInteropContext.Provider>
// ........ ⬆️
      </api.Provider>
    </QueryClientProvider>
  );
}

// ...

// see here ⬇️
// use this hook like outlined here: https://trpc.io/docs/client/tanstack-react-query/usage
export const useTRPC = () => {
  const { optionsProxy } = useContext(TrpcInteropContext);
  return optionsProxy;
};
// ........ ⬆️

useTRPC is then the new hook that allows patterns with queryOptions and mutationOptions

The diff to the current react.tsx is small. Find the full file here: https://gist.github.com/jwoyo/ae62e8896bccf8e735e249dccc9b492e

I can imagine that we could add this to the documentation. Let me know what you think.

[jwoyo]

This is how react.tsx looks like for a full migration btw.

"use client";

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { httpBatchStreamLink, loggerLink } from "@trpc/client";
import { createTRPCContext } from '@trpc/tanstack-react-query';
import { type inferRouterInputs, type inferRouterOutputs } from "@trpc/server";
import { useState } from "react";
import SuperJSON from "superjson";
import { createTRPCClient } from '@trpc/client';

import { type AppRouter } from "~/server/api/root";

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        // With SSR, we usually want to set some default staleTime
        // above 0 to avoid refetching immediately on the client
        staleTime: 60 * 1000,
      },
    },
  });
}
let browserQueryClient: QueryClient | undefined = undefined;
function getQueryClient() {
  if (typeof window === 'undefined') {
    // Server: always make a new query client
    return makeQueryClient();
  } else {
    // Browser: make a new query client if we don't already have one
    // This is very important, so we don't re-make a new client if React
    // suspends during the initial render. This may not be needed if we
    // have a suspense boundary BELOW the creation of the query client
    if (!browserQueryClient) browserQueryClient = makeQueryClient();
    return browserQueryClient;
  }
}

export const { TRPCProvider, useTRPC, useTRPCClient } = createTRPCContext<AppRouter>();

/**
 * Inference helper for inputs.
 *
 * @example type HelloInput = RouterInputs['example']['hello']
 */
export type RouterInputs = inferRouterInputs<AppRouter>;

/**
 * Inference helper for outputs.
 *
 * @example type HelloOutput = RouterOutputs['example']['hello']
 */
export type RouterOutputs = inferRouterOutputs<AppRouter>;

export function TRPCReactProvider(props: { children: React.ReactNode }) {
  const queryClient = getQueryClient();

  const [trpcClient] = useState(() =>
    createTRPCClient<AppRouter>({
      links: [
        loggerLink({
          enabled: (op) =>
            process.env.NODE_ENV === "development" ||
            (op.direction === "down" && op.result instanceof Error),
        }),
        httpBatchStreamLink({
          transformer: SuperJSON,
          url: getBaseUrl() + "/api/trpc",
          headers: () => {
            const headers = new Headers();
            headers.set("x-trpc-source", "nextjs-react");
            return headers;
          },
        }),
      ],
    })
  );

  return (
    <QueryClientProvider client={queryClient}>
      <TRPCProvider trpcClient={trpcClient} queryClient={queryClient}>
        {props.children}
      </TRPCProvider>
    </QueryClientProvider>
  );
}

function getBaseUrl() {
  if (typeof window !== "undefined") return window.location.origin;
  if (process.env.VERCEL_URL) return `https://${process.env.VERCEL_URL}`;
  return `http://localhost:${process.env.PORT ?? 3000}`;
}

[juliusmarminge]

Here's a simple example showing how to use both for an incremental migration: https://github.com/juliusmarminge/trpc-interop

Also note that the codemod we've provided should help you migrate a lot of stuff at once

[jwoyo]

@juliusmarminge do you see a simple (and secure) way how to pass along the headers the client sends to the trpc client during SSR? I'm struggeling with the trpcClient (from the react.ts above) as it is not authenticated when running queries. I could pass the cookie header from a parent server-side component to the TRPCReactProvider but this would make the http-only cookie part of the HTML.

[juliusmarminge]

No, it's not possible and the Next.js team has made it clear they don't want to support it either...

Your best bet is to do prefetching in RSCs.

You could also encrypt the cookies in RSC and send down the encrypted string to the client component with your trpc provider and then run decryption for requests being fired from the server, and use browser cookies for requests fired from the client

[jwoyo]

Thanks @juliusmarminge ! Appreciate your quick answer. I ended up prefetching every query to avoid the unauthenticated request being fired during SSR. Encrypting the cookies also sounds doable. It creates an (avoidable) attack surface, obviously.

I'm curios if @aidansunbury can come up with a proper solution for t3 for this feature request.

[bohdancho]

Working on this currently

@aidansunbury are you still working on this? ^^
if not I would be glad to take it over

[aidansunbury]

@bohdancho Sorry I haven't had the chance yet. Feel free to take it over

[bohdancho]

No, it's not possible and the Next.js team has made it clear they don't want to support it either...
Your best bet is to do prefetching in RSCs.
You could also encrypt the cookies in RSC and send down the encrypted string to the client component with your trpc provider and then run decryption for requests being fired from the server, and use browser cookies for requests fired from the client

@juliusmarminge

There is an elegant workaround for this issue (cc #1765) that doesn't involve using third party packages or encrypting cookies. I would be happy to include it in the PR for this issue. If not, IMO it would make sense to at least mention this workaround (or the cookie encryption one) in the docs. What do you think?

The workaround:

1. Declare a global variable for the headers during the SSR pass: https://github.com/bohdancho/trpc-client-component-ssr-headers/blob/a6180c76f24ca757fba0fe75fc93c3124b745f45/src/trpc/react.tsx#L13-L16

2. Pass the global variable if available (SSR) or the regular headers otherwise to httpBatchStreamLink https://github.com/bohdancho/trpc-client-component-ssr-headers/blob/a6180c76f24ca757fba0fe75fc93c3124b745f45/src/trpc/react.tsx#L60-L66

3. Populate the global variable in a 'server-only' file https://github.com/bohdancho/trpc-client-component-ssr-headers/blob/a6180c76f24ca757fba0fe75fc93c3124b745f45/src/trpc/client-ssr-headers-provider.ts

4. Import this 'server-only' file in a server component, for example layout.tsxhttps://github.com/bohdancho/trpc-client-component-ssr-headers/blob/a6180c76f24ca757fba0fe75fc93c3124b745f45/src/app/layout.tsx#L2

Feel free to clone the repo to play with the minimal example that I put together. It returns posts for authorized users or null otherwise. Removing the workaround results in a hydration error.

P.S. This is heavily inspired by oRPC's suggested way to deal with this issue.