Links Overview#

From https://trpc.io/docs/client/links

Links enable you to customize the flow of data between the tRPC Client and Server. A link should do only one thing, which can be either a self-contained modification to a tRPC operation (query, mutation, or subscription) or a side-effect based on the operation (such as logging).

You can compose links together into an array that you can provide to the tRPC client configuration via the links property, which represents a link chain. This means that the tRPC client will execute the links in the order they are added to the links array when doing a request and will execute them again in reverse when it's handling a response. Here's a visual representation of the link chain:

tRPC Link Diagram. Based on Apollo's.

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

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

Creating a custom link#

A link is a function that follows the TRPCLink type. Each link is composed of three parts:

1. The link returns a function that has no parameters. This is the setup phase where the link is initialized — it happens once per app and is useful for storing caches or other state.
2. The function in step 1 returns another function that receives an object with two properties: op which is the Operation that is being executed by the client, and next which is the function we use to call the next link down the chain.
3. The function in step 2 returns a final function that returns the observable function provided by @trpc/server. The observable accepts a function that receives an observer which helps our link notify the next link up the chain how they should handle the operation result. In this function, we can just return next(op) and leave it as is, or we can subscribe to next, which enables our link to handle the operation result.

Example#

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

export const customLink: TRPCLink<AppRouter> = () => {
  // here we just got initialized in the app - this happens once per app
  // useful for storing cache for instance
  return ({ next, op }) => {
    // this is when passing the result to the next link

    // each link needs to return an observable which propagates results
    return observable((observer) => {
      console.log('performing operation:', op);
      const unsubscribe = next(op).subscribe({
        next(value) {
          console.log('we received value', value);
          observer.next(value);
        },
        error(err) {
          console.log('we received error', err);
          observer.error(err);
        },
        complete() {
          observer.complete();
        },
      });

      return unsubscribe;
    });
  };
};

References#

If you need a more real reference for creating your custom link, you can check out some of the built-in links tRPC provides on GitHub.

The terminating link#

The terminating link is the last link in a link chain. Instead of calling the next function, the terminating link is responsible for sending your composed tRPC operation to the tRPC server and returning an OperationResultEnvelope.

The links array that you add to the tRPC client config should have at least one link, and that link should be a terminating link. If links don't have a terminating link at the end of them, the tRPC operation will not be sent to the tRPC server.

httpBatchLink is the recommended terminating link by tRPC. Pick another one depending on your needs:

The HTTP links don't handle subscriptions, so to use subscriptions alongside them, route by operation type with a splitLink:

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

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

Managing context#

As an operation moves along your link chain, it maintains a context that each link can read and modify. This allows links to pass metadata along the chain that other links use in their execution logic.

Obtain the current context object and modify it by accessing op.context.

You can set the context object's initial value for a particular operation by providing the context parameter to the query or useQuery hook (or mutation, subscription, etc.).

For an example use case, see Disable batching for certain requests.

Common mistakes#

• No terminating link at the end of the chain. Calls fail with No more links to execute - did you forget to add an ending link?. Links listed after the terminating link never run, so put loggerLink, retryLink and your own links before it.
• A splitLink branch without a terminating link. Each branch is its own chain, so each one needs to end in a terminating link.
• Sending subscriptions through httpLink, httpBatchLink or httpBatchStreamLink. They throw on subscriptions. Route them to httpSubscriptionLink or wsLink with a splitLink, as shown in The terminating link.
• Returning an async generator from a query through httpLink or httpBatchLink. The server responds with Cannot use stream-like response in non-streaming request - use httpBatchStreamLink.
• Reading op in a batch link's headers callback. httpBatchLink and httpBatchStreamLink call headers({ opList }) once per batch, with all its operations. Only httpLink gets a single { op }.
• Unbounded batches. maxURLLength and maxItems default to Infinity. If long URLs hit limits in your server or CDN, set maxURLLength. If the server sets maxBatchSize, set maxItems to the same or a lower value, or larger batches are rejected with 400 Bad Request. See httpBatchLink.
• Forgetting the transformer on one link. If your server uses a data transformer, every terminating link needs the same transformer, in every splitLink branch.

References#

• HTTP Batch Link: A terminating link that batches concurrent tRPC calls into a single HTTP request
• HTTP Link: A terminating link that sends each tRPC call as its own HTTP request
• HTTP Batch Stream Link: A terminating link that batches tRPC calls and streams each response as soon as it is ready
• HTTP Subscription Link: A terminating link for subscriptions over Server-sent Events
• WebSocket Link: A terminating link that sends tRPC operations over a WebSocket
• Local Link: A link for direct procedure calls without HTTP overhead
• Split Link: A link that routes each operation down one of two link chains based on a condition
• Logger Link: A link that logs tRPC operations and their results
• Retry Link: A link that retries failed operations

Related skills#

• client-setup (https://trpc.io/docs/client/vanilla/setup): npx @tanstack/intent@latest load @trpc/client#client-setup