Aller au contenu principal
Version : 10.x

Aides côté serveur

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 →

Les aides côté serveur vous fournissent un ensemble de fonctions utilitaires pour précharger des requêtes sur le serveur. C'est particulièrement utile pour la génération statique (SSG), mais aussi pour le rendu côté serveur (SSR) si vous choisissez de ne pas utiliser ssr: true.

Le préchargement via ces aides permet de remplir le cache des requêtes côté serveur, évitant ainsi leur récupération initiale côté client.

Deux méthodes d'utilisation​

1. Routeur interne​

Cette méthode s'utilise lorsque vous avez un accès direct à votre routeur tRPC, par exemple dans une application Next.js monolithique.

Les aides permettent à tRPC d'appeler vos procédures directement sur le serveur, sans requête HTTP, similairement aux appels côté serveur. Cela signifie que vous n'aurez pas accès à la requête et la réponse comme habituellement. Veillez à instancier les aides avec un contexte dépourvu de req et res, qui sont normalement fournis via la création de contexte. Nous recommandons d'utiliser le concept de contexte "interne" et "externe" dans ce scénario.

ts
import { createServerSideHelpers } from '@trpc/react-query/server';
import { createContext } from '~/server/context';
import superjson from 'superjson';
const helpers = createServerSideHelpers({
  router: appRouter,
  ctx: await createContext(),
  transformer: superjson, // optional - adds superjson serialization
});
ts
import { createServerSideHelpers } from '@trpc/react-query/server';
import { createContext } from '~/server/context';
import superjson from 'superjson';
const helpers = createServerSideHelpers({
  router: appRouter,
  ctx: await createContext(),
  transformer: superjson, // optional - adds superjson serialization
});

2. Routeur externe​

Cette méthode s'utilise lorsque vous n'avez pas d'accès direct à votre routeur tRPC, par exemple avec une application Next.js et une API autonome hébergées séparément.

ts
import { createTRPCProxyClient } from '@trpc/client';
import { createServerSideHelpers } from '@trpc/react-query/server';
import superjson from 'superjson';
const proxyClient = createTRPCProxyClient<AppRouter>({
  links: [
    httpBatchLink({
      url: 'http://localhost:3000/api/trpc',
    }),
  ],
  transformer: superjson,
});
const helpers = createServerSideHelpers({
  client: proxyClient,
});
ts
import { createTRPCProxyClient } from '@trpc/client';
import { createServerSideHelpers } from '@trpc/react-query/server';
import superjson from 'superjson';
const proxyClient = createTRPCProxyClient<AppRouter>({
  links: [
    httpBatchLink({
      url: 'http://localhost:3000/api/trpc',
    }),
  ],
  transformer: superjson,
});
const helpers = createServerSideHelpers({
  client: proxyClient,
});

Utilisation des aides​

Les méthodes des aides côté serveur renvoient un objet similaire au client tRPC, avec vos routeurs comme clés. Cependant, au lieu de useQuery et useMutation, vous obtenez les fonctions prefetch, fetch, prefetchInfinite et fetchInfinite.

La différence principale entre prefetch et fetch est que fetch agit comme un appel fonctionnel classique en renvoyant le résultat de la requête, tandis que prefetch ne renvoie aucun résultat et ne génère jamais d'erreur - si vous avez besoin de ce comportement, utilisez plutôt fetch. prefetch ajoute simplement la requête au cache, que vous déshydratez ensuite pour l'envoyer au client.

ts
return {
  props: {
    // very important - use `trpcState` as the key
    trpcState: helpers.dehydrate(),
  },
};
ts
return {
  props: {
    // very important - use `trpcState` as the key
    trpcState: helpers.dehydrate(),
  },
};

La règle générale est : utilisez prefetch pour les requêtes dont vous savez qu'elles seront nécessaires côté client, et fetch pour les requêtes dont vous souhaitez exploiter le résultat côté serveur.

Ces fonctions sont toutes des wrappers autour des fonctionnalités de react-query. Consultez leur documentation pour en apprendre davantage en détail.

info

Pour un exemple complet, consultez notre test E2E de génération statique

Exemple avec Next.js​

pages/posts/[id].tsx
tsx
import { createServerSideHelpers } from '@trpc/react-query/server';
import { GetServerSidePropsContext, InferGetServerSidePropsType } from 'next';
import { appRouter } from 'server/routers/_app';
import superjson from 'superjson';
import { trpc } from 'utils/trpc';
export async function getServerSideProps(
  context: GetServerSidePropsContext<{ id: string }>,
) {
  const helpers = createServerSideHelpers({
    router: appRouter,
    ctx: {},
    transformer: superjson,
  });
  const id = context.params?.id as string;
  /*
   * Prefetching the `post.byId` query.
   * `prefetch` does not return the result and never throws - if you need that behavior, use `fetch` instead.
   */
  await helpers.post.byId.prefetch({ id });
  // Make sure to return { props: { trpcState: helpers.dehydrate() } }
  return {
    props: {
      trpcState: helpers.dehydrate(),
      id,
    },
  };
}
export default function PostViewPage(
  props: InferGetServerSidePropsType<typeof getServerSideProps>,
) {
  const { id } = props;
  const postQuery = trpc.post.byId.useQuery({ id });
  if (postQuery.status !== 'success') {
    // won't happen since the query has been prefetched
    return <>Loading...</>;
  }
  const { data } = postQuery;
  return (
    <>
      <h1>{data.title}</h1>
      <em>Created {data.createdAt.toLocaleDateString()}</em>
      <p>{data.text}</p>
      <h2>Raw data:</h2>
      <pre>{JSON.stringify(data, null, 4)}</pre>
    </>
  );
}
pages/posts/[id].tsx
tsx
import { createServerSideHelpers } from '@trpc/react-query/server';
import { GetServerSidePropsContext, InferGetServerSidePropsType } from 'next';
import { appRouter } from 'server/routers/_app';
import superjson from 'superjson';
import { trpc } from 'utils/trpc';
export async function getServerSideProps(
  context: GetServerSidePropsContext<{ id: string }>,
) {
  const helpers = createServerSideHelpers({
    router: appRouter,
    ctx: {},
    transformer: superjson,
  });
  const id = context.params?.id as string;
  /*
   * Prefetching the `post.byId` query.
   * `prefetch` does not return the result and never throws - if you need that behavior, use `fetch` instead.
   */
  await helpers.post.byId.prefetch({ id });
  // Make sure to return { props: { trpcState: helpers.dehydrate() } }
  return {
    props: {
      trpcState: helpers.dehydrate(),
      id,
    },
  };
}
export default function PostViewPage(
  props: InferGetServerSidePropsType<typeof getServerSideProps>,
) {
  const { id } = props;
  const postQuery = trpc.post.byId.useQuery({ id });
  if (postQuery.status !== 'success') {
    // won't happen since the query has been prefetched
    return <>Loading...</>;
  }
  const { data } = postQuery;
  return (
    <>
      <h1>{data.title}</h1>
      <em>Created {data.createdAt.toLocaleDateString()}</em>
      <p>{data.text}</p>
      <h2>Raw data:</h2>
      <pre>{JSON.stringify(data, null, 4)}</pre>
    </>
  );
}