Skip to main content
Version: 10.x

Define Procedures

Procedures in tRPC are very flexible primitives to create backend functions; they use a builder pattern which means you can create reusable base procedures for different parts of your backend application.

tip
  • A procedure can be viewed as the equivalent of a REST-endpoint or a function.
  • There's no internal difference between queries and mutations apart from semantics.
  • Defining publicProcedure is the same for queries, mutations, and subscription with the exception that subscriptions need to return an observable instance.

Example without input validation​

ts
import { router, publicProcedure } from './trpc';
import { z } from 'zod';
 
const appRouter = router({
  // Create publicProcedure at path 'hello'
  hello: publicProcedure.query(() => {
    return {
      greeting: 'hello world',
    };
  }),
});
 
ts
import { router, publicProcedure } from './trpc';
import { z } from 'zod';
 
const appRouter = router({
  // Create publicProcedure at path 'hello'
  hello: publicProcedure.query(() => {
    return {
      greeting: 'hello world',
    };
  }),
});
 

Input validation​

tRPC works out-of-the-box with yup/superstruct/zod/myzod/custom validators/[..] - see test suite

With Zod​

ts
import { publicProcedure, router } from './trpc';
import { z } from 'zod';
 
export const appRouter = router({
  hello: publicProcedure
    .input(
      z
        .object({
          text: z.string(),
        })
        .optional(),
    )
    .query(({ input }) => {
               
(parameter) input: {
    text: string;
} | undefined
      return {
        greeting: `hello ${input?.text ?? 'world'}`,
      };
    }),
});
 
export type AppRouter = typeof appRouter;
ts
import { publicProcedure, router } from './trpc';
import { z } from 'zod';
 
export const appRouter = router({
  hello: publicProcedure
    .input(
      z
        .object({
          text: z.string(),
        })
        .optional(),
    )
    .query(({ input }) => {
               
(parameter) input: {
    text: string;
} | undefined
      return {
        greeting: `hello ${input?.text ?? 'world'}`,
      };
    }),
});
 
export type AppRouter = typeof appRouter;

With Yup​

tsx
import { initTRPC } from '@trpc/server';
import * as yup from 'yup';
export const t = initTRPC.create();
export const appRouter = router({
  hello: publicProcedure
    .input(
      yup.object({
        text: yup.string().required(),
      }),
    )
    .query(({ input }) => {
      return {
        greeting: `hello ${input?.text ?? 'world'}`,
      };
    }),
});
export type AppRouter = typeof appRouter;
tsx
import { initTRPC } from '@trpc/server';
import * as yup from 'yup';
export const t = initTRPC.create();
export const appRouter = router({
  hello: publicProcedure
    .input(
      yup.object({
        text: yup.string().required(),
      }),
    )
    .query(({ input }) => {
      return {
        greeting: `hello ${input?.text ?? 'world'}`,
      };
    }),
});
export type AppRouter = typeof appRouter;

With Superstruct​

tsx
import { initTRPC } from '@trpc/server';
import { defaulted, object, string } from 'superstruct';
export const t = initTRPC.create();
export const appRouter = router({
  hello: publicProcedure
    .input(
      object({
        /**
         * Also supports inline doc strings when referencing the type.
         */
        text: defaulted(string(), 'world'),
      }),
    )
    .query(({ input }) => {
      return {
        greeting: `hello ${input.text}`,
      };
    }),
});
export type AppRouter = typeof appRouter;
tsx
import { initTRPC } from '@trpc/server';
import { defaulted, object, string } from 'superstruct';
export const t = initTRPC.create();
export const appRouter = router({
  hello: publicProcedure
    .input(
      object({
        /**
         * Also supports inline doc strings when referencing the type.
         */
        text: defaulted(string(), 'world'),
      }),
    )
    .query(({ input }) => {
      return {
        greeting: `hello ${input.text}`,
      };
    }),
});
export type AppRouter = typeof appRouter;

Multiple input parsers​

You're able to chain multiple parsers in order to make reusable publicProcedures for different parts of your application.

ts
// ------------------------------
// @filename: roomProcedure.ts
// ------------------------------
import { publicProcedure } from './trpc';
import { z } from 'zod';
 
/**
 * Create reusable publicProcedure for a chat room
 */
export const roomProcedure = publicProcedure.input(
  z.object({
    roomId: z.string(),
  }),
);
 
// ------------------------------
// @filename: _app.ts
// ------------------------------
import { router } from './trpc';
import { roomProcedure } from './roomProcedure';
import { z } from 'zod';
 
 
const appRouter = router({
  sendMessage: roomProcedure
    // Add extra input validation for the `sendMessage`-procedure
    .input(
      z.object({
        text: z.string(),
      }),
    )
    .mutation(({ input }) => {
                  
(parameter) input: {
    roomId: string;
    text: string;
}
      // [...]
    }),
});
 
export type AppRouter = typeof appRouter;
ts
// ------------------------------
// @filename: roomProcedure.ts
// ------------------------------
import { publicProcedure } from './trpc';
import { z } from 'zod';
 
/**
 * Create reusable publicProcedure for a chat room
 */
export const roomProcedure = publicProcedure.input(
  z.object({
    roomId: z.string(),
  }),
);
 
// ------------------------------
// @filename: _app.ts
// ------------------------------
import { router } from './trpc';
import { roomProcedure } from './roomProcedure';
import { z } from 'zod';
 
 
const appRouter = router({
  sendMessage: roomProcedure
    // Add extra input validation for the `sendMessage`-procedure
    .input(
      z.object({
        text: z.string(),
      }),
    )
    .mutation(({ input }) => {
                  
(parameter) input: {
    roomId: string;
    text: string;
}
      // [...]
    }),
});
 
export type AppRouter = typeof appRouter;

Multiple Procedures​

To add multiple publicProcedures, you define them as properties on the object passed to t.router().

tsx
import { initTRPC } from '@trpc/server';
export const t = initTRPC.create();
const router = t.router;
const publicProcedure = t.procedure;
export const appRouter = router({
  hello: publicProcedure.query(() => {
    return {
      text: 'hello world',
    };
  }),
  bye: publicProcedure.query(() => {
    return {
      text: 'goodbye',
    };
  }),
});
export type AppRouter = typeof appRouter;
tsx
import { initTRPC } from '@trpc/server';
export const t = initTRPC.create();
const router = t.router;
const publicProcedure = t.procedure;
export const appRouter = router({
  hello: publicProcedure.query(() => {
    return {
      text: 'hello world',
    };
  }),
  bye: publicProcedure.query(() => {
    return {
      text: 'goodbye',
    };
  }),
});
export type AppRouter = typeof appRouter;

Reusable base procedures​

You can create reusable base procedures to have a set of login-protected procedures.

tip

This can be combined with multiple input parsers & metadata to create powerful reusable authorization and authentication patterns.

tsx
// -------------------------------------------------
// @filename: context.ts
// -------------------------------------------------
 
import { inferAsyncReturnType } from '@trpc/server';
import * as trpcNext from '@trpc/server/adapters/next';
import { getSession } from 'next-auth/react';
 
/**
 * Creates context for an incoming request
 * @link https://trpc.io/docs/context
 */
export async function createContext(opts: trpcNext.CreateNextContextOptions) {
  const session = await getSession({ req: opts.req });
 
  return {
    session,
  };
};
 
export type Context = inferAsyncReturnType<typeof createContext>;
 
// -------------------------------------------------
// @filename: trpc.ts
// -------------------------------------------------
import { initTRPC, TRPCError } from '@trpc/server';
import { Context } from './context';
 
const t = initTRPC.context<Context>().create();
 
/**
 * Reusable middleware that checks if users are authenticated.
 **/
const isAuthed = t.middleware(({ next, ctx }) => {
  if (!ctx.session?.user?.email) {
    throw new TRPCError({
      code: 'UNAUTHORIZED',
    });
  }
  return next({
    ctx: {
      // Infers the `session` as non-nullable
      session: ctx.session,
    },
  });
});
 
export const middleware = t.middleware;
export const router = t.router;
 
/**
 * Unprotected procedure
 **/
export const publicProcedure = t.procedure;
 
/**
 * Protected procedure
 **/
export const protectedProcedure = t.procedure.use(isAuthed);
 
// -------------------------------------------------
// @filename: _app.ts
// -------------------------------------------------
import { protectedProcedure, publicProcedure, router } from './trpc';
import { z } from 'zod';
 
export const appRouter = router({
  createPost: protectedProcedure
    .mutation(({ ctx }) => {
      const session = ctx.session;
              
const session: Session
      // [...]
    }),
  whoami: publicProcedure
    .query(({ ctx }) => {
      const session = ctx.session;
              
const session: Session | null
      // [...]
    }),
});
tsx
// -------------------------------------------------
// @filename: context.ts
// -------------------------------------------------
 
import { inferAsyncReturnType } from '@trpc/server';
import * as trpcNext from '@trpc/server/adapters/next';
import { getSession } from 'next-auth/react';
 
/**
 * Creates context for an incoming request
 * @link https://trpc.io/docs/context
 */
export async function createContext(opts: trpcNext.CreateNextContextOptions) {
  const session = await getSession({ req: opts.req });
 
  return {
    session,
  };
};
 
export type Context = inferAsyncReturnType<typeof createContext>;
 
// -------------------------------------------------
// @filename: trpc.ts
// -------------------------------------------------
import { initTRPC, TRPCError } from '@trpc/server';
import { Context } from './context';
 
const t = initTRPC.context<Context>().create();
 
/**
 * Reusable middleware that checks if users are authenticated.
 **/
const isAuthed = t.middleware(({ next, ctx }) => {
  if (!ctx.session?.user?.email) {
    throw new TRPCError({
      code: 'UNAUTHORIZED',
    });
  }
  return next({
    ctx: {
      // Infers the `session` as non-nullable
      session: ctx.session,
    },
  });
});
 
export const middleware = t.middleware;
export const router = t.router;
 
/**
 * Unprotected procedure
 **/
export const publicProcedure = t.procedure;
 
/**
 * Protected procedure
 **/
export const protectedProcedure = t.procedure.use(isAuthed);
 
// -------------------------------------------------
// @filename: _app.ts
// -------------------------------------------------
import { protectedProcedure, publicProcedure, router } from './trpc';
import { z } from 'zod';
 
export const appRouter = router({
  createPost: protectedProcedure
    .mutation(({ ctx }) => {
      const session = ctx.session;
              
const session: Session
      // [...]
    }),
  whoami: publicProcedure
    .query(({ ctx }) => {
      const session = ctx.session;
              
const session: Session | null
      // [...]
    }),
});