Move Fast and Break Nothing.End-to-end typesafe APIs made easy.

How it works#

It's quick and easy to get started with tRPC to build a typesafe API.

1. 1Define your procedures#

   The first step to creating a tRPC API is to define your procedures.

   Procedures are the functions we will use to build your backend. They're composable and can be queries, mutations, or subscriptions. Routers contain multiple procedures.

   In this procedure, we use a Zod validator to ensure the input from the client has exactly the shape that our procedure expects. We will also return a simple text string from the query.

   At the end of the file, we export the type of the router so we can use it in our frontend code in just a few moments.

   Define procedures

   const 
   const t: TRPCRootObject<object, object, RuntimeConfigOptions<object, object>, {
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }>t = const initTRPC: TRPCBuilder<object, object>initTRPC.
   TRPCBuilder<object, object>.create<RuntimeConfigOptions<object, object>>(opts?: RuntimeConfigOptions<object, object> | undefined): TRPCRootObject<object, object, RuntimeConfigOptions<object, object>, {
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }>create();
   
   const 
   const router: RouterBuilder<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }>router = 
   const t: TRPCRootObject<object, object, RuntimeConfigOptions<object, object>, {
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }>t.
   TRPCRootObject<object, object, RuntimeConfigOptions<object, object>, { ctx: object; meta: object; errorShape: DefaultErrorShape; transformer: false; }>.router: RouterBuilder<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }>router;
   const const publicProcedure: ProcedureBuilder<object, object, object, UnsetMarker, UnsetMarker, UnsetMarker, UnsetMarker, false, DefaultErrorShape>publicProcedure = 
   const t: TRPCRootObject<object, object, RuntimeConfigOptions<object, object>, {
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }>t.TRPCRootObject<object, object, RuntimeConfigOptions<object, object>, { ctx: object; meta: object; errorShape: DefaultErrorShape; transformer: false; }>.procedure: ProcedureBuilder<object, object, object, UnsetMarker, UnsetMarker, UnsetMarker, UnsetMarker, false, DefaultErrorShape>procedure;
   
   const 
   const appRouter: BuiltRouter<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }, DecorateCreateRouterOptions<{
       greeting: QueryProcedure<{
           input: {
               name: string;
           };
           output: `Hello ${string}`;
           meta: object;
           errorShape: DefaultErrorShape;
       }>;
   }>>appRouter = 
   const router: RouterBuilder
   <{
       greeting: QueryProcedure<{
           input: {
               name: string;
           };
           output: `Hello ${string}`;
           meta: object;
           errorShape: DefaultErrorShape;
       }>;
   }>(_: {
       greeting: QueryProcedure<{
           input: {
               name: string;
           };
           output: `Hello ${string}`;
           meta: object;
           errorShape: DefaultErrorShape;
       }>;
   }) => BuiltRouter<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }, DecorateCreateRouterOptions<{
       greeting: QueryProcedure<{
           input: {
               name: string;
           };
           output: `Hello ${string}`;
           meta: object;
           errorShape: DefaultErrorShape;
       }>;
   }>>router({
     
   greeting: QueryProcedure<{
       input: {
           name: string;
       };
       output: `Hello ${string}`;
       meta: object;
       errorShape: DefaultErrorShape;
   }>greeting: const publicProcedure: ProcedureBuilder<object, object, object, UnsetMarker, UnsetMarker, UnsetMarker, UnsetMarker, false, DefaultErrorShape>publicProcedure
       .
   ProcedureBuilder<object, object, object, UnsetMarker, UnsetMarker, UnsetMarker, UnsetMarker, false, DefaultErrorShape>.input<z.ZodObject<{
       name: z.ZodString;
   }, z.core.$strip>>(schema: z.ZodObject<{
       name: z.ZodString;
   }, z.core.$strip>): ProcedureBuilder<object, object, object, {
       name: string;
   }, {
       name: string;
   }, UnsetMarker, UnsetMarker, false, DefaultErrorShape>input(import zz.
   function object<{
       name: z.ZodString;
   }>(shape?: {
       name: z.ZodString;
   } | undefined, params?: string | {
       error?: string | z.core.$ZodErrorMap<NonNullable<z.core.$ZodIssueUnrecognizedKeys | z.core.$ZodIssueInvalidType<unknown>>> | undefined;
       message?: string | undefined | undefined;
   } | undefined): z.ZodObject<{
       name: z.ZodString;
   }, z.core.$strip>object({ name: z.ZodStringname: import zz.function string(params?: string | z.core.$ZodStringParams): z.ZodString (+1 overload)string() }))
       .
   ProcedureBuilder<object, object, object, { name: string; }, { name: string; }, UnsetMarker, UnsetMarker, false, DefaultErrorShape>.query<`Hello ${string}`>(resolver: ProcedureResolver<object, object, object, {
       name: string;
   }, UnsetMarker, `Hello ${string}`>): QueryProcedure<{
       input: {
           name: string;
       };
       output: `Hello ${string}`;
       meta: object;
       errorShape: DefaultErrorShape;
   }>query((
   opts: ProcedureResolverOptions<object, object, object, {
       name: string;
   }>opts) => {
         const { input } = 
   opts: ProcedureResolverOptions<object, object, object, {
       name: string;
   }>opts;
                 
   const input: {
       name: string;
   }
   
         return `Hello ${
   const input: {
       name: string;
   }input.name: stringname}` as type const = `Hello ${string}`const;
     }),
   });
   
   export type 
   type AppRouter = Router<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }, DecorateCreateRouterOptions<{
       greeting: QueryProcedure<{
           input: {
               name: string;
           };
           output: `Hello ${string}`;
           meta: object;
           errorShape: DefaultErrorShape;
       }>;
   }>> & DecorateCreateRouterOptions<{
       greeting: QueryProcedure<{
           input: {
               name: string;
           };
           output: `Hello ${string}`;
           meta: object;
           errorShape: DefaultErrorShape;
       }>;
   }>AppRouter = typeof 
   const appRouter: BuiltRouter<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }, DecorateCreateRouterOptions<{
       greeting: QueryProcedure<{
           input: {
               name: string;
           };
           output: `Hello ${string}`;
           meta: object;
           errorShape: DefaultErrorShape;
       }>;
   }>>appRouter;

   Copy

2. 2Create your HTTP server#

   Next, we create our HTTP server using our appRouter. We now have a tRPC server running!

   tRPC has many adapters so it can meet you where you are. Next.js, Express, the Fetch API (Astro, Remix, SvelteKit, Cloudflare Workers, etc.), Fastify, AWS Lambda, or a vanilla Node HTTP server.

   Adapters

   const { 
   const listen: {
       (port?: number, hostname?: string, backlog?: number, listeningListener?: () => void): Server<typeof IncomingMessage, typeof ServerResponse>;
       (port?: number, hostname?: string, listeningListener?: () => void): Server<typeof IncomingMessage, typeof ServerResponse>;
       (port?: number, backlog?: number, listeningListener?: () => void): Server<typeof IncomingMessage, typeof ServerResponse>;
       (port?: number, listeningListener?: () => void): Server<...>;
       (path: string, backlog?: number, listeningListener?: () => void): Server<...>;
       (path: string, listeningListener?: () => void): Server<...>;
       (options: ListenOptions, listeningListener?: () => void): Server<...>;
       (handle: any, backlog?: number, listeningListener?: () => void): Server<...>;
       (handle: any, listeningListener?: () => void): Server<...>;
   }listen } = 
   createHTTPServer<BuiltRouter<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }, DecorateCreateRouterOptions<{}>>>(opts: CreateHTTPHandlerOptions<BuiltRouter<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }, DecorateCreateRouterOptions<{}>>>): Server<typeof IncomingMessage, typeof ServerResponse>createHTTPServer({
     
   BaseHandlerOptions<BuiltRouter<{ ctx: object; meta: object; errorShape: DefaultErrorShape; transformer: false; }, DecorateCreateRouterOptions<{}>>, IncomingMessage>.router: BuiltRouter<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }, DecorateCreateRouterOptions<{}>>router: 
   const appRouter: BuiltRouter<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }, DecorateCreateRouterOptions<{}>>appRouter,
   });
   
   // The API will now be listening on port 3000!
   const listen: (port?: number, hostname?: string, backlog?: number, listeningListener?: () => void) => Server<typeof IncomingMessage, typeof ServerResponse> (+8 overloads)listen(3000);

   Copy

3. 3Connect your client and start querying!#

   Now that we have the server running, we can create a client and start querying data.

   We pass the AppRouter type when creating the client to give us TypeScript autocompletion and Intellisense that matches the backend API without requiring any code generation!

   The vanilla client

   const 
   const trpc: TRPCClient<BuiltRouter<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }, DecorateCreateRouterOptions<{
       greeting: QueryProcedure<{
           input: {
               name: string;
           };
           output: `Hello ${string}`;
           meta: object;
           errorShape: DefaultErrorShape;
       }>;
   }>>>trpc = 
   createTRPCClient<BuiltRouter<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }, DecorateCreateRouterOptions<{
       greeting: QueryProcedure<{
           input: {
               name: string;
           };
           output: `Hello ${string}`;
           meta: object;
           errorShape: DefaultErrorShape;
       }>;
   }>>>(opts: CreateTRPCClientOptions<BuiltRouter<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }, DecorateCreateRouterOptions<{
       greeting: QueryProcedure<{
           input: {
               name: string;
           };
           output: `Hello ${string}`;
           meta: object;
           errorShape: DefaultErrorShape;
       }>;
   }>>>): TRPCClient<...>createTRPCClient<
   type AppRouter = Router<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }, DecorateCreateRouterOptions<{
       greeting: QueryProcedure<{
           input: {
               name: string;
           };
           output: `Hello ${string}`;
           meta: object;
           errorShape: DefaultErrorShape;
       }>;
   }>> & DecorateCreateRouterOptions<{
       greeting: QueryProcedure<{
           input: {
               name: string;
           };
           output: `Hello ${string}`;
           meta: object;
           errorShape: DefaultErrorShape;
       }>;
   }>AppRouter>({
     
   links: TRPCLink<BuiltRouter<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }, DecorateCreateRouterOptions<{
       greeting: QueryProcedure<{
           input: {
               name: string;
           };
           output: `Hello ${string}`;
           meta: object;
           errorShape: DefaultErrorShape;
       }>;
   }>>>[]links: [
       
   httpBatchLink<BuiltRouter<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }, DecorateCreateRouterOptions<{
       greeting: QueryProcedure<{
           input: {
               name: string;
           };
           output: `Hello ${string}`;
           meta: object;
           errorShape: DefaultErrorShape;
       }>;
   }>>>(opts: HTTPBatchLinkOptions<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }>): TRPCLink<BuiltRouter<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }, DecorateCreateRouterOptions<...>>>httpBatchLink({
         url: string | URLurl: 'http://localhost:3000',
       }),
     ],
   });
   
   const res = await 
   const trpc: TRPCClient<BuiltRouter<{
       ctx: object;
       meta: object;
       errorShape: DefaultErrorShape;
       transformer: false;
   }, DecorateCreateRouterOptions<{
       greeting: QueryProcedure<{
           input: {
               name: string;
           };
           output: `Hello ${string}`;
           meta: object;
           errorShape: DefaultErrorShape;
       }>;
   }>>>trpc.
   greeting: {
       query: Resolver<{
           input: {
               name: string;
           };
           output: `Hello ${string}`;
           errorShape: DefaultErrorShape;
           transformer: false;
       }>;
   }greeting.
   query: (input: {
       name: string;
   }, opts?: TRPCProcedureOptions) => TRPCTaggedPromise<`Hello ${string}`, DefaultErrorShape>query({ name: stringname: 'John' });
        
   const res: `Hello ${string}`

   Copy