Skip to main content
Version: 10.x

Links & Request Batching

Similar to urql's exchanges or Apollo's links. Links enables you to customize the flow of data between tRPC Client and the tRPC-server.

Request Batching​

Request batching is automatically enabled which batches your requests to the server, this can make the below code produce exactly one HTTP request and on the server exactly one database query:

ts
// below will be done in the same request when batching is enabled
const somePosts = await Promise.all([
  proxy.post.byId.query(1);
  proxy.post.byId.query(2);
  proxy.post.byId.query(3);
])
ts
// below will be done in the same request when batching is enabled
const somePosts = await Promise.all([
  proxy.post.byId.query(1);
  proxy.post.byId.query(2);
  proxy.post.byId.query(3);
])

Customizing data flow​

The below examples assuming you use Next.js, but the same as below can be added if you use the vanilla tRPC client

Setting a maximum URL length​

When sending batch requests, sometimes the URL can become too large causing HTTP errors like 413 Payload Too Large, 414 URI Too Long, and 404 Not Found. The maxURLLength option will limit the number of requests that can be sent together in a batch.

utils/trpc.ts
ts
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from "@/server/routers/app";
export const trpc = createTRPCNext<AppRouter>({
  config() {
    return {
      links: [
        httpBatchLink({
          url: 'http://localhost:3000/api/trpc',
          maxURLLength: 2083 // a suitable size
        }),
      ],
    };
  },
});
utils/trpc.ts
ts
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from "@/server/routers/app";
export const trpc = createTRPCNext<AppRouter>({
  config() {
    return {
      links: [
        httpBatchLink({
          url: 'http://localhost:3000/api/trpc',
          maxURLLength: 2083 // a suitable size
        }),
      ],
    };
  },
});

Disabling request batching​

1. Disable batching on your server:​

In your [trpc].ts:

pages/api/trpc/[trpc].ts
ts
export default trpcNext.createNextApiHandler({
  // [...]
  // 👇 disable batching
  batching: {
    enabled: false,
  },
});
pages/api/trpc/[trpc].ts
ts
export default trpcNext.createNextApiHandler({
  // [...]
  // 👇 disable batching
  batching: {
    enabled: false,
  },
});
utils/trpc.ts
tsx
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from "@/server/routers/app";
import { httpLink } from '@trpc/client';
export const trpc = createTRPCNext<AppRouter>({
  config() {
    return {
      links: [
        httpLink({
          url: '/api/trpc',
        }),
      ],
    };
  },
});
utils/trpc.ts
tsx
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from "@/server/routers/app";
import { httpLink } from '@trpc/client';
export const trpc = createTRPCNext<AppRouter>({
  config() {
    return {
      links: [
        httpLink({
          url: '/api/trpc',
        }),
      ],
    };
  },
});

Disable batching for certain requests​

1. Configure client / utils/trpc.ts​
utils/trpc.ts
tsx
import { createTRPCNext } from '@trpc/next';
import { httpBatchLink, httpLink, splitLink } from '@trpc/client';
export default createTRPCNext<AppRouter>({
  config() {
    const url = `http://localhost:3000`;
    return {
      links: [
        splitLink({
          condition(op) {
            // check for context property `skipBatch`
            return op.context.skipBatch === true;
          },
          // when condition is true, use normal request
          true: httpLink({
            url,
          }),
          // when condition is false, use batching
          false: httpBatchLink({
            url,
          }),
        }),
      ],
    };
  },
});
utils/trpc.ts
tsx
import { createTRPCNext } from '@trpc/next';
import { httpBatchLink, httpLink, splitLink } from '@trpc/client';
export default createTRPCNext<AppRouter>({
  config() {
    const url = `http://localhost:3000`;
    return {
      links: [
        splitLink({
          condition(op) {
            // check for context property `skipBatch`
            return op.context.skipBatch === true;
          },
          // when condition is true, use normal request
          true: httpLink({
            url,
          }),
          // when condition is false, use batching
          false: httpBatchLink({
            url,
          }),
        }),
      ],
    };
  },
});
2. Perform request without batching​
client.ts
ts
const postResult = proxy.posts.query(null, {
  context: {
    skipBatch: true,
  },
})
client.ts
ts
const postResult = proxy.posts.query(null, {
  context: {
    skipBatch: true,
  },
})

or:

MyComponent.tsx
tsx
export function MyComponent() {
  const postsQuery = proxy.posts.useQuery(undefined, {
    trpc: {
      context: {
        skipBatch: true,
      },
    }
  });
  return (
    <pre>{JSON.stringify(postsQuery.data ?? null, null, 4)}</pre>
  )
})
MyComponent.tsx
tsx
export function MyComponent() {
  const postsQuery = proxy.posts.useQuery(undefined, {
    trpc: {
      context: {
        skipBatch: true,
      },
    }
  });
  return (
    <pre>{JSON.stringify(postsQuery.data ?? null, null, 4)}</pre>
  )
})

Reference examples can be found in packages/client/src/links.

utils/customLink.ts
tsx
import { TRPCLink } from '@trpc/client';
import { AppRouter } from 'server/routers/_app';
import { observable } from '@trpc/server/observable';
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;
    });
  };
};
utils/customLink.ts
tsx
import { TRPCLink } from '@trpc/client';
import { AppRouter } from 'server/routers/_app';
import { observable } from '@trpc/server/observable';
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;
    });
  };
};