Configuration avec le routeur de pages 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 de pages Next.js. Si vous utilisez le routeur d'application Next.js, consultez plutôt le guide de configuration du routeur d'application.

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 dans l'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

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

yarn

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

pnpm

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

bun

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

deno

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

Agents IA

Si vous utilisez un agent de codage IA, installez les compétences tRPC pour une meilleure génération de code :

bash
npx @tanstack/intent@latest install

bash
npx @tanstack/intent@latest install

L'intégration Next.js est en réalité une combinaison de notre intégration React Query et de quelques 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 d'utilisation du 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/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: () => ({}),
});

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 un ensemble de 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/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,
});

note

createTRPCNext ne fonctionne pas avec le mode d'interopérabilité tRPC-v9. Si vous migrez depuis la v9 en utilisant l'interop, 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 désormais utiliser les hooks React que vous venez de créer 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 qui renvoie un objet configurant les clients tRPC et React Query. Cette fonction reçoit un objet avec une propriété ctx optionnelle (de type NextPageContext) vous donnant accès à l'objet req de Next.js lors du rendu côté serveur. La valeur renvoyée 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.

Callback responseMeta

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 '../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: [
        /* [...] */
      ],
    };
  },
});

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.