Version : 11.x

Configuration avec le routeur Pages de Next.js

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

attention

Ce guide concerne le routeur Pages de Next.js. Si vous utilisez le routeur App de Next.js avec des composants serveur React, consultez la documentation RSC.

Structure de fichiers recommandée

Nous recommandons une structure de fichiers comme celle-ci, bien qu'elle ne soit pas imposée par tRPC. C'est ce que vous verrez dans nos exemples. Le reste de cette page vous guidera à travers le processus d'ajout de tRPC à cette structure.

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
└── [..]

Ajouter tRPC à un projet Next.js existant

1. Installer les dépendances

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

L'intégration Next.js combine en réalité notre Intégration React Query avec des intégrations spécifiques à Next.js.

2. Activer le mode strict

Si vous souhaitez utiliser Zod pour la validation des entrées, assurez-vous d'avoir activé le mode strict dans votre tsconfig.json :

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

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

Si le mode strict est trop contraignant, activez au minimum strictNullChecks :

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

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

3. Créer un routeur tRPC

Initialisez votre backend tRPC dans src/server/trpc.ts en utilisant la fonction initTRPC, puis créez votre premier routeur. Nous allons créer ici un simple routeur et procédure "hello world" - mais pour des informations approfondies sur la création de votre API tRPC, référez-vous à :

le Guide de démarrage rapide et la Documentation backend pour les informations tRPC
la Documentation de l'adaptateur Next.js pour intégrer tRPC dans votre serveur 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/v11/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/v11/server/adapters
export default trpcNext.createNextApiHandler({
  router: appRouter,
  createContext: () => ({}),
});

note

Le backend ci-dessus utilise la structure de fichiers recommandée, mais vous pouvez simplifier en plaçant tout directement dans un gestionnaire d'API si vous préférez.

4. Créer les hooks tRPC

Utilisez la fonction createTRPCNext pour créer des hooks fortement typés à partir de la signature de type de votre 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/v11/ssr
           **/
          url: `${getBaseUrl()}/api/trpc`,
          // You can pass any HTTP headers you wish here
          async headers() {
            return {
              // authorization: getAuthCookie(),
            };
          },
        }),
      ],
    };
  },
  /**
   * @see https://trpc.io/docs/v11/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/v11/ssr
           **/
          url: `${getBaseUrl()}/api/trpc`,
          // You can pass any HTTP headers you wish here
          async headers() {
            return {
              // authorization: getAuthCookie(),
            };
          },
        }),
      ],
    };
  },
  /**
   * @see https://trpc.io/docs/v11/ssr
   **/
  ssr: false,
});

note

createTRPCNext ne fonctionne pas avec le mode d'interopérabilité de tRPC v9. Si vous effectuez une migration depuis la v9 en utilisant ce mode d'interopérabilité, vous devez continuer à utiliser l'ancienne méthode d'initialisation de tRPC.

5. Configurer `_app.tsx`

Enveloppez votre page d'application racine avec le HOC trpc.withTRPC, comme suit :

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. Effectuer une requête API

Vous êtes prêt !

Vous pouvez maintenant utiliser les hooks React créés pour invoquer votre API. Pour plus de détails, consultez l'Intégration 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>
  );
}

Options de `createTRPCNext()`

Callback `config`

L'argument config est une fonction renvoyant un objet configurant les clients tRPC et React Query. Cette fonction reçoit un contexte ctx donnant accès à l'objet req de Next.js entre autres. L'objet retourné peut contenir les propriétés suivantes :

Obligatoire :
links pour personnaliser le flux de données entre le client tRPC et le serveur tRPC. En savoir plus.
Optionnel :
queryClientConfig : un objet de configuration pour le QueryClient de React Query, utilisé en interne par les hooks React de tRPC : Documentation QueryClient
queryClient : une instance QueryClient de React Query
- Remarque : Vous ne pouvez fournir qu'un queryClient OU un queryClientConfig, pas les deux.
transformer : un transformateur appliqué aux charges utiles sortantes. En savoir plus sur les Transformateurs de données
abortOnUnmount : détermine si les requêtes en cours seront annulées lors du démontage du composant. Par défaut false.

`overrides` : (par défaut : `undefined`)

Configure les surcharges des hooks React Query.

`ssr`-booléen (par défaut : `false`)

Détermine si tRPC doit attendre les requêtes lors du rendu côté serveur d'une page. Valeur par défaut false.

`responseMeta`-callback

Permet de définir les en-têtes de requête et le statut HTTP lors du rendu côté serveur.

Exemple

utils/trpc.ts
tsx
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from '../pages/api/trpc/[trpc]';
export const trpc = createTRPCNext<AppRouter>({
  config(config) {
    /* [...] */
  },
});

utils/trpc.ts
tsx
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from '../pages/api/trpc/[trpc]';
export const trpc = createTRPCNext<AppRouter>({
  config(config) {
    /* [...] */
  },
});

Prochaines étapes

Parcourez le reste de la documentation pour en savoir plus sur des sujets comme l'autorisation, les middlewares et la gestion des erreurs.

Vous trouverez également des informations sur les requêtes et les mutations maintenant que vous utilisez @trpc/react-query.

Structure de fichiers recommandée​

Ajouter tRPC à un projet Next.js existant​

1. Installer les dépendances​

2. Activer le mode strict​

3. Créer un routeur tRPC​

4. Créer les hooks tRPC​

5. Configurer _app.tsx​

6. Effectuer une requête API​

Options de createTRPCNext()​

Callback config​

overrides : (par défaut : undefined)​

ssr-booléen (par défaut : false)​

responseMeta-callback​

Exemple​

Prochaines étapes​