Pages Router Integration

/**
 * Creates a tRPC instance with React hooks and utilities for Next.js Pages Router
 * @param opts - Configuration options for tRPC client and SSR behavior
 * @returns Object with tRPC hooks, utilities, and withTRPC HOC
 */
function createTRPCNext<TRouter extends AnyRouter, TSSRContext extends NextPageContext = NextPageContext>(
  opts: WithTRPCNoSSROptions<TRouter> | WithTRPCSSROptions<TRouter>
): CreateTRPCNext<TRouter, TSSRContext>;

interface CreateTRPCNext<TRouter extends AnyRouter, TSSRContext extends NextPageContext> {
  /** @deprecated renamed to `useUtils` and will be removed in a future tRPC version */
  useContext(): CreateReactUtils<TRouter, TSSRContext>;
  /** Hook for accessing tRPC utilities like invalidateQueries, refetch, etc. */
  useUtils(): CreateReactUtils<TRouter, TSSRContext>;
  /** Higher-order component for wrapping Next.js apps/pages */
  withTRPC: ReturnType<typeof withTRPC<TRouter, TSSRContext>>;
  /** Hook for performing multiple queries in parallel */
  useQueries: TRPCUseQueries<TRouter>;
  /** Hook for performing multiple suspense queries in parallel */
  useSuspenseQueries: TRPCUseSuspenseQueries<TRouter>;
}

import { createTRPCNext } from "@trpc/next";
import { httpBatchLink } from "@trpc/client";
import type { AppRouter } from "../pages/api/[trpc]";

// Basic client-side only setup
export const trpc = createTRPCNext<AppRouter>({
  config() {
    return {
      links: [
        httpBatchLink({
          url: "http://localhost:3000/api/trpc",
        }),
      ],
    };
  },
  ssr: false,
});

// Using the created instance
function UserProfile() {
  const utils = trpc.useUtils();
  const { data } = trpc.user.getProfile.useQuery({ userId: "123" });
  
  const handleRefresh = () => {
    utils.user.getProfile.invalidate({ userId: "123" });
  };
  
  return <div>{data?.name}</div>;
}

/**
 * Higher-order component that wraps Next.js App or Page components with tRPC context
 * @param opts - Configuration options for tRPC client and SSR behavior
 * @returns Function that takes a component and returns wrapped component
 */
function withTRPC<TRouter extends AnyRouter, TSSRContext extends NextPageContext = NextPageContext>(
  opts: WithTRPCNoSSROptions<TRouter> | WithTRPCSSROptions<TRouter>
): (AppOrPage: NextComponentType<any, any, any>) => NextComponentType;

import { withTRPC } from "@trpc/next";
import { httpBatchLink } from "@trpc/client";
import type { AppRouter } from "../pages/api/[trpc]";

// In pages/_app.tsx
const MyApp = ({ Component, pageProps }) => {
  return <Component {...pageProps} />;
};

export default withTRPC<AppRouter>({
  config() {
    return {
      links: [
        httpBatchLink({
          url: process.env.NEXT_PUBLIC_VERCEL_URL
            ? `https://${process.env.NEXT_PUBLIC_VERCEL_URL}/api/trpc`
            : "http://localhost:3000/api/trpc",
        }),
      ],
    };
  },
  ssr: false,
})(MyApp);

interface WithTRPCNoSSROptions<TRouter extends AnyRouter> extends WithTRPCOptions<TRouter> {
  /** Explicitly disable SSR */
  ssr?: false;
}

interface WithTRPCOptions<TRouter extends AnyRouter> extends CreateTRPCReactOptions<TRouter>, TransformerOptions<inferClientTypes<TRouter>> {
  /** Function that returns tRPC client configuration */
  config: (info: { ctx?: NextPageContext }) => WithTRPCConfig<TRouter>;
}

interface WithTRPCSSROptions<TRouter extends AnyRouter> extends WithTRPCOptions<TRouter> {
  /** Enable SSR with optional conditional function */
  ssr: true | ((opts: { ctx: NextPageContext }) => boolean | Promise<boolean>);
  /** Function to set response meta like headers and status codes */
  responseMeta?: (opts: {
    ctx: NextPageContext;
    clientErrors: TRPCClientError<TRouter>[];
  }) => ResponseMeta;
  /** SSR prepass helper function - use `ssrPrepass` from @trpc/next/ssrPrepass */
  ssrPrepass: TRPCPrepassHelper;
}

interface WithTRPCConfig<TRouter extends AnyRouter> extends CreateTRPCClientOptions<TRouter>, CreateTRPCReactQueryClientConfig {
  /** Whether to abort queries on component unmount */
  abortOnUnmount?: boolean;
}

import { httpBatchLink } from "@trpc/client";
import { ssrPrepass } from "@trpc/next/ssrPrepass";

// Client-side only configuration
const clientOnlyConfig = {
  config() {
    return {
      links: [httpBatchLink({ url: "/api/trpc" })],
    };
  },
  ssr: false,
};

// SSR configuration with conditional SSR

const ssrConfig = {
  config(ctx) {
    return {
      links: [
        httpBatchLink({
          url: "/api/trpc",
          headers: ctx?.ctx?.req?.headers,
        }),
      ],
    };
  },
  ssr: (ctx) => {
    // Only SSR on certain pages
    return ctx.ctx?.pathname?.startsWith("/dashboard") ?? false;
  },
  responseMeta({ ctx, clientErrors }) {
    if (clientErrors.length > 0) {
      return { status: 500 };
    }
    return {};
  },
  ssrPrepass,
};

// Function signature for SSR prepass helpers
type TRPCPrepassHelper = (opts: {
  parent: WithTRPCSSROptions<AnyRouter>;
  WithTRPC: NextComponentType<any, any, any>;
  AppOrPage: NextComponentType<any, any, any>;
}) => void;

// Props passed to components during SSR prepass
interface TRPCPrepassProps<TRouter extends AnyRouter, TSSRContext extends NextPageContext = NextPageContext> {
  config: WithTRPCConfig<TRouter>;
  queryClient: QueryClient;
  trpcClient: TRPCUntypedClient<TRouter> | TRPCClient<TRouter>;
  ssrState: 'prepass';
  ssrContext: TSSRContext;
}

// Response metadata for SSR
interface ResponseMeta {
  status?: number;
  headers?: Record<string, string>;
}