Versión: 11.x

Contexto

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

Tu contexto almacena datos a los que todos tus procedimientos tRPC tendrán acceso, siendo el lugar ideal para incluir información como credenciales de autenticación.

Configurar el contexto se realiza en 2 pasos: definir el tipo durante la inicialización y luego crear el contexto en tiempo de ejecución para cada solicitud.

Definir el tipo de contexto

Al inicializar tRPC con initTRPC, debes encadenar .context<TContext>() a la función constructora initTRPC antes de llamar a .create(). El tipo TContext puede inferirse del tipo de retorno de una función o definirse explícitamente.

Esto garantizará que tu contexto tenga tipado correcto en procedimientos y middlewares.

ts
import { initTRPC } from '@trpc/server';
import type { CreateHTTPContextOptions } from '@trpc/server/adapters/standalone';
 
export const createContext = async (opts: CreateHTTPContextOptions) => {
  // Example: extract a session token from the request headers
  const token = opts.req.headers['authorization'];
 
  return {
    token,
  };
};
 
export type Context = Awaited<ReturnType<typeof createContext>>;
const t = initTRPC.context<Context>().create();
 
t.procedure.use((opts) => {
  opts.ctx;
       (property) ctx: {
    token: any;
}
 
  return opts.next();
});

ts
import { initTRPC } from '@trpc/server';
import type { CreateHTTPContextOptions } from '@trpc/server/adapters/standalone';
 
export const createContext = async (opts: CreateHTTPContextOptions) => {
  // Example: extract a session token from the request headers
  const token = opts.req.headers['authorization'];
 
  return {
    token,
  };
};
 
export type Context = Awaited<ReturnType<typeof createContext>>;
const t = initTRPC.context<Context>().create();
 
t.procedure.use((opts) => {
  opts.ctx;
       (property) ctx: {
    token: any;
}
 
  return opts.next();
});

Crear el contexto

Debes pasar la función createContext() al manejador que monta tu appRouter. El manejador puede usar HTTP o una llamada del lado del servidor.

createContext() se llama una vez por solicitud, por lo que todos los procedimientos dentro de una misma solicitud en lote comparten el mismo contexto.

ts
// 1. HTTP request
import { createHTTPHandler } from '@trpc/server/adapters/standalone';
import { createContext } from './context';
import { appRouter } from './router';
 
const handler = createHTTPHandler({
  router: appRouter,
  createContext,
});

ts
// 1. HTTP request
import { createHTTPHandler } from '@trpc/server/adapters/standalone';
import { createContext } from './context';
import { appRouter } from './router';
 
const handler = createHTTPHandler({
  router: appRouter,
  createContext,
});

ts
// 2. Server-side call
import { createContext } from './context';
import { createCaller } from './router';
 
const caller = createCaller(await createContext());

ts
// 2. Server-side call
import { createContext } from './context';
import { createCaller } from './router';
 
const caller = createCaller(await createContext());

ts
// 3. Server-side helpers (Next.js-specific, see /docs/client/nextjs/pages-router/server-side-helpers)
import { createServerSideHelpers } from '@trpc/react-query/server';
import { createContext } from './context';
import { appRouter } from './router';
 
const helpers = createServerSideHelpers({
  router: appRouter,
  ctx: await createContext(),
});

ts
// 3. Server-side helpers (Next.js-specific, see /docs/client/nextjs/pages-router/server-side-helpers)
import { createServerSideHelpers } from '@trpc/react-query/server';
import { createContext } from './context';
import { appRouter } from './router';
 
const helpers = createServerSideHelpers({
  router: appRouter,
  ctx: await createContext(),
});

Código de ejemplo

ts
// -------------------------------------------------
// @filename: context.ts
// -------------------------------------------------
import type { CreateHTTPContextOptions } from '@trpc/server/adapters/standalone';
 
/**
 * Creates context for an incoming request
 * @see https://trpc.io/docs/v11/context
 */
export async function createContext(opts: CreateHTTPContextOptions) {
  const token = opts.req.headers['authorization'];
 
  // In a real app, you would verify the token and look up the user
  const user = token ? { email: 'user@example.com' } : null;
 
  return {
    user,
  };
}
 
export type Context = Awaited<ReturnType<typeof createContext>>;
 
// -------------------------------------------------
// @filename: trpc.ts
// -------------------------------------------------
import { initTRPC, TRPCError } from '@trpc/server';
import { Context } from './context';
 
const t = initTRPC.context<Context>().create();
 
 
export const router = t.router;
 
/**
 * Unprotected procedure
 */
export const publicProcedure = t.procedure;
 
/**
 * Protected procedure
 */
export const protectedProcedure = t.procedure.use(function isAuthed(opts) {
  if (!opts.ctx.user?.email) {
    throw new TRPCError({
      code: 'UNAUTHORIZED',
    });
  }
  return opts.next({
    ctx: {
      // Infers the `user` as non-nullable
      user: opts.ctx.user,
    },
  });
});

ts
// -------------------------------------------------
// @filename: context.ts
// -------------------------------------------------
import type { CreateHTTPContextOptions } from '@trpc/server/adapters/standalone';
 
/**
 * Creates context for an incoming request
 * @see https://trpc.io/docs/v11/context
 */
export async function createContext(opts: CreateHTTPContextOptions) {
  const token = opts.req.headers['authorization'];
 
  // In a real app, you would verify the token and look up the user
  const user = token ? { email: 'user@example.com' } : null;
 
  return {
    user,
  };
}
 
export type Context = Awaited<ReturnType<typeof createContext>>;
 
// -------------------------------------------------
// @filename: trpc.ts
// -------------------------------------------------
import { initTRPC, TRPCError } from '@trpc/server';
import { Context } from './context';
 
const t = initTRPC.context<Context>().create();
 
 
export const router = t.router;
 
/**
 * Unprotected procedure
 */
export const publicProcedure = t.procedure;
 
/**
 * Protected procedure
 */
export const protectedProcedure = t.procedure.use(function isAuthed(opts) {
  if (!opts.ctx.user?.email) {
    throw new TRPCError({
      code: 'UNAUTHORIZED',
    });
  }
  return opts.next({
    ctx: {
      // Infers the `user` as non-nullable
      user: opts.ctx.user,
    },
  });
});

Contexto interno y externo

En algunos escenarios puede ser útil dividir tu contexto en funciones "internas" y "externas".

Contexto interno: Aquí defines elementos que no dependen de la solicitud, como tu conexión a la base de datos. Puedes usar esta función para pruebas de integración o llamadas del lado del servidor, donde no tienes un objeto de solicitud. Todo lo definido aquí estará siempre disponible en tus procedimientos.

Compensación para clientes grandes en createContextInner

Colocar un cliente de base de datos como prisma en createContextInner es conveniente y común, pero los clientes generados grandes (como Prisma) pueden incrementar la sobrecarga de verificación de tipos porque pasan a formar parte del tipo de contexto en todos los procedimientos.

Si esa sobrecarga se vuelve notable, una alternativa es mantener el contexto más reducido e importar el cliente directamente en los puntos de llamada donde sea necesario.

Contexto externo: Aquí defines elementos que dependen de la solicitud, como la sesión del usuario. Lo definido aquí solo está disponible para procedimientos llamados mediante HTTP.

Ejemplo de contexto interno y externo

ts
import type { CreateHTTPContextOptions } from '@trpc/server/adapters/standalone';
import { getSessionFromCookie, type Session } from './auth';
import { db } from './db';
 
/**
 * Defines your inner context shape.
 * Add fields here that the inner context brings.
 */
interface CreateInnerContextOptions {
  session: Session | null;
}
 
/**
 * Inner context. Will always be available in your procedures, in contrast to the outer context.
 *
 * Also useful for:
 * - testing, so you don't have to mock `req`/`res`
 * - server-side calls where we don't have `req`/`res`
 *
 * @see https://trpc.io/docs/v11/context#inner-and-outer-context
 */
export async function createContextInner(opts?: CreateInnerContextOptions) {
  return {
    db,
    session: opts?.session,
  };
}
 
/**
 * Outer context. Used in the routers and will e.g. bring `req` & `res` to the context as "not `undefined`".
 *
 * @see https://trpc.io/docs/v11/context#inner-and-outer-context
 */
export async function createContext(opts: CreateHTTPContextOptions) {
  const session = getSessionFromCookie(opts.req);
 
  const contextInner = await createContextInner({ session });
 
  return {
    ...contextInner,
    req: opts.req,
    res: opts.res,
  };
}
 
export type Context = Awaited<ReturnType<typeof createContextInner>>;
 
// The usage in your router is the same as the example above.

ts
import type { CreateHTTPContextOptions } from '@trpc/server/adapters/standalone';
import { getSessionFromCookie, type Session } from './auth';
import { db } from './db';
 
/**
 * Defines your inner context shape.
 * Add fields here that the inner context brings.
 */
interface CreateInnerContextOptions {
  session: Session | null;
}
 
/**
 * Inner context. Will always be available in your procedures, in contrast to the outer context.
 *
 * Also useful for:
 * - testing, so you don't have to mock `req`/`res`
 * - server-side calls where we don't have `req`/`res`
 *
 * @see https://trpc.io/docs/v11/context#inner-and-outer-context
 */
export async function createContextInner(opts?: CreateInnerContextOptions) {
  return {
    db,
    session: opts?.session,
  };
}
 
/**
 * Outer context. Used in the routers and will e.g. bring `req` & `res` to the context as "not `undefined`".
 *
 * @see https://trpc.io/docs/v11/context#inner-and-outer-context
 */
export async function createContext(opts: CreateHTTPContextOptions) {
  const session = getSessionFromCookie(opts.req);
 
  const contextInner = await createContextInner({ session });
 
  return {
    ...contextInner,
    req: opts.req,
    res: opts.res,
  };
}
 
export type Context = Awaited<ReturnType<typeof createContextInner>>;
 
// The usage in your router is the same as the example above.

Es crucial inferir tu Context desde el contexto interno, pues solo lo definido allí está realmente disponible siempre en tus procedimientos.

Si prefieres no verificar constantemente si req o res son undefined en tus procedimientos, puedes crear un pequeño procedimiento reutilizable:

ts
export const apiProcedure = publicProcedure.use((opts) => {
  if (!opts.ctx.req || !opts.ctx.res) {
    throw new Error('You are missing `req` or `res` in your call.');
  }
  return opts.next({
    ctx: {
      // We overwrite the context with the truthy `req` & `res`, which will also overwrite the types used in your procedure.
      req: opts.ctx.req,
      res: opts.ctx.res,
    },
  });
});

ts
export const apiProcedure = publicProcedure.use((opts) => {
  if (!opts.ctx.req || !opts.ctx.res) {
    throw new Error('You are missing `req` or `res` in your call.');
  }
  return opts.next({
    ctx: {
      // We overwrite the context with the truthy `req` & `res`, which will also overwrite the types used in your procedure.
      req: opts.ctx.req,
      res: opts.ctx.res,
    },
  });
});

Definir el tipo de contexto​

Crear el contexto​

Código de ejemplo​

Contexto interno y externo​

Ejemplo de contexto interno y externo​

Definir el tipo de contexto

Crear el contexto

Código de ejemplo

Contexto interno y externo

Ejemplo de contexto interno y externo