Versión: 11.x

Configuración con el enrutador de páginas de Next.js

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 →

precaución

Esta guía es para el enrutador de páginas de Next.js. Si estás usando el enrutador de aplicación de Next.js, consulta la guía de configuración para App Router en su lugar.

Estructura de archivos recomendada

Recomendamos una estructura de archivos como esta, aunque no es obligatoria en tRPC. Es lo que verás en nuestros ejemplos. El resto de esta página te guiará paso a paso para agregar tRPC a esta estructura.

graphql
.
├── prisma  # <-- if prisma is added
│   └── [..]
├── src
│   ├── pages
│   │   ├── _app.tsx  # <-- add `withTRPC()`-HOC here
│   │   ├── api
│   │   │   └── trpc
│   │   │       └── [trpc].ts  # <-- tRPC HTTP handler
│   │   └── [..]
│   ├── server
│   │   ├── routers
│   │   │   ├── _app.ts  # <-- main app router
│   │   │   ├── post.ts  # <-- sub routers
│   │   │   └── [..]
│   │   ├── context.ts   # <-- create app context
│   │   └── trpc.ts      # <-- procedure helpers
│   └── utils
│       └── trpc.ts  # <-- your typesafe tRPC hooks
└── [..]

graphql
.
├── prisma  # <-- if prisma is added
│   └── [..]
├── src
│   ├── pages
│   │   ├── _app.tsx  # <-- add `withTRPC()`-HOC here
│   │   ├── api
│   │   │   └── trpc
│   │   │       └── [trpc].ts  # <-- tRPC HTTP handler
│   │   └── [..]
│   ├── server
│   │   ├── routers
│   │   │   ├── _app.ts  # <-- main app router
│   │   │   ├── post.ts  # <-- sub routers
│   │   │   └── [..]
│   │   ├── context.ts   # <-- create app context
│   │   └── trpc.ts      # <-- procedure helpers
│   └── utils
│       └── trpc.ts  # <-- your typesafe tRPC hooks
└── [..]

Agregar tRPC a un proyecto existente de Next.js

1. Instalar dependencias

npm
yarn
pnpm
bun
deno

npm install @trpc/server @trpc/client @trpc/react-query @trpc/next @tanstack/react-query@latest zod

yarn add @trpc/server @trpc/client @trpc/react-query @trpc/next @tanstack/react-query@latest zod

pnpm add @trpc/server @trpc/client @trpc/react-query @trpc/next @tanstack/react-query@latest zod

bun add @trpc/server @trpc/client @trpc/react-query @trpc/next @tanstack/react-query@latest zod

deno add npm:@trpc/server npm:@trpc/client npm:@trpc/react-query npm:@trpc/next npm:@tanstack/react-query@latest npm:zod

Agentes de IA

Si utilizas un agente de IA para programación, instala habilidades de tRPC para una mejor generación de código:

bash
npx @tanstack/intent@latest install

bash
npx @tanstack/intent@latest install

La integración con Next.js combina nuestra integración con React Query con algunas funcionalidades específicas para Next.js.

2. Habilitar modo estricto

Si quieres usar Zod para validación de entradas, asegúrate de habilitar el modo estricto en tu tsconfig.json:

tsconfig.json
diff
"compilerOptions": {
+   "strict": true
}

tsconfig.json
diff
"compilerOptions": {
+   "strict": true
}

Si el modo estricto es demasiado restrictivo, al menos deberías habilitar strictNullChecks:

tsconfig.json
diff
"compilerOptions": {
+   "strictNullChecks": true
}

tsconfig.json
diff
"compilerOptions": {
+   "strictNullChecks": true
}

3. Crear un enrutador tRPC

Inicializa tu backend tRPC en src/server/trpc.ts usando la función initTRPC, y crea tu primer enrutador. Aquí haremos un enrutador y procedimiento simple de "hola mundo". Para información más profunda sobre cómo crear tu API tRPC, consulta:

la guía de inicio rápido y documentación de uso del backend para información sobre tRPC
la documentación del adaptador para Next.js para montar tRPC en tu servidor Next.js.

View sample backend

server/trpc.ts
ts
import { initTRPC } from '@trpc/server';
 
// Avoid exporting the entire t-object
// since it's not very descriptive.
// For instance, the use of a t variable
// is common in i18n libraries.
const t = initTRPC.create();
 
// Base router and procedure helpers
export const router = t.router;
export const procedure = t.procedure;

server/trpc.ts
ts
import { initTRPC } from '@trpc/server';
 
// Avoid exporting the entire t-object
// since it's not very descriptive.
// For instance, the use of a t variable
// is common in i18n libraries.
const t = initTRPC.create();
 
// Base router and procedure helpers
export const router = t.router;
export const procedure = t.procedure;

server/routers/_app.ts
ts
import { z } from 'zod';
import { procedure, router } from '../trpc';
 
export const appRouter = router({
  hello: procedure
    .input(
      z.object({
        text: z.string(),
      }),
    )
    .query((opts) => {
      return {
        greeting: `hello ${opts.input.text}`,
      };
    }),
});
 
// export type definition of API
export type AppRouter = typeof appRouter;

server/routers/_app.ts
ts
import { z } from 'zod';
import { procedure, router } from '../trpc';
 
export const appRouter = router({
  hello: procedure
    .input(
      z.object({
        text: z.string(),
      }),
    )
    .query((opts) => {
      return {
        greeting: `hello ${opts.input.text}`,
      };
    }),
});
 
// export type definition of API
export type AppRouter = typeof appRouter;

pages/api/trpc/[trpc].ts
ts
import * as trpcNext from '@trpc/server/adapters/next';
import { appRouter } from '../../../server/routers/_app';
 
// export API handler
// @link https://trpc.io/docs/server/adapters
export default trpcNext.createNextApiHandler({
  router: appRouter,
  createContext: () => ({}),
});

pages/api/trpc/[trpc].ts
ts
import * as trpcNext from '@trpc/server/adapters/next';
import { appRouter } from '../../../server/routers/_app';
 
// export API handler
// @link https://trpc.io/docs/server/adapters
export default trpcNext.createNextApiHandler({
  router: appRouter,
  createContext: () => ({}),
});

nota

El backend anterior usa la estructura de archivos recomendada, pero puedes simplificar y poner todo directamente en un manejador de API si prefieres.

4. Crear hooks tRPC

Usa la función createTRPCNext para crear un conjunto de hooks con tipado seguro a partir de la firma de tipos de tu API.

utils/trpc.ts
tsx
import { httpBatchLink } from '@trpc/client';
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from '../server/routers/_app';
 
function getBaseUrl() {
  if (typeof window !== 'undefined')
    // browser should use relative path
    return '';
 
  if (process.env.VERCEL_URL)
    // reference for vercel.com
    return `https://${process.env.VERCEL_URL}`;
 
  if (process.env.RENDER_INTERNAL_HOSTNAME)
    // reference for render.com
    return `http://${process.env.RENDER_INTERNAL_HOSTNAME}:${process.env.PORT}`;
 
  // assume localhost
  return `http://localhost:${process.env.PORT ?? 3000}`;
}
 
export const trpc = createTRPCNext<AppRouter>({
  config(config) {
    return {
      links: [
        httpBatchLink({
          /**
           * If you want to use SSR, you need to use the server's full URL
           * @see https://trpc.io/docs/client/nextjs/pages-router/ssr
           **/
          url: `${getBaseUrl()}/api/trpc`,
 
          // You can pass any HTTP headers you wish here
          async headers() {
            return {
              // authorization: getAuthCookie(),
            };
          },
        }),
      ],
    };
  },
  /**
   * @see https://trpc.io/docs/client/nextjs/pages-router/ssr
   **/
  ssr: false,
});

utils/trpc.ts
tsx
import { httpBatchLink } from '@trpc/client';
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from '../server/routers/_app';
 
function getBaseUrl() {
  if (typeof window !== 'undefined')
    // browser should use relative path
    return '';
 
  if (process.env.VERCEL_URL)
    // reference for vercel.com
    return `https://${process.env.VERCEL_URL}`;
 
  if (process.env.RENDER_INTERNAL_HOSTNAME)
    // reference for render.com
    return `http://${process.env.RENDER_INTERNAL_HOSTNAME}:${process.env.PORT}`;
 
  // assume localhost
  return `http://localhost:${process.env.PORT ?? 3000}`;
}
 
export const trpc = createTRPCNext<AppRouter>({
  config(config) {
    return {
      links: [
        httpBatchLink({
          /**
           * If you want to use SSR, you need to use the server's full URL
           * @see https://trpc.io/docs/client/nextjs/pages-router/ssr
           **/
          url: `${getBaseUrl()}/api/trpc`,
 
          // You can pass any HTTP headers you wish here
          async headers() {
            return {
              // authorization: getAuthCookie(),
            };
          },
        }),
      ],
    };
  },
  /**
   * @see https://trpc.io/docs/client/nextjs/pages-router/ssr
   **/
  ssr: false,
});

nota

createTRPCNext no funciona con el modo de interoperabilidad de tRPC-v9. Si estás migrando desde v9 usando interoperabilidad, debes seguir usando la forma anterior de inicializar tRPC.

5. Configurar `_app.tsx`

Envuelve tu página raíz de la aplicación en el HOC trpc.withTRPC, de forma similar a esto:

pages/_app.tsx
tsx
import type { AppType } from 'next/app';
import { trpc } from '../utils/trpc';
 
const MyApp: AppType = ({ Component, pageProps }) => {
  return <Component {...pageProps} />;
};
 
export default trpc.withTRPC(MyApp);

pages/_app.tsx
tsx
import type { AppType } from 'next/app';
import { trpc } from '../utils/trpc';
 
const MyApp: AppType = ({ Component, pageProps }) => {
  return <Component {...pageProps} />;
};
 
export default trpc.withTRPC(MyApp);

6. Realizar una solicitud a la API

¡Estás listo!

Ahora puedes usar los hooks de React que acabas de crear para invocar tu API. Para más detalles, consulta la integración con React Query

pages/index.tsx
tsx
import { trpc } from '../utils/trpc';
 
export default function IndexPage() {
  const hello = trpc.hello.useQuery({ text: 'client' });
  if (!hello.data) {
    return <div>Loading...</div>;
  }
  return (
    <div>
      <p>{hello.data.greeting}</p>
    </div>
  );
}

pages/index.tsx
tsx
import { trpc } from '../utils/trpc';
 
export default function IndexPage() {
  const hello = trpc.hello.useQuery({ text: 'client' });
  if (!hello.data) {
    return <div>Loading...</div>;
  }
  return (
    <div>
      <p>{hello.data.greeting}</p>
    </div>
  );
}

Opciones de `createTRPCNext()`

Callback `config`

El argumento config es una función que devuelve un objeto que configura los clientes de tRPC y React Query. Esta función recibe un objeto con una propiedad opcional ctx (de tipo NextPageContext) que te da acceso al objeto req de Next.js durante el renderizado en el servidor. El valor devuelto puede contener las siguientes propiedades:

Obligatorias:
links para personalizar el flujo de datos entre el cliente tRPC y el servidor tRPC. Lee más.
Opcionales:
queryClientConfig: objeto de configuración para el QueryClient de React Query utilizado internamente por los hooks de React de tRPC: Documentación de QueryClient
queryClient: una instancia de React Query QueryClient
- Nota: Solo puedes proporcionar un queryClient o un queryClientConfig, no ambos.
transformer: transformador aplicado a las cargas útiles salientes. Más información sobre Transformadores de Datos
abortOnUnmount: determina si las solicitudes en curso se cancelarán al desmontar el componente. Por defecto es false.

`overrides`: (predeterminado: `undefined`)

Configura sobreescrituras para los hooks de React Query.

`ssr`-booleano (predeterminado: `false`)

Indica si tRPC debe esperar las consultas al renderizar una página en el servidor. Por defecto es false.

Callback `responseMeta`

Permite establecer encabezados de solicitud y estado HTTP durante el renderizado en el servidor.

Ejemplo

utils/trpc.ts
tsx
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from '../server/routers/_app';
 
export const trpc = createTRPCNext<AppRouter>({
  config(config) {
    return {
      links: [
        /* [...] */
      ],
    };
  },
});

utils/trpc.ts
tsx
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from '../server/routers/_app';
 
export const trpc = createTRPCNext<AppRouter>({
  config(config) {
    return {
      links: [
        /* [...] */
      ],
    };
  },
});

Próximos pasos

Explora el resto de la documentación para aprender sobre temas como autorización, middlewares y manejo de errores.

También puedes encontrar información sobre consultas y mutaciones ahora que estás usando @trpc/react-query.

Estructura de archivos recomendada​

Agregar tRPC a un proyecto existente de Next.js​

1. Instalar dependencias​

2. Habilitar modo estricto​

3. Crear un enrutador tRPC​

4. Crear hooks tRPC​

5. Configurar _app.tsx​

6. Realizar una solicitud a la API​

Opciones de createTRPCNext()​

Callback config​

overrides: (predeterminado: undefined)​

ssr-booleano (predeterminado: false)​

Callback responseMeta​

Ejemplo​

Próximos pasos​