tRPC -- Links

Setup

ts
1import { createTRPCClient, httpBatchLink, loggerLink } from '@trpc/client';
2import type { AppRouter } from './server';
3
4const client = createTRPCClient<AppRouter>({
5  links: [
6    loggerLink(),
7    httpBatchLink({
8      url: 'http://localhost:3000/trpc',
9    }),
10  ],
11});

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

ts
1import { createTRPCClient, httpBatchLink } from '@trpc/client';
2import type { AppRouter } from './server';
3
4const client = createTRPCClient<AppRouter>({
5  links: [
6    httpBatchLink({
7      url: 'http://localhost:3000/trpc',
8      maxURLLength: 2083,
9      maxItems: 10,
10    }),
11  ],
12});
13
14const [post1, post2, post3] = await Promise.all([
15  client.post.byId.query(1),
16  client.post.byId.query(2),
17  client.post.byId.query(3),
18]);

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

splitLink -- Route Subscriptions to SSE

ts
1import {
2  createTRPCClient,
3  httpBatchLink,
4  httpSubscriptionLink,
5  splitLink,
6} from '@trpc/client';
7import type { AppRouter } from './server';
8
9const client = createTRPCClient<AppRouter>({
10  links: [
11    splitLink({
12      condition: (op) => op.type === 'subscription',
13      true: httpSubscriptionLink({
14        url: 'http://localhost:3000/trpc',
15      }),
16      false: httpBatchLink({
17        url: 'http://localhost:3000/trpc',
18      }),
19    }),
20  ],
21});

splitLink -- Disable Batching Per-Request via Context

ts
1import {
2  createTRPCClient,
3  httpBatchLink,
4  httpLink,
5  splitLink,
6} from '@trpc/client';
7import type { AppRouter } from './server';
8
9const client = createTRPCClient<AppRouter>({
10  links: [
11    splitLink({
12      condition: (op) => Boolean(op.context.skipBatch),
13      true: httpLink({ url: 'http://localhost:3000/trpc' }),
14      false: httpBatchLink({ url: 'http://localhost:3000/trpc' }),
15    }),
16  ],
17});
18
19const result = await client.post.byId.query(1, {
20  context: { skipBatch: true },
21});

httpBatchStreamLink -- Stream Responses as They Arrive

ts
1import { createTRPCClient, httpBatchStreamLink } from '@trpc/client';
2import type { AppRouter } from './server';
3
4const client = createTRPCClient<AppRouter>({
5  links: [
6    httpBatchStreamLink({
7      url: 'http://localhost:3000/trpc',
8    }),
9  ],
10});
11
12const iterable = await client.examples.iterable.query();
13for await (const value of iterable) {
14  console.log(value);
15}

wsLink -- WebSocket Terminating Link

ts
1import { createTRPCClient, createWSClient, wsLink } from '@trpc/client';
2import type { AppRouter } from './server';
3
4const wsClient = createWSClient({
5  url: 'ws://localhost:3000',
6});
7
8const client = createTRPCClient<AppRouter>({
9  links: [wsLink<AppRouter>({ client: wsClient })],
10});

Custom Link

ts
1import { TRPCLink } from '@trpc/client';
2import { observable } from '@trpc/server/observable';
3import type { AppRouter } from './server';
4
5export const timingLink: TRPCLink<AppRouter> = () => {
6  return ({ next, op }) => {
7    return observable((observer) => {
8      const start = Date.now();
9      const unsubscribe = next(op).subscribe({
10        next(value) {
11          observer.next(value);
12        },
13        error(err) {
14          console.error(`${op.path} failed in ${Date.now() - start}ms`);
15          observer.error(err);
16        },
17        complete() {
18          console.log(`${op.path} completed in ${Date.now() - start}ms`);
19          observer.complete();
20        },
21      });
22      return unsubscribe;
23    });
24  };
25};

Common Mistakes

[CRITICAL] No terminating link in the chain

Wrong:

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

Correct:

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

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:

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

Correct:

ts
1const client = createTRPCClient<AppRouter>({
2  links: [
3    splitLink({
4      condition: (op) => op.type === 'subscription',
5      true: httpSubscriptionLink({ url: 'http://localhost:3000/trpc' }),
6      false: httpBatchLink({ url: 'http://localhost:3000/trpc' }),
7    }),
8  ],
9});

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:

ts
1httpBatchLink({
2  url: 'http://localhost:3000/trpc',
3  headers({ opList }) {
4    return { authorization: opList[0]?.context.token };
5  },
6});

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

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

[MEDIUM] Default batch limits are Infinity

Wrong:

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

Correct:

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

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