tRPC Scaffold

tRPC in this monorepo is an intentional stub, not the product API. The router in apps/web/src/trpc/routers/_app.ts exposes a single healthCheck procedure. There are no workspace, user, AI, or tasks routers, and there is no auth middleware. Product authentication and data flow through @tuturuuu/internal-api helpers and REST routes under /api/v1, not tRPC. This page documents the real scaffold so you do not build on procedures that do not exist.

Why a stub?

The maintained runtime is Next.js Web and its satellite apps. Rust (apps/backend) and TanStack Start (apps/tanstack-web) are paused and not in use. Docker setup is inactive and the Docker cron runner is retired. Retained migration designs describe a possible future, not live traffic or a current setup requirement. See the active runtime map. Rather than build out a tRPC API surface that would be thrown away, the team keeps a minimal tRPC scaffold wired end-to-end so the type system and client plumbing stay valid and ready, while all real reads and writes go through the internal API client and REST routes. New product features should not add tRPC routers — use the patterns in Data Fetching and API Routes.

A repository guard (scripts/check-tanstack-api-access.js, run as part of bun validate) forbids calls to /trpc from apps/tanstack-web/src. The TanStack app talks to the Rust backend and REST API, never to this stub.

What actually exists today

apps/web/src/trpc/
├── init.ts                       # initTRPC + context + exported helpers
├── query.ts                      # makeQueryClient (superjson + rate-limit retry)
├── client.tsx                    # TRPCProvider + createTRPCReact client
├── server.ts                     # RSC caller + HydrateClient hydration helpers
└── routers/
    └── _app.ts                   # appRouter: a single healthCheck procedure

apps/web/src/app/api/trpc/[trpc]/route.ts   # fetch adapter (GET + POST)

Relevant versions in apps/web/package.json: @trpc/server, @trpc/client, and @trpc/react-query are all on ^11.x, paired with @tanstack/react-query ^5.x and superjson ^2.x. (Check the manifest for exact pinned versions; do not hard-code them in code.)

Initialization (`init.ts`)

init.ts creates the tRPC instance with the superjson transformer and exports helper factories. Note the real export names — there is no router, publicProcedure, or protectedProcedure.

// apps/web/src/trpc/init.ts
import { initTRPC } from '@trpc/server';
import { cache } from 'react';
import superjson from 'superjson';

export const createTRPCContext = cache(async () => {
  // @see: https://trpc.io/docs/server/context
  // This is a placeholder context. There is no Supabase auth here —
  // login authentication uses API routes via @tuturuuu/internal-api.
  return { userId: 'user_123' };
});

const t = initTRPC.create({
  // superjson preserves Dates, Maps, Sets, etc. across the wire.
  transformer: superjson,
});

// Base router and procedure helpers
export const createTRPCRouter = t.router;
export const createCallerFactory = t.createCallerFactory;
export const baseProcedure = t.procedure;

Exported helpers:

Export	What it is	Used by
`createTRPCContext`	Async cached context factory. Returns a hardcoded `{ userId: 'user_123' }` placeholder — no real auth.	`route.ts`, `server.ts`
`createTRPCRouter`	`t.router` — builds routers.	`routers/_app.ts`
`createCallerFactory`	`t.createCallerFactory` — builds RSC server callers.	`server.ts`
`baseProcedure`	`t.procedure` — the only procedure builder.	`routers/_app.ts`

The context is a hardcoded stub, not an authenticated user. Do not read ctx.userId expecting a real identity, and do not invent a protectedProcedure / isAuthed middleware — none exists. If you need the signed-in user, use the auth helpers and @tuturuuu/internal-api, not tRPC.

The root router (`routers/_app.ts`)

The entire API surface is one health-check query that keeps the tRPC type system compiling:

// apps/web/src/trpc/routers/_app.ts
import { baseProcedure, createTRPCRouter } from '../init';

// tRPC router for the web app
// Login authentication uses API routes via @tuturuuu/internal-api.
export const appRouter = createTRPCRouter({
  // Health check procedure to maintain tRPC type system compatibility
  healthCheck: baseProcedure.query(() => {
    return { status: 'ok', timestamp: Date.now() };
  }),
});

// export type definition of API
export type AppRouter = typeof appRouter;

That is the complete router. The only callable procedure is appRouter.healthCheck.

The route handler (`app/api/trpc/[trpc]/route.ts`)

A standard tRPC fetch adapter exposes the router over HTTP for both GET and POST:

// apps/web/src/app/api/trpc/[trpc]/route.ts
import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
import type { NextRequest } from 'next/server';
import { createTRPCContext } from '@/trpc/init';
import { appRouter } from '@/trpc/routers/_app';

const handler = (req: NextRequest) =>
  fetchRequestHandler({
    endpoint: '/api/trpc',
    req,
    router: appRouter,
    createContext: createTRPCContext,
  });

export { handler as GET, handler as POST };

Query client (`query.ts`)

makeQueryClient builds a TanStack Query v5 QueryClient with superjson de/serialization and rate-limit-aware retries. This is shared by both the client provider and the RSC caller.

// apps/web/src/trpc/query.ts (abridged)
import { defaultShouldDehydrateQuery, QueryClient } from '@tanstack/react-query';
import { deserialize, serialize } from 'superjson';
import { HttpError, isRateLimitError } from '@/lib/api-fetch';

export function makeQueryClient(options?: MakeQueryClientOptions) {
  return new QueryClient({
    queryCache: options?.queryCache,
    mutationCache: options?.mutationCache,
    defaultOptions: {
      queries: {
        staleTime: 30 * 1000,
        // Retry only rate-limited requests, up to 3 times.
        retry: (failureCount, error) =>
          isRateLimitError(error) ? failureCount < 3 : false,
        retryDelay: (_attemptIndex, error) =>
          error instanceof HttpError && error.retryAfter
            ? error.retryAfter * 1000
            : 1000,
      },
      // mutations use the same rate-limit retry policy
      dehydrate: {
        serializeData: serialize,
        shouldDehydrateQuery: (query) =>
          defaultShouldDehydrateQuery(query) ||
          query.state.status === 'pending',
      },
      hydrate: { deserializeData: deserialize },
    },
  });
}

On TanStack Query v5, the cache-retention option is gcTime, not the v4 cacheTime. The factory above relies on the v5 default gcTime; if you set it explicitly anywhere, use gcTime.

Client provider (`client.tsx`)

client.tsx creates the typed React client with createTRPCReact<AppRouter>() and wires a TRPCProvider over @tanstack/react-query. The HTTP batch link points at /api/trpc and uses the superjson transformer.

// apps/web/src/trpc/client.tsx (abridged)
'use client';

import { QueryClientProvider } from '@tanstack/react-query';
import { httpBatchLink } from '@trpc/client';
import { createTRPCReact } from '@trpc/react-query';
import { useState } from 'react';
import superjson from 'superjson';
import { makeQueryClient } from './query';
import type { AppRouter } from './routers/_app';

export const trpc = createTRPCReact<AppRouter>();

export function TRPCProvider({ children }: { children: React.ReactNode }) {
  const queryClient = getQueryClient(); // singleton in browser, fresh on server
  const [trpcClient] = useState(() =>
    trpc.createClient({
      links: [httpBatchLink({ transformer: superjson, url: getUrl() })],
    })
  );

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

The only hook you can actually call through this client today is:

'use client';

import { trpc } from '@/trpc/client';

export function HealthBadge() {
  const { data } = trpc.healthCheck.useQuery();
  return <span>{data?.status ?? 'checking…'}</span>;
}

Server caller and hydration (`server.ts`)

server.ts builds an RSC-side caller from the root router plus the same query client, and exposes trpc and HydrateClient via tRPC’s createHydrationHelpers. It is marked server-only.

// apps/web/src/trpc/server.ts
import { createCallerFactory, createTRPCContext } from './init';
import { makeQueryClient } from './query';
import { appRouter } from './routers/_app';
import { createHydrationHelpers } from '@trpc/react-query/rsc';
import { cache } from 'react';
import 'server-only';

export const getQueryClient = cache(makeQueryClient);
const caller = createCallerFactory(appRouter)(createTRPCContext);
export const { trpc, HydrateClient } = createHydrationHelpers<typeof appRouter>(
  caller,
  getQueryClient
);

In a Server Component you can prefetch and hydrate the single health-check procedure:

import { trpc, HydrateClient } from '@/trpc/server';

export default async function Page() {
  // The only available procedure today
  await trpc.healthCheck();
  return (
    <HydrateClient>
      {/* client components can read the hydrated cache */}
    </HydrateClient>
  );
}

How to actually fetch product data

Because tRPC is a stub, real data access uses the platform’s standard stack:

Server Components read data directly (via Supabase server clients and @tuturuuu/internal-api helpers) and pass it down as props.
Client components use TanStack Query v5 hooks wrapping @tuturuuu/internal-api helpers / REST /api/v1 routes. Never fetch in useEffect, and never call raw app APIs from the client directly.
Realtime updates are wired into the TanStack Query cache, not into useEffect.

When using the Supabase server clients from @tuturuuu/supabase/next/server, remember:

import {
  createClient,
  createDynamicClient,
  createAdminClient,
} from '@tuturuuu/supabase/next/server';

const supabase = await createClient();         // ASYNC — await it
const dynamic = await createDynamicClient();    // ASYNC — await it
const admin = createAdminClient();              // SYNC  — do NOT await

See Data Fetching for the canonical patterns and decision table.

Extending the stub (rarely needed)

If you genuinely need to add a procedure to the stub (for example, another lightweight diagnostic), follow the real helper names:

// apps/web/src/trpc/routers/_app.ts
import { baseProcedure, createTRPCRouter } from '../init';

export const appRouter = createTRPCRouter({
  healthCheck: baseProcedure.query(() => ({ status: 'ok', timestamp: Date.now() })),
  // example diagnostic addition
  ping: baseProcedure.query(() => ({ pong: true })),
});

export type AppRouter = typeof appRouter;

Procedures here run with the placeholder context only — there is no auth middleware to attach. For anything user-facing, authenticated, or product-related, prefer @tuturuuu/internal-api + REST routes instead of growing this scaffold during the migration.

Data Fetching — the real client/server fetching stack (Server Components + internal-api + TanStack Query)
API Routes — REST /api/v1 patterns and @tuturuuu/internal-api
TanStack + Rust migration — why this layer is a stub
Authentication
Authorization

Build

Platform

Components

Why a stub?

What actually exists today

Initialization (`init.ts`)

The root router (`routers/_app.ts`)

The route handler (`app/api/trpc/[trpc]/route.ts`)

Query client (`query.ts`)

Client provider (`client.tsx`)

Server caller and hydration (`server.ts`)

How to actually fetch product data

Extending the stub (rarely needed)

External Resources

Why a stub?

What actually exists today

Initialization (init.ts)

The root router (routers/_app.ts)

The route handler (app/api/trpc/[trpc]/route.ts)

Query client (query.ts)

Client provider (client.tsx)

Server caller and hydration (server.ts)

How to actually fetch product data

Extending the stub (rarely needed)

Related Documentation

External Resources

Initialization (`init.ts`)

The root router (`routers/_app.ts`)

The route handler (`app/api/trpc/[trpc]/route.ts`)

Query client (`query.ts`)

Client provider (`client.tsx`)

Server caller and hydration (`server.ts`)