Version : 11.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 permettant de précharger des requêtes sur le serveur. Ceci est utile pour la SSG (génération de sites statiques), mais aussi pour la SSR (rendu côté serveur) si vous optez 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 est utilisée lorsque vous avez un accès direct à votre routeur tRPC, par exemple lors du développement d'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 { appRouter } from './server/routers/_app';
import superjson from 'superjson';
 
const helpers = createServerSideHelpers({
  router: appRouter,
  ctx: await createContext(),
  transformer: superjson,
});

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

2. Routeur externe

Cette méthode est utilisée lorsque vous n'avez pas d'accès direct à votre routeur tRPC, par exemple lors du développement d'une application Next.js et d'une API autonome hébergée séparément.

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

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

Utilisation des aides

Les méthodes des aides côté serveur renvoient un objet qui reflète la structure de votre routeur, avec tous 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
// In getServerSideProps / getStaticProps:
const props = {
  // very important - use `trpcState` as the key
  trpcState: helpers.dehydrate(),
};

ts
// In getServerSideProps / getStaticProps:
const 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 des wrappers autour des fonctionnalités de react-query. Consultez leur documentation pour en savoir plus 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 { appRouter } from './server/routers/_app';
import { trpc } from './utils/trpc';
import { GetServerSidePropsContext, InferGetServerSidePropsType } from 'next';
import superjson from 'superjson';
 
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 { appRouter } from './server/routers/_app';
import { trpc } from './utils/trpc';
import { GetServerSidePropsContext, InferGetServerSidePropsType } from 'next';
import superjson from 'superjson';
 
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>
    </>
  );
}

Deux méthodes d'utilisation​

1. Routeur interne​

2. Routeur externe​

Utilisation des aides​

Exemple avec Next.js​

Deux méthodes d'utilisation

1. Routeur interne

2. Routeur externe

Utilisation des aides

Exemple avec Next.js