Version: 10.x

Migrate from v9 to v10

Is v10 ready for production?

tRPC v10 is ready for production & can safely be used today. However, we will do changes to the API before we do a final release where you'll have to figure out the migration path between the releases on your own.

Under the hood of version 10, we are unlocking performance improvements, bringing you quality of life enhancements, and creating room for us to build new features in the future.

tRPC v10 features a compatibility layer for users coming from v9. .interop() allows you to incrementally adopt v10 so that you can continue building the rest of your project while still enjoying v10's new features.

Summary of changes

The `t` variable

If you don't like the variable name t, you can call it whatever you want
You should create your root t-variable exactly once per application

The way you initialize tRPC on the server has been update, we now create a root t variable that contains the root information about your app:

The way the t variable is defined is simply like this:

/src/server/trpc.ts
ts
import { initTRPC } from '@trpc/server';
export const t = initTRPC.create();

/src/server/trpc.ts
ts
import { initTRPC } from '@trpc/server';
export const t = initTRPC.create();

Here's a full example of how the t variable may look like with a data-transformer, openapi metadata and error formatter:

/src/server/trpc.ts
ts
import { initTRPC } from '@trpc/server';
import superjson from 'superjson';
// This is usually inferred
interface Context {
  user?: {
    id: string;
    name: string;
  };
}
interface Meta {
  openapi: {
    enabled: boolean;
    method: string;
    path: string;
  };
}
export const t = initTRPC
  .context<Context>()
  .meta<Meta>()
  .create({
    errorFormatter({ shape, error }) {
      return {
        ...shape,
        data: {
          ...shape.data,
          zodError:
            error.code === 'BAD_REQUEST' && error.cause instanceof ZodError
              ? error.cause.flatten()
              : null,
        },
      };
    },
    transformer: superjson,
  });

/src/server/trpc.ts
ts
import { initTRPC } from '@trpc/server';
import superjson from 'superjson';
// This is usually inferred
interface Context {
  user?: {
    id: string;
    name: string;
  };
}
interface Meta {
  openapi: {
    enabled: boolean;
    method: string;
    path: string;
  };
}
export const t = initTRPC
  .context<Context>()
  .meta<Meta>()
  .create({
    errorFormatter({ shape, error }) {
      return {
        ...shape,
        data: {
          ...shape.data,
          zodError:
            error.code === 'BAD_REQUEST' && error.cause instanceof ZodError
              ? error.cause.flatten()
              : null,
        },
      };
    },
    transformer: superjson,
  });

Defining routers & procedures

ts
// v9:
const appRouter = trpc.router()
  .query('greeting', {
    input: z.string(),
    resolve({ input }) {
      return `hello ${input}!`;
    },
  });
// v10:
const appRouter = t.router({
  greeting: t.procedure
    .input(z.string())
    .query(({ input }) => `hello ${input}!`),
});

ts
// v9:
const appRouter = trpc.router()
  .query('greeting', {
    input: z.string(),
    resolve({ input }) {
      return `hello ${input}!`;
    },
  });
// v10:
const appRouter = t.router({
  greeting: t.procedure
    .input(z.string())
    .query(({ input }) => `hello ${input}!`),
});

Calling procedures

ts
// OLD
client.query('greeting', 'KATT');
trpc.useQuery(['greeting', 'KATT']);
// NEW - you'll be able to CMD+click `greeting` below and jump straight to your backend code
client.greeting.query('KATT');
trpc.greeting.useQuery('KATT');

ts
// OLD
client.query('greeting', 'KATT');
trpc.useQuery(['greeting', 'KATT']);
// NEW - you'll be able to CMD+click `greeting` below and jump straight to your backend code
client.greeting.query('KATT');
trpc.greeting.useQuery('KATT');

Inferring types

ts
// OLD - you had to make multiple complex helper types yourself
type GreetingInput = InferQueryInput<'greeting'>;
type GreetingOutput = InferQueryOutput<'greeting'>;
// NEW - same helper for all procedure types which are shipped out of the box
type GreetingInput = inferProcedureInput<AppRouter['greeting']>;
type GreetingOutput = inferProcedureOutput<AppRouter['greeting']>;

ts
// OLD - you had to make multiple complex helper types yourself
type GreetingInput = InferQueryInput<'greeting'>;
type GreetingOutput = InferQueryOutput<'greeting'>;
// NEW - same helper for all procedure types which are shipped out of the box
type GreetingInput = inferProcedureInput<AppRouter['greeting']>;
type GreetingOutput = inferProcedureOutput<AppRouter['greeting']>;

Middlewares

Middlewares are now reusable and can be chained, see middleware docs.

ts
// OLD
const appRouter = trpc
  .router()
  .middleware(({ next, ctx }) => {
    if (!ctx.user) {
      throw new TRPCError({ code: 'UNAUTHORIZED' });
    }
    return next({
      ctx: {
        ...ctx,
        user: ctx.user,
      },
    });
  })
  .query('greeting', {
    resolve({ input }) {
      return `hello ${ctx.user.name}!`;
    },
  });
// NEW
const isAuthed = t.middleware(({ next, ctx }) => {
  if (!ctx.user) {
    throw new TRPCError({ code: 'UNAUTHORIZED' });
  }
  return next({
    ctx: {
      // <-- auto-spreading old context, modify only what's changed
      user: ctx.user,
    },
  });
});
// Reusable:
const authedProcedure = t.procedure.use(isAuthed);
const appRouter = t.router({
  greeting: authedProcedure.query(({ ctx }) => {
    return `Hello ${ctx.user.name}!`
  }),
});

ts
// OLD
const appRouter = trpc
  .router()
  .middleware(({ next, ctx }) => {
    if (!ctx.user) {
      throw new TRPCError({ code: 'UNAUTHORIZED' });
    }
    return next({
      ctx: {
        ...ctx,
        user: ctx.user,
      },
    });
  })
  .query('greeting', {
    resolve({ input }) {
      return `hello ${ctx.user.name}!`;
    },
  });
// NEW
const isAuthed = t.middleware(({ next, ctx }) => {
  if (!ctx.user) {
    throw new TRPCError({ code: 'UNAUTHORIZED' });
  }
  return next({
    ctx: {
      // <-- auto-spreading old context, modify only what's changed
      user: ctx.user,
    },
  });
});
// Reusable:
const authedProcedure = t.procedure.use(isAuthed);
const appRouter = t.router({
  greeting: authedProcedure.query(({ ctx }) => {
    return `Hello ${ctx.user.name}!`
  }),
});

Migrating from v9

info

There are a few features that are not supported by .interop(). We expect nearly all of our users to be able to use .interop() to migrate their server side code in only a few minutes. If you are discovering that .interop() is not working correctly for you, be sure to check here.

You may choose to start writing new procedures using the v10 syntax - but keep your v9 procedures in place for now. Incremental adoption is only a matter of merging the two routers together.

Turning your v9 router into a v10 router only takes 10 characters. Add .interop() to the end of your v9 router...and you're done with your server code!

We will create a simple hello world v10 router to demonstrate interoperability mode. If you have not learned how to create a more complex tRPC v10 router yet, we encourage you to check out the rest of the documentation.

1. Enable `interop()` on a v9 router

All you'll need to do is to add an .interop() at the end of your appRouter. Example.

src/server/routers/_app.ts
diff
  const appRouter = trpc
    .router<Context>()
    /* ... */
+ .interop();
  export type AppRouter = typeof appRouter;

src/server/routers/_app.ts
diff
  const appRouter = trpc
    .router<Context>()
    /* ... */
+ .interop();
  export type AppRouter = typeof appRouter;

2. Create the `t`-object

src/server/trpc.ts
ts
import superjson from 'superjson';
import { Context } from './context';
export const t = initTRPC.context<Context>().create({
  // Optional:
  transformer: superjson,
  // Optional:
  errorFormatter({ shape }) {
    return {
      ...shape,
      data: {
        ...shape.data,
      },
    };
  },
});

src/server/trpc.ts
ts
import superjson from 'superjson';
import { Context } from './context';
export const t = initTRPC.context<Context>().create({
  // Optional:
  transformer: superjson,
  // Optional:
  errorFormatter({ shape }) {
    return {
      ...shape,
      data: {
        ...shape.data,
      },
    };
  },
});

3. Create a new `appRouter`

tip

Be careful of using procedures that will end up having the same caller name! You will run into issues if a path in your legacy router matches a path in your new router.

Both sets of procedures will now be available for your client. You will now need to visit your client code to update your callers to the v10 syntax.

Rename your old appRouter to legacyRouter
Create a new app router:

src/server/routers/_app.ts
ts
import * as trpc from '@trpc/server';
import { t } from './trpc';
 
// Renamed from `appRouter`
const legacyRouter = trpc
  .router()
  /* [...] */
  .interop();
 
const mainRouter = t.router({
  greeting: t.procedure.query(() => 'hello tRPC v10!'),
});
 
// Merges the v9 router with v10 router
export const appRouter = t.mergeRouters(legacyRouter, mainRouter);
 
export type AppRouter = typeof appRouter;

src/server/routers/_app.ts
ts
import * as trpc from '@trpc/server';
import { t } from './trpc';
 
// Renamed from `appRouter`
const legacyRouter = trpc
  .router()
  /* [...] */
  .interop();
 
const mainRouter = t.router({
  greeting: t.procedure.query(() => 'hello tRPC v10!'),
});
 
// Merges the v9 router with v10 router
export const appRouter = t.mergeRouters(legacyRouter, mainRouter);
 
export type AppRouter = typeof appRouter;

4. Use it in your client

ts
// Raw client:
client.proxy.greeting.query();
// React:
trpc.proxy.greeting.useQuery();

ts
// Raw client:
client.proxy.greeting.query();
// React:
trpc.proxy.greeting.useQuery();

Limitations of interop

Any procedures defined using t.procedure must be called on the client using the new way of calling procedures. What this means is that when you migrate the legacyRouter over to be a "v10-t.router", you'll have to update the frontend-usage of this router to use the new way of calling procedures.

Subscriptions

We have changed the API of Subscriptions where subscriptions need to return an observable-instance. See subscriptions docs.

🚧 Feel free to contribute to improve this section

Custom Links

See the Links documentation.

🚧 Feel free to contribute to improve this section

Client Package Changes

v10 also brings changes to the client side of your application. After making a few key changes, you'll unlock a few key quality of life changes:

Jump to server definitions straight from your client
Rename routers or procedures straight from the client

`@trpc/react`

Upgrade of `react-query`

We've upgraded peerDependencies from react-query@^3 to @tanstack/react-query@^4. Because our client hooks are only a thin wrapper around react-query, we encourage you to visit their migration guide for more details around our React hooks implementation.

tRPC-specific options on hooks moved to `trpc`

To avoid collisions and confusion with any built-in react-query properties, we have moved all of the tRPC options to a property called trpc. This namespace brings clarity to options that are tRPC specific and ensures that we won't collide with react-query in the future.

tsx
// Before
useQuery(['post.byId', '1'], {
  context: {
    batching: false,
  },
});
// After:
useQuery(['post.byId', '1'], {
  trpc: {
    context: {
      batching: false,
    },
  },
});
// or:
trpc.post.byId.useQuery('1', {
  trpc: {
    batching: false,
  },
});

tsx
// Before
useQuery(['post.byId', '1'], {
  context: {
    batching: false,
  },
});
// After:
useQuery(['post.byId', '1'], {
  trpc: {
    context: {
      batching: false,
    },
  },
});
// or:
trpc.post.byId.useQuery('1', {
  trpc: {
    batching: false,
  },
});

`@trpc/client`

Aborting procedures

We've moved to the industry standards when it comes to aborting procedures. Instead of calling a .cancel(), you now give the query an AbortSignal and call .abort() on its parent AbortController.

tsx
const ac = new AbortController();
const helloQuery = client.greeting.query('KATT', { signal: ac.signal });
// Aborting
ac.abort();

tsx
const ac = new AbortController();
const helloQuery = client.greeting.query('KATT', { signal: ac.signal });
// Aborting
ac.abort();

Extras

Removal of the teardown option

The teardown option has been removed and is no longer available.

Migrate custom error formatters

You will need to move the contents of your formatError() into the t-object, see the Error Formatting docs.

Summary of changes​

The t variable​

Defining routers & procedures​

Calling procedures​

Inferring types​

Middlewares​

Migrating from v9​

1. Enable interop() on a v9 router​

2. Create the t-object​

3. Create a new appRouter​

4. Use it in your client​

Limitations of interop​

Subscriptions​

Custom Links​

Client Package Changes​

@trpc/react​

Upgrade of react-query​

tRPC-specific options on hooks moved to trpc​

@trpc/client​

Aborting procedures​

Extras​

Removal of the teardown option​

Migrate custom error formatters​