tRPC -- Links

Setup

import { createTRPCClient, httpBatchLink, loggerLink } from '@trpc/client';
import type { AppRouter } from './server';

const client = createTRPCClient<AppRouter>({
  links: [
    loggerLink(),
    httpBatchLink({
      url: 'http://localhost:3000/trpc',
    }),
  ],
});

The links array is a chain: non-terminating links (loggerLink, splitLink, retryLink) forward operations; the chain must end with a terminating link (httpBatchLink, httpLink, httpBatchStreamLink, wsLink, httpSubscriptionLink, unstable_localLink).

Core Patterns

httpBatchLink -- Batch Multiple Calls into One Request

import { createTRPCClient, httpBatchLink } from '@trpc/client';
import type { AppRouter } from './server';

const client = createTRPCClient<AppRouter>({
  links: [
    httpBatchLink({
      url: 'http://localhost:3000/trpc',
      maxURLLength: 2083,
      maxItems: 10,
    }),
  ],
});

const [post1, post2, post3] = await Promise.all([
  client.post.byId.query(1),
  client.post.byId.query(2),
  client.post.byId.query(3),
]);

Concurrent calls are batched into a single HTTP request. Set maxURLLength to prevent 414 errors from long URLs.

splitLink -- Route Subscriptions to SSE

import {
  createTRPCClient,
  httpBatchLink,
  httpSubscriptionLink,
  splitLink,
} from '@trpc/client';
import type { AppRouter } from './server';

const client = createTRPCClient<AppRouter>({
  links: [
    splitLink({
      condition: (op) => op.type === 'subscription',
      true: httpSubscriptionLink({
        url: 'http://localhost:3000/trpc',
      }),
      false: httpBatchLink({
        url: 'http://localhost:3000/trpc',
      }),
    }),
  ],
});

splitLink -- Disable Batching Per-Request via Context

import {
  createTRPCClient,
  httpBatchLink,
  httpLink,
  splitLink,
} from '@trpc/client';
import type { AppRouter } from './server';

const client = createTRPCClient<AppRouter>({
  links: [
    splitLink({
      condition: (op) => Boolean(op.context.skipBatch),
      true: httpLink({ url: 'http://localhost:3000/trpc' }),
      false: httpBatchLink({ url: 'http://localhost:3000/trpc' }),
    }),
  ],
});

const result = await client.post.byId.query(1, {
  context: { skipBatch: true },
});

httpBatchStreamLink -- Stream Responses as They Arrive

import { createTRPCClient, httpBatchStreamLink } from '@trpc/client';
import type { AppRouter } from './server';

const client = createTRPCClient<AppRouter>({
  links: [
    httpBatchStreamLink({
      url: 'http://localhost:3000/trpc',
    }),
  ],
});

const iterable = await client.examples.iterable.query();
for await (const value of iterable) {
  console.log(value);
}

wsLink -- WebSocket Terminating Link

import { createTRPCClient, createWSClient, wsLink } from '@trpc/client';
import type { AppRouter } from './server';

const wsClient = createWSClient({
  url: 'ws://localhost:3000',
});

const client = createTRPCClient<AppRouter>({
  links: [wsLink<AppRouter>({ client: wsClient })],
});

Custom Link

import { TRPCLink } from '@trpc/client';
import { observable } from '@trpc/server/observable';
import type { AppRouter } from './server';

export const timingLink: TRPCLink<AppRouter> = () => {
  return ({ next, op }) => {
    return observable((observer) => {
      const start = Date.now();
      const unsubscribe = next(op).subscribe({
        next(value) {
          observer.next(value);
        },
        error(err) {
          console.error(`${op.path} failed in ${Date.now() - start}ms`);
          observer.error(err);
        },
        complete() {
          console.log(`${op.path} completed in ${Date.now() - start}ms`);
          observer.complete();
        },
      });
      return unsubscribe;
    });
  };
};

Common Mistakes

[CRITICAL] No terminating link in the chain

Wrong:

const client = createTRPCClient<AppRouter>({
  links: [loggerLink()],
});

Correct:

const client = createTRPCClient<AppRouter>({
  links: [loggerLink(), httpBatchLink({ url: 'http://localhost:3000/trpc' })],
});

The link chain must end with a terminating link. Without one, tRPC throws "No more links to execute - did you forget to add an ending link?"

Source: packages/client/src/links/internals/createChain.ts

[CRITICAL] Sending subscriptions through httpLink or httpBatchLink

Wrong:

const client = createTRPCClient<AppRouter>({
  links: [httpBatchLink({ url: 'http://localhost:3000/trpc' })],
});
await client.onMessage.subscribe({});

Correct:

const client = createTRPCClient<AppRouter>({
  links: [
    splitLink({
      condition: (op) => op.type === 'subscription',
      true: httpSubscriptionLink({ url: 'http://localhost:3000/trpc' }),
      false: httpBatchLink({ url: 'http://localhost:3000/trpc' }),
    }),
  ],
});

httpLink and httpBatchLink throw on subscription operations. Subscriptions must use httpSubscriptionLink or wsLink, routed via splitLink.

Source: packages/client/src/links/httpLink.ts

[HIGH] httpBatchLink and httpBatchStreamLink headers callback receives { opList }

httpBatchLink and httpBatchStreamLink headers callbacks receive { opList } (a NonEmptyArray<Operation>), not { op } like httpLink. Access per-operation context via opList[0]?.context:

httpBatchLink({
  url: 'http://localhost:3000/trpc',
  headers({ opList }) {
    return { authorization: opList[0]?.context.token };
  },
});

httpBatchLink headers callback receives { opList } (an array of operations)

Source: packages/client/src/links/httpBatchLink.ts

[MEDIUM] Default batch limits are Infinity

Wrong:

httpBatchLink({ url: 'http://localhost:3000/trpc' });

Correct:

httpBatchLink({
  url: 'http://localhost:3000/trpc',
  maxURLLength: 2083,
  // should be the same or lower than the server's maxBatchSize
  maxItems: 10,
});

Both maxURLLength and maxItems default to Infinity, which can cause 413/414 HTTP errors on servers or CDNs with URL length limits. When the server sets maxBatchSize, set maxItems to the same or lower value so the client auto-splits batches instead of triggering a 400 Bad Request.

Source: packages/client/src/links/httpBatchLink.ts

[HIGH] httpBatchStreamLink data loss on stream completion

There is a known race condition where buffered chunks can be lost on normal stream completion. Long streaming responses (e.g., LLM output) may be truncated. If you experience truncated data, switch to httpBatchLink for those operations.

Source: https://github.com/trpc/trpc/issues/7209

References

• Link options reference

See Also

• client-setup -- create the tRPC client and configure links
• superjson -- add transformer to links for Date/Map/Set support
• subscriptions -- set up SSE or WebSocket real-time streams
• non-json-content-types -- route FormData/binary through splitLink + httpLink
• service-oriented-architecture -- build custom routing links for multi-service backends