Bien que tRPC v11 soit prêt pour la production depuis longtemps via le tag @next, nous avons pris l'habitude d'ajouter constamment de nouvelles fonctionnalités sans nous astreindre strictement au versionnage sémantique. Aujourd'hui, nous sommes ravis d'enfin retirer le pansement et d'annoncer la sortie officielle de tRPC v11 !

Depuis notre dernière version majeure en novembre 2022, la communauté tRPC a connu une croissance substantielle :

• Plus de 35 000 étoiles sur GitHub

• Une communauté Discord comptant plus de 5 000 membres

• Plus de 700 000 téléchargements npm hebdomadaires

• Des centaines de contributeurs

• Un écosystème impressionnant d'extensions, d'exemples et de contenus

Avec le lancement de tRPC v11, nous sommes heureux de partager que v11 est déjà utilisé en production par de nombreux projets TypeScript d'envergure, grâce à son évolution stable sur notre canal @next.

Pour les nouveaux projets, vous pouvez démarrer avec une application exemple pour découvrir tRPC v11. Pour les projets encore sur tRPC v10, consultez le guide de migration vers v11.

Vue d'ensemble des changements​

v11 est une version largement rétrocompatible avec v10, mais elle apporte de nombreuses nouvelles fonctionnalités et améliorations. Voici les points forts :

Prise en charge de TanStack Query v5​

La sortie de TanStack Query v5 a nécessité des changements cassants dans l'intégration react-query de tRPC. Disponible assez tôt via le tag @next, elle est désormais officiellement publiée. De nombreux projets ont déjà choisi de mettre à niveau et profitent du support complet de React Suspense ainsi que de nombreuses autres améliorations. Pour migrer votre code client React tRPC, suivez le guide de migration de TanStack Query.

Nouvelle intégration TanStack React Query​

Voir l'article de blog

Prise en charge de FormData / Types de contenu non-JSON​

L'une de nos fonctionnalités les plus demandées est la possibilité d'envoyer et de recevoir plus que de simples données JSON. Avec tRPC v11, vous pouvez désormais échanger des données dans divers types de contenu non-JSON, FormData, et types binaires comme Blob, File et Uint8Array. Un exemple d'utilisation est disponible ici.

ts
import { publicProcedure, router } from './trpc';
import { octetInputParser } from '@trpc/server/http';
import { z } from 'zod';
 
const appRouter = router({
  formData: publicProcedure
    .input(z.instanceof(FormData))
    .mutation(async ({ input }) => {
                        
(parameter) input: FormData
    }),
  file: publicProcedure
    .input(octetInputParser)
    .mutation(async ({ input }) => {
                        
(parameter) input: ReadableStream<any>
    }),
});
Copy

ts
import { publicProcedure, router } from './trpc';
import { octetInputParser } from '@trpc/server/http';
import { z } from 'zod';
 
const appRouter = router({
  formData: publicProcedure
    .input(z.instanceof(FormData))
    .mutation(async ({ input }) => {
                        
(parameter) input: FormData
    }),
  file: publicProcedure
    .input(octetInputParser)
    .mutation(async ({ input }) => {
                        
(parameter) input: ReadableStream<any>
    }),
});
Copy

Composants Serveur React / Routeur d'application Next.js​

Bien que vous ayez pu utiliser tRPC avec le routeur d'application de Next.js depuis le premier jour, soit :

• via une approche centrée serveur avec async/await via createCaller ou createTRPCClient,

• soit une approche centrée client utilisant l'intégration React Query et les hooks côté client,

La passerelle entre les deux approches présentait quelques aspérités. Les modèles de revalidation devenaient hybrides lorsqu'il fallait gérer différents modes de récupération de données, ce qui entraînait une expérience développeur inférieure aux standards habituels de tRPC.

Pour résoudre cela, nous avons amélioré la prise en charge des React Server Components (RSC) et ajouté des helpers de préchargement pour exploiter plus facilement la puissance des RSC exécutés exclusivement côté serveur, tout en bénéficiant du cache dynamique de React Query côté client. Vous pouvez désormais démarrer l'exécution d'une procédure côté serveur dans un RSC, récupérer la promesse en attente côté client, et hydrater automatiquement le cache React Query. Cela permet de créer des applications hautement dynamiques sans subir les goulots d'étranglement serveur-client. Consultez notre documentation sur les Server Components.

En complément de ces nouveaux modèles de préchargement, nous avons ajouté une prise en charge expérimentale des fonctions serveur. Lisez-en plus dans notre article de blog. Nous prévoyons d'itérer sur cette fonctionnalité à mesure que les fonctions serveur deviendront un modèle établi dans l'écosystème.

Nous avons également collaboré avec l'équipe TanStack pour concevoir les APIs de leurs fonctions serveur. Notre objectif est d'extraire des parties du puissant système de middleware de tRPC dans un package séparé, utilisable dans tout l'écosystème.

Streaming des réponses depuis les queries et mutations​

Nous avons introduit le httpBatchStreamLink, qui permet de streamer les réponses des queries. C'est particulièrement utile pour les jeux de données volumineux ou lorsque vous devez traiter des données en temps réel et les envoyer progressivement au frontend. Ce n'est pas un remplacement des subscriptions, mais un outil supplémentaire à votre disposition.

ts
// @filename: server.ts
import { publicProcedure, router } from './trpc';
 
const appRouter = router({
  examples: {
    iterable: publicProcedure.query(async function* () {
      let i = 0;
      while (true) {
        await new Promise((resolve) => setTimeout(resolve, 500));
        yield i++;
      }
    }),
  },
});
 
export type AppRouter = typeof appRouter;
 
 
// @filename: client.ts
import { createTRPCClient, httpBatchStreamLink } from '@trpc/client';
import type { AppRouter } from './server';
 
const trpc = createTRPCClient<AppRouter>({
  links: [
    httpBatchStreamLink({
      url: 'http://localhost:3000',
    }),
  ],
});
const iterable = await trpc.examples.iterable.query();
         
const iterable: AsyncIterable<number, never, unknown>
 
for await (const value of iterable) {
  console.log('Iterable:', value);
                            
const value: number
}
Copy

ts
// @filename: server.ts
import { publicProcedure, router } from './trpc';
 
const appRouter = router({
  examples: {
    iterable: publicProcedure.query(async function* () {
      let i = 0;
      while (true) {
        await new Promise((resolve) => setTimeout(resolve, 500));
        yield i++;
      }
    }),
  },
});
 
export type AppRouter = typeof appRouter;
 
 
// @filename: client.ts
import { createTRPCClient, httpBatchStreamLink } from '@trpc/client';
import type { AppRouter } from './server';
 
const trpc = createTRPCClient<AppRouter>({
  links: [
    httpBatchStreamLink({
      url: 'http://localhost:3000',
    }),
  ],
});
const iterable = await trpc.examples.iterable.query();
         
const iterable: AsyncIterable<number, never, unknown>
 
for await (const value of iterable) {
  console.log('Iterable:', value);
                            
const value: number
}
Copy

Syntaxe raccourcie pour les définitions de routeur​

Nous avons introduit une nouvelle syntaxe raccourcie pour définir votre router afin de simplifier la définition de vos routes. Documentation

ts
const appRouter = router({
  // Shorthand plain object for creating a sub-router
  nested1: {
    proc: publicProcedure.query(() => '...'),
  },
  // Equivalent of:
  nested2: router({
    proc: publicProcedure.query(() => '...'),
  }),
});
Copy

ts
const appRouter = router({
  // Shorthand plain object for creating a sub-router
  nested1: {
    proc: publicProcedure.query(() => '...'),
  },
  // Equivalent of:
  nested2: router({
    proc: publicProcedure.query(() => '...'),
  }),
});
Copy

Abonnements : Server-Sent Events et autres améliorations​

• tRPC v11 introduit un nouveau mode de gestion des abonnements via les Server-Sent Events (SSE). Une solution idéale pour les mises à jour temps réel sans la complexité des WebSockets. Nous recommandons désormais cette approche en priorité.

• Nous avons ajouté la prise en charge des générateurs JavaScript dans les abonnements. Cela permet d'écrire des gestionnaires d'abonnement complexes produisant plusieurs valeurs dans le temps, avec un nettoyage automatique des effets de bord, dans un style parfaitement adapté à JavaScript.

• Les abonnements prennent désormais en charge les validateurs de sortie, améliorant la type-safety de vos gestionnaires.

Adieu le mode .interop() de la v9​

Dans tRPC v10, nous avions introduit le mode .interop() pour faciliter la migration depuis la v9. Avec tRPC v11, nous avons supprimé le mode .interop(). Si vous utilisez encore le mode .interop(), vous pouvez utiliser le guide de migration v10 pour achever votre transition vers les APIs utilisées par tRPC aujourd'hui.

Migration vers la v11​

Si vous utilisez actuellement tRPC v10, suivez le guide de migration pour passer à la v11. Ce guide couvre toutes les breaking changes et nouvelles fonctionnalités.

Merci !​

De la part de toute l'équipe core de tRPC, merci d'utiliser et de soutenir notre bibliothèque.

slug: typescript-performance-lessons title: Leçons de performance TypeScript lors du refactoring pour la v10 authors: [sachinraja]​

• Suivez @trpcio sur Twitter.

• Rejoignez notre communauté Discord

• Essayez tRPC dans votre navigateur

Nous sommes ravis d'annoncer que la nouvelle intégration TanStack React Query pour tRPC est désormais disponible dans la version next de tRPC. Comparée à notre intégration classique de React Query, elle est plus simple et plus fidèle à l'esprit de TanStack Query. Elle utilise directement les interfaces QueryOptions et MutationOptions natives de TanStack React Query, plutôt que d'encapsuler useQuery et useMutation avec notre propre client.

greeting.tsx
tsx
import { useQuery } from '@tanstack/react-query';
import { useTRPC } from './trpc';
 
export function Greeting() {
  const trpc = useTRPC();
 
  const greetingQuery = useQuery(trpc.greeting.queryOptions({ name: 'Jerry' }));
 
  // greetingQuery.data === 'Hello Jerry'
 
  return null;
}
Copy

greeting.tsx
tsx
import { useQuery } from '@tanstack/react-query';
import { useTRPC } from './trpc';
 
export function Greeting() {
  const trpc = useTRPC();
 
  const greetingQuery = useQuery(trpc.greeting.queryOptions({ name: 'Jerry' }));
 
  // greetingQuery.data === 'Hello Jerry'
 
  return null;
}
Copy

Avec ce nouveau client, nous supprimons une couche d'abstraction souvent source de confusion pour les nouveaux utilisateurs. Nous proposons plutôt une manière plus directe de travailler avec TanStack React Query, qui semblera immédiatement familière à ceux qui suivent la documentation officielle de TanStack. Cela signifie également que nous avons besoin de moins de documentation tRPC pour l'expliquer, bien que nous ayons bien sûr une documentation pour démarrer.

Pourquoi ce changement ?​

Vous pouvez consulter notre RFC originale concernant ce changement ici pour plus de détails. Voici nos principales raisons :

• Simplicité : Le nouveau client est plus simple et plus proche de TanStack Query, fournissant des factories pour les interfaces courantes comme QueryKeys, QueryOptions et MutationOptions. Cela réduit la courbe d'apprentissage car vous pouvez suivre la documentation officielle de TanStack Query

• Familiarité : Le nouveau client sera plus naturel pour ceux qui utilisent déjà TanStack Query. Utiliser TanStack Query pour d'autres parties de votre application ne vous forcera pas à adopter une syntaxe alternative pour tRPC

• React : Notre intégration classique de React Query enfreint en réalité les règles des hooks ; elle ne peut pas être lintée correctement et encourage certains motifs qui casseront sous le React Compiler, comme passer des hooks en tant que props. À cet égard, le nouveau client est plus idiomatique pour React

• Maintenabilité : Un défi rencontré avec notre versioning était de maintenir tRPC synchronisé avec les changements de TanStack Query, notamment les nouvelles fonctionnalités ajoutées périodiquement à QueryClient. En utilisant la petite surface d'interface native, nous supportons React Query plus facilement tout en suivant les bonnes pratiques recommandées par les mainteneurs de TanStack

• Retours utilisateurs : Comme mentionné, le client classique est souvent source de difficultés pour les nouveaux utilisateurs. Mais les retours sur la RFC pour ce nouveau client ont été extrêmement positifs, avec une majorité d'utilisateurs enthousiastes à l'idée de l'utiliser. Bien sûr, tout le monde n'est pas encore convaincu, donc nous maintiendrons le client classique

Qu'advient-il de l'intégration classique tRPC React Query ?​

Elle ne disparaîtra pas de sitôt ! Nous nous engageons à la maintenir longtemps, mais elle ne recevra pas de nouvelles fonctionnalités majeures et sera considérée comme stable.

Nous recommandons toujours aux nouveaux projets de démarrer avec la nouvelle intégration TanStack React Query, et aux projets existants d'envisager une migration progressive.

Comment migrer ?​

Bien que le client classique soit maintenu pour longtemps, nous recommandons aux nouveaux projets de démarrer avec le nouveau client et aux projets actifs d'envisager une migration progressive.

Les deux clients sont compatibles entre eux et peuvent coexister dans la même application, vous permettant de migrer à votre rythme. Nous travaillons également sur un codemod pour lequel nous adorerions des contributions communautaires. Nous remercions @reaper pour ses contributions actuelles au codemod !

👉 Lire la documentation de migration

Le pattern de builder pour créer des procédures introduit dans tRPC v10 a été massivement apprécié par la communauté, et de nombreuses bibliothèques ont adopté des patterns similaires. On voit même émerger le terme tRPC like XYZ comme preuve de la popularité croissante de ce pattern. Récemment, j'ai d'ailleurs vu quelqu'un se demander s'il était possible d'écrire des applications CLI avec une API similaire à tRPC. Note au passage : vous pouvez même utiliser tRPC directement pour cela. Mais ce n'est pas le sujet du jour. Nous allons plutôt parler d'utiliser tRPC avec les Server Actions de Next.js.

Qu'est-ce qu'une Server Action ?​

Au cas où vous seriez passé à côté des dernières fonctionnalités de React et Next.js, les Server Actions permettent d'écrire des fonctions classiques exécutées côté serveur, de les importer côté client et de les appeler comme si c'étaient des fonctions ordinaires. Vous pourriez penser que cela ressemble à tRPC - et vous auriez raison. Selon Dan Abramov, les Server Actions sont l'équivalent de tRPC en tant que fonctionnalité de bundler :

Et c'est tout à fait exact. Les Server Actions sont similaires à tRPC : au final, ce sont toutes deux des RPC. Toutes deux vous permettent d'écrire des fonctions backend et de les appeler avec une typage fort côté frontend, sans vous soucier de la couche réseau.

Alors où intervient tRPC ? Pourquoi aurais-je besoin à la fois de tRPC et des Server Actions ? Les Server Actions sont une primitive, et comme toute primitive, elles sont assez basiques et manquent d'aspects fondamentaux pour construire des API. Pour tout endpoint exposé sur le réseau, vous devez valider et autoriser les requêtes pour éviter les utilisations malveillantes. Comme mentionné précédemment, l'API de tRPC est appréciée par la communauté. Ne serait-il pas idéal d'utiliser tRPC pour définir des Server Actions et bénéficier de ses fonctionnalités intégrées comme la validation des entrées, l'authentification/autorisation via middlewares, la validation des sorties, les transformers de données, etc. ? Je pense que oui, alors creusons cela.

Définir des Server Actions avec tRPC​

npm install @trpc/serverCopier

yarn add @trpc/serverCopier

pnpm add @trpc/serverCopier

bun add @trpc/serverCopier

deno add npm:@trpc/serverCopier

Commençons par initialiser tRPC et définir notre procédure de base pour les Server Actions. Nous utiliserons la méthode experimental_caller du builder de procédures, une nouvelle méthode permettant de personnaliser l'appel de la procédure lorsqu'elle est invoquée comme fonction. Nous utiliserons aussi l'adaptateur experimental_nextAppDirCaller pour la compatibilité avec Next.js. Cet adaptateur gérera les cas où la Server Action est wrappée dans useActionState côté client, ce qui modifie la signature d'appel de la Server Action.

Nous utiliserons également une propriété span comme métadonnée, puisqu'il n'y a pas de chemin classique comme avec un routeur (user.byId par exemple). Vous pouvez utiliser la propriété span pour différencier les procédures, par exemple pour du logging ou de l'observabilité.

server/trpc.ts
ts
import { initTRPC, TRPCError } from '@trpc/server';
import { experimental_nextAppDirCaller } from '@trpc/server/adapters/next-app-dir';
 
interface Meta {
  span: string;
}
 
export const t = initTRPC.meta<Meta>().create();
 
const serverActionProcedure = t.procedure.experimental_caller(
  experimental_nextAppDirCaller({
    pathExtractor: ({ meta }) => (meta as Meta).span,
  }),
);
Copy

server/trpc.ts
ts
import { initTRPC, TRPCError } from '@trpc/server';
import { experimental_nextAppDirCaller } from '@trpc/server/adapters/next-app-dir';
 
interface Meta {
  span: string;
}
 
export const t = initTRPC.meta<Meta>().create();
 
const serverActionProcedure = t.procedure.experimental_caller(
  experimental_nextAppDirCaller({
    pathExtractor: ({ meta }) => (meta as Meta).span,
  }),
);
Copy

Nous allons maintenant ajouter du contexte. Comme nous n'hébergerons pas de routeur via un adaptateur HTTP classique, nous n'aurons pas de contexte injecté via la méthode createContext de l'adaptateur. À la place, nous utiliserons un middleware pour injecter notre contexte. Dans cet exemple, récupérons l'utilisateur courant depuis la session et injectons-le dans le contexte.

server/trpc.ts
ts
import { initTRPC, TRPCError } from '@trpc/server';
import { experimental_nextAppDirCaller } from '@trpc/server/adapters/next-app-dir';
import { currentUser } from './auth';
 
interface Meta {
  span: string;
}
 
export const t = initTRPC.meta<Meta>().create();
 
export const serverActionProcedure = t.procedure
  .experimental_caller(
    experimental_nextAppDirCaller({
      pathExtractor: ({ meta }) => (meta as Meta).span,
    }),
  )
  .use(async (opts) => {
    // Inject user into context
    const user = await currentUser();
    return opts.next({ ctx: { user } });
  });
Copy

server/trpc.ts
ts
import { initTRPC, TRPCError } from '@trpc/server';
import { experimental_nextAppDirCaller } from '@trpc/server/adapters/next-app-dir';
import { currentUser } from './auth';
 
interface Meta {
  span: string;
}
 
export const t = initTRPC.meta<Meta>().create();
 
export const serverActionProcedure = t.procedure
  .experimental_caller(
    experimental_nextAppDirCaller({
      pathExtractor: ({ meta }) => (meta as Meta).span,
    }),
  )
  .use(async (opts) => {
    // Inject user into context
    const user = await currentUser();
    return opts.next({ ctx: { user } });
  });
Copy

Enfin, nous allons créer une procédure protectedAction qui protégera toute action des utilisateurs non authentifiés. Si vous avez déjà un middleware qui fait cela, vous pouvez l'utiliser. Pour cet exemple, je vais en définir un directement.

server/trpc.ts
ts
import { initTRPC, TRPCError } from '@trpc/server';
import { experimental_nextAppDirCaller } from '@trpc/server/adapters/next-app-dir';
import { currentUser } from './auth';
 
interface Meta {
  span: string;
}
 
export const t = initTRPC.meta<Meta>().create();
 
export const serverActionProcedure = t.procedure
  .experimental_caller(
    experimental_nextAppDirCaller({
      pathExtractor: ({ meta }) => (meta as Meta).span,
    }),
  )
  .use(async (opts) => {
    // Inject user into context
    const user = await currentUser();
           
const user: User | null
    return opts.next({ ctx: { user } });
  });
 
export const protectedAction = serverActionProcedure.use((opts) => {
  if (!opts.ctx.user) {
    throw new TRPCError({
      code: 'UNAUTHORIZED',
    });
  }
 
  return opts.next({
    ctx: {
      ...opts.ctx,
      user: opts.ctx.user, // <-- ensures type is non-nullable
       
(property) user: User
    },
  });
});
Copy

server/trpc.ts
ts
import { initTRPC, TRPCError } from '@trpc/server';
import { experimental_nextAppDirCaller } from '@trpc/server/adapters/next-app-dir';
import { currentUser } from './auth';
 
interface Meta {
  span: string;
}
 
export const t = initTRPC.meta<Meta>().create();
 
export const serverActionProcedure = t.procedure
  .experimental_caller(
    experimental_nextAppDirCaller({
      pathExtractor: ({ meta }) => (meta as Meta).span,
    }),
  )
  .use(async (opts) => {
    // Inject user into context
    const user = await currentUser();
           
const user: User | null
    return opts.next({ ctx: { user } });
  });
 
export const protectedAction = serverActionProcedure.use((opts) => {
  if (!opts.ctx.user) {
    throw new TRPCError({
      code: 'UNAUTHORIZED',
    });
  }
 
  return opts.next({
    ctx: {
      ...opts.ctx,
      user: opts.ctx.user, // <-- ensures type is non-nullable
       
(property) user: User
    },
  });
});
Copy

Très bien, écrivons une véritable Server Action. Créez un fichier _actions.ts, décorez-le avec la directive "use server", et définissez votre action.

app/_actions.ts
ts
'use server';
 
import { z } from 'zod';
import { protectedAction } from '../server/trpc';
 
export const createPost = protectedAction
  .input(
    z.object({
      title: z.string(),
    }),
  )
  .mutation(async (opts) => {
    // Do something with the input
  });
 
// Since we're using the `experimental_caller`,
// our procedure is now just an ordinary function:
createPost;
    
const createPost: (input: {
    title: string;
}) => Promise<void>
Copy

app/_actions.ts
ts
'use server';
 
import { z } from 'zod';
import { protectedAction } from '../server/trpc';
 
export const createPost = protectedAction
  .input(
    z.object({
      title: z.string(),
    }),
  )
  .mutation(async (opts) => {
    // Do something with the input
  });
 
// Since we're using the `experimental_caller`,
// our procedure is now just an ordinary function:
createPost;
    
const createPost: (input: {
    title: string;
}) => Promise<void>
Copy

Wow, c'est aussi simple de définir une Server Action protégée contre les utilisateurs non authentifiés, avec validation des entrées pour prévenir des attaques comme les injections SQL. Importons maintenant cette fonction côté client et appelons-la.

app/post-form.tsx
tsx
'use client';
import { createPost } from './_actions';
export function PostForm() {
  return (
    <form
      // Use `action` to make form progressively enhanced
      action={createPost}
      // `Using `onSubmit` allows building rich interactive
      // forms once JavaScript has loaded
      onSubmit={async (e) => {
        e.preventDefault();
        const title = new FormData(e.currentTarget).get('title') as string;
        // Maybe show loading toast, etc etc. Endless possibilities
        await createPost({ title });
      }}
    >
      <input type="text" name="title" />
      <button type="submit">Create Post</button>
    </form>
  );
}
Copy

app/post-form.tsx
tsx
'use client';
import { createPost } from './_actions';
export function PostForm() {
  return (
    <form
      // Use `action` to make form progressively enhanced
      action={createPost}
      // `Using `onSubmit` allows building rich interactive
      // forms once JavaScript has loaded
      onSubmit={async (e) => {
        e.preventDefault();
        const title = new FormData(e.currentTarget).get('title') as string;
        // Maybe show loading toast, etc etc. Endless possibilities
        await createPost({ title });
      }}
    >
      <input type="text" name="title" />
      <button type="submit">Create Post</button>
    </form>
  );
}
Copy

Aller plus loin​

En utilisant les builders de tRPC et sa manière composable de définir des procédures réutilisables, nous pouvons facilement créer des Server Actions plus complexes. Voici quelques exemples :

Observabilité​

Vous pouvez utiliser le plugin trpc de @baselime/node-opentelemtry pour ajouter de l'observabilité en quelques lignes de code :

diff
--- server/trpc.ts
+++ server/trpc.ts
+ import { tracing } from '@baselime/node-opentelemetry/trpc';
  export const serverActionProcedure = t.procedure
    .experimental_caller(
      experimental_nextAppDirCaller({
        pathExtractor: (meta: Meta) => meta.span,
      }),
    )
    .use(async (opts) => {
      // Inject user into context
      const user = await currentUser();
      return opts.next({ ctx: { user } });
    })
+  .use(tracing());
--- app/_actions.ts
+++ app/_actions.ts
  export const createPost = protectedAction
+   .meta({ span: 'create-post' })
    .input(
      z.object({
        title: z.string(),
      }),
    )
    .mutation(async (opts) => {
      // Do something with the input
    });
Copy

diff
--- server/trpc.ts
+++ server/trpc.ts
+ import { tracing } from '@baselime/node-opentelemetry/trpc';
  export const serverActionProcedure = t.procedure
    .experimental_caller(
      experimental_nextAppDirCaller({
        pathExtractor: (meta: Meta) => meta.span,
      }),
    )
    .use(async (opts) => {
      // Inject user into context
      const user = await currentUser();
      return opts.next({ ctx: { user } });
    })
+  .use(tracing());
--- app/_actions.ts
+++ app/_actions.ts
  export const createPost = protectedAction
+   .meta({ span: 'create-post' })
    .input(
      z.object({
        title: z.string(),
      }),
    )
    .mutation(async (opts) => {
      // Do something with the input
    });
Copy

Consultez l'intégration Baselime pour tRPC pour plus d'informations. Des patterns similaires devraient fonctionner quelle que soit votre plateforme d'observabilité.

Limitation de débit (Rate Limiting)​

Vous pouvez utiliser un service comme Unkey pour limiter le débit de vos Server Actions. Voici un exemple d'action protégée utilisant Unkey pour limiter le nombre de requêtes par utilisateur :

server/trpc.ts
ts
import { Ratelimit } from '@unkey/ratelimit';
 
export const rateLimitedAction = protectedAction.use(async (opts) => {
  const unkey = new Ratelimit({
    rootKey: process.env.UNKEY_ROOT_KEY!,
    async: true,
    duration: '10s',
    limit: 5,
    namespace: `trpc_${opts.path}`,
  });
 
  const ratelimit = await unkey.limit(opts.ctx.user.id);
  if (!ratelimit.success) {
    throw new TRPCError({
      code: 'TOO_MANY_REQUESTS',
      message: JSON.stringify(ratelimit),
    });
  }
 
  return opts.next();
});
Copy

server/trpc.ts
ts
import { Ratelimit } from '@unkey/ratelimit';
 
export const rateLimitedAction = protectedAction.use(async (opts) => {
  const unkey = new Ratelimit({
    rootKey: process.env.UNKEY_ROOT_KEY!,
    async: true,
    duration: '10s',
    limit: 5,
    namespace: `trpc_${opts.path}`,
  });
 
  const ratelimit = await unkey.limit(opts.ctx.user.id);
  if (!ratelimit.success) {
    throw new TRPCError({
      code: 'TOO_MANY_REQUESTS',
      message: JSON.stringify(ratelimit),
    });
  }
 
  return opts.next();
});
Copy

app/_actions.ts
ts
'use server';
 
import { z } from 'zod';
import { rateLimitedAction } from '../server/trpc';
 
export const commentOnPost = rateLimitedAction
  .input(
    z.object({
      postId: z.string(),
      content: z.string(),
    }),
  )
  .mutation(async (opts) => {
    console.log(
      `${opts.ctx.user.name} commented on ${opts.input.postId} saying ${opts.input.content}`,
    );
  });
Copy

app/_actions.ts
ts
'use server';
 
import { z } from 'zod';
import { rateLimitedAction } from '../server/trpc';
 
export const commentOnPost = rateLimitedAction
  .input(
    z.object({
      postId: z.string(),
      content: z.string(),
    }),
  )
  .mutation(async (opts) => {
    console.log(
      `${opts.ctx.user.name} commented on ${opts.input.postId} saying ${opts.input.content}`,
    );
  });
Copy

Lisez-en plus sur la limitation de débit des procédures tRPC dans cet article de l'équipe Unkey.

Les possibilités sont infinies, et je parie que vous avez déjà plein d'utilitaires middleware sympas dans vos applications tRPC actuelles. Sinon, vous en trouverez sûrement sur npm que vous pouvez npm install !

Pour conclure​

Les Server Actions ne sont en aucun cas une solution miracle. Pour les données plus dynamiques, vous voudrez peut-être conserver vos données dans le cache React Query côté client, et effectuer les mutations via useMutation. C'est tout à fait valable. Ces nouvelles primitives permettent aussi une adoption progressive, vous pouvez donc migrer des procédures individuelles de votre API tRPC existante vers des Server Actions là où cela a du sens. Pas besoin de tout réécrire.

En définissant vos Server Actions avec tRPC, vous pouvez réutiliser une grande partie de la logique actuelle et choisir où exposer la mutation : en tant que Server Action ou mutation traditionnelle. En tant que développeur, vous avez le pouvoir de choisir les patterns qui conviennent le mieux à votre application. Si vous n'utilisez pas encore tRPC, des packages comme next-safe-action et zsa permettent de définir des Server Actions typesafe avec validation des entrées.

Pour voir une application utilisant ce pattern, consultez Trellix tRPC, une app que j'ai récemment créée avec ces nouvelles primitives.

Qu'en pensez-vous ? Nous voulons votre feedback​

Alors, qu'en pensez-vous ? Dites-le nous sur Github et aidez-nous à peaufiner ces primitives pour les stabiliser.

Il reste du travail, notamment sur la gestion des erreurs. Next.js préconise de retourner les erreurs, et nous aimerions rendre cela aussi typesafe que possible. Voyez cette PR en cours par Alex pour un aperçu des travaux en cours.

En attendant, bon code !

Vous êtes-vous déjà demandé comment fonctionne tRPC ? Peut-être souhaitez-vous contribuer au projet mais les rouages internes vous effraient ? L'objectif de cet article est de vous familiariser avec le fonctionnement interne de tRPC en écrivant un client minimal qui couvre les grandes parties de son fonctionnement.

Aperçu​

Supposons que nous ayons un routeur tRPC simple avec trois procédures comme ceci :

ts
type Post = { id: string; title: string };
const posts: Post[] = [];
 
const appRouter = router({
  post: router({
    byId: publicProcedure
      .input(z.object({ id: z.string() }))
      .query(({ input }) => {
        const post = posts.find((p) => p.id === input.id);
        if (!post) throw new TRPCError({ code: "NOT_FOUND" });
        return post;
      }),
    byTitle: publicProcedure
      .input(z.object({ title: z.string() }))
      .query(({ input }) => {
        const post = posts.find((p) => p.title === input.title);
        if (!post) throw new TRPCError({ code: "NOT_FOUND" });
        return post;
      }),
    create: publicProcedure
      .input(z.object({ title: z.string() }))
      .mutation(({ input }) => {
        const post = { id: uuid(), ...input };
        posts.push(post);
        return post;
      }),
  }),
});
Copy

ts
type Post = { id: string; title: string };
const posts: Post[] = [];
 
const appRouter = router({
  post: router({
    byId: publicProcedure
      .input(z.object({ id: z.string() }))
      .query(({ input }) => {
        const post = posts.find((p) => p.id === input.id);
        if (!post) throw new TRPCError({ code: "NOT_FOUND" });
        return post;
      }),
    byTitle: publicProcedure
      .input(z.object({ title: z.string() }))
      .query(({ input }) => {
        const post = posts.find((p) => p.title === input.title);
        if (!post) throw new TRPCError({ code: "NOT_FOUND" });
        return post;
      }),
    create: publicProcedure
      .input(z.object({ title: z.string() }))
      .mutation(({ input }) => {
        const post = { id: uuid(), ...input };
        posts.push(post);
        return post;
      }),
  }),
});
Copy

L'objectif de notre client est de reproduire cette structure d'objet côté client pour pouvoir appeler des procédures ainsi :

ts
const post1 = await client.post.byId.query({ id: '123' });
const post2 = await client.post.byTitle.query({ title: 'Hello world' });
const newPost = await client.post.create.mutate({ title: 'Foo' });
Copy

ts
const post1 = await client.post.byId.query({ id: '123' });
const post2 = await client.post.byTitle.query({ title: 'Hello world' });
const newPost = await client.post.create.mutate({ title: 'Foo' });
Copy

Pour y parvenir, tRPC utilise une combinaison d'objets Proxy et d'un peu de magie TypeScript pour enrichir la structure avec les méthodes .query et .mutate - ce qui signifie que nous vous MENTONS en réalité sur ce que vous faites (nous y reviendrons) pour offrir une excellente expérience développeur !

Globalement, nous voulons mapper post.byId.query() vers une requête GET sur notre serveur, et post.create.mutate() vers une requête POST, avec une propagation complète des types du back vers le front. Alors, comment procéder ?

Implémentation d'un petit client tRPC​

🧙‍♀️ La magie TypeScript​

Commençons par la magie amusante de TypeScript pour débloquer l'autocomplétion géniale et la sécurité de type qu'on adore dans tRPC.

Nous utiliserons des types récursifs pour inférer des structures de routeur arbitrairement profondes. De plus, nous voulons que nos procédures post.byId et post.create aient respectivement les méthodes .query et .mutate - dans tRPC, on appelle cela "décorer" les procédures. Dans @trpc/server, des helpers d'inférence déduisent les types d'entrée/sortie des procédures avec ces méthodes résolues, que nous exploiterons pour typer ces fonctions. Alors, codons !

Voyons ce que nous voulons accomplir pour fournir l'autocomplétion des chemins et l'inférence des types d'entrée/sortie des procédures :

• Sur un routeur, nous devons accéder à ses sous-routeurs et procédures. (nous y reviendrons)

• Sur une procédure query, nous devons pouvoir appeler .query

• Sur une procédure mutation, nous devons pouvoir appeler .mutate

• Pour tout autre accès, nous voulons une erreur de type indiquant l'absence de la procédure côté serveur

Créons donc un type qui implémente ce comportement :

ts
type DecorateProcedure<TProcedure> = TProcedure extends AnyTRPCQueryProcedure
  ? {
      query: Resolver<TProcedure>;
    }
  : TProcedure extends AnyTRPCMutationProcedure
  ? {
      mutate: Resolver<TProcedure>;
    }
  : never;
Copy

ts
type DecorateProcedure<TProcedure> = TProcedure extends AnyTRPCQueryProcedure
  ? {
      query: Resolver<TProcedure>;
    }
  : TProcedure extends AnyTRPCMutationProcedure
  ? {
      mutate: Resolver<TProcedure>;
    }
  : never;
Copy

Nous utiliserons des helpers d'inférence internes de tRPC pour définir le type Resolver en déduisant les types d'entrée/sortie des procédures.

ts
import type {
  AnyTRPCProcedure,
  inferProcedureInput,
  inferProcedureOutput,
  AnyTRPCQueryProcedure,
  AnyTRPCMutationProcedure
} from '@trpc/server';
 
 
 
type Resolver<TProcedure extends AnyTRPCProcedure> = (
  input: inferProcedureInput<TProcedure>,
) => Promise<inferProcedureOutput<TProcedure>>;
 
Copy

ts
import type {
  AnyTRPCProcedure,
  inferProcedureInput,
  inferProcedureOutput,
  AnyTRPCQueryProcedure,
  AnyTRPCMutationProcedure
} from '@trpc/server';
 
 
 
type Resolver<TProcedure extends AnyTRPCProcedure> = (
  input: inferProcedureInput<TProcedure>,
) => Promise<inferProcedureOutput<TProcedure>>;
 
Copy

Testons cela sur notre procédure post.byId :

ts
type PostById = Resolver<AppRouter['post']['byId']>;
        
type PostById = (input: {
    id: string;
}) => Promise<Post>
Copy

ts
type PostById = Resolver<AppRouter['post']['byId']>;
        
type PostById = (input: {
    id: string;
}) => Promise<Post>
Copy

Parfait ! Nous pouvons maintenant appeler .query sur notre procédure et obtenir les types d'entrée/sortie correctement déduits.

Enfin, créons un type qui parcourt récursivement le routeur et décore toutes les procédures rencontrées :

ts
import type { TRPCRouterRecord } from "@trpc/server";
import type { AnyTRPCRouter } from "@trpc/server";
 
type DecorateRouterRecord<TRecord extends TRPCRouterRecord> = {
  [TKey in keyof TRecord]: TRecord[TKey] extends infer $Value
    ? $Value extends TRPCRouterRecord
      ? DecorateRouterRecord<$Value>
      : $Value extends AnyTRPCProcedure
      ? DecorateProcedure<$Value>
      : never
    : never;
};
Copy

ts
import type { TRPCRouterRecord } from "@trpc/server";
import type { AnyTRPCRouter } from "@trpc/server";
 
type DecorateRouterRecord<TRecord extends TRPCRouterRecord> = {
  [TKey in keyof TRecord]: TRecord[TKey] extends infer $Value
    ? $Value extends TRPCRouterRecord
      ? DecorateRouterRecord<$Value>
      : $Value extends AnyTRPCProcedure
      ? DecorateProcedure<$Value>
      : never
    : never;
};
Copy

Décortiquons un peu ce type :

1. Nous passons un TRPCRouterRecord comme générique, qui représente l'ensemble des procédures et sous-routeurs d'un routeur tRPC.

2. Nous itérons sur les clés de l'enregistrement, qui sont les noms des procédures ou routeurs, et effectuons les actions suivantes :

   • Si la clé correspond à un routeur, nous appelons récursivement le type sur l'enregistrement des procédures de ce routeur, ce qui décorera toutes les procédures de ce routeur. Cela fournira l'autocomplétion lors de la navigation dans le chemin.
   • Si la clé correspond à une procédure, nous la décorons en utilisant le type DecorateProcedure créé précédemment.
   • Si la clé ne correspond ni à une procédure ni à un routeur, nous assignons le type never, ce qui équivaut à dire "cette clé n'existe pas" et générera une erreur de type si on tente d'y accéder.

🤯 Le remaniement par Proxy​

Maintenant que nos types sont configurés, nous devons implémenter la fonctionnalité qui enrichira la définition du routeur côté client pour pouvoir invoquer les procédures comme des fonctions normales.

Nous allons d'abord créer une fonction utilitaire pour générer des proxies récursifs - createRecursiveProxy :

ts
interface ProxyCallbackOptions {
  path: readonly string[];
  args: readonly unknown[];
}
 
type ProxyCallback = (opts: ProxyCallbackOptions) => unknown;
 
function createRecursiveProxy(callback: ProxyCallback, path: readonly string[]) {
  const proxy: unknown = new Proxy(
    () => {
      // dummy no-op function since we don't have any
      // client-side target we want to remap to
    },
    {
      get(_obj, key) {
        if (typeof key !== 'string') return undefined;
 
        // Recursively compose the full path until a function is invoked
        return createRecursiveProxy(callback, [...path, key]);
      },
      apply(_1, _2, args) {
        // Call the callback function with the entire path we
        // recursively created and forward the arguments
        return callback({
          path,
          args,
        });
      },
    },
  );
 
  return proxy;
}
Copy

ts
interface ProxyCallbackOptions {
  path: readonly string[];
  args: readonly unknown[];
}
 
type ProxyCallback = (opts: ProxyCallbackOptions) => unknown;
 
function createRecursiveProxy(callback: ProxyCallback, path: readonly string[]) {
  const proxy: unknown = new Proxy(
    () => {
      // dummy no-op function since we don't have any
      // client-side target we want to remap to
    },
    {
      get(_obj, key) {
        if (typeof key !== 'string') return undefined;
 
        // Recursively compose the full path until a function is invoked
        return createRecursiveProxy(callback, [...path, key]);
      },
      apply(_1, _2, args) {
        // Call the callback function with the entire path we
        // recursively created and forward the arguments
        return callback({
          path,
          args,
        });
      },
    },
  );
 
  return proxy;
}
Copy

Cela semble un peu magique, comment cela fonctionne-t-il ?

• La méthode get gère les accès aux propriétés comme post.byId. La clé (key) correspond au nom de la propriété accédée : lorsque nous tapons post, notre key sera post, et pour post.byId ce sera byId. Le proxy récursif combine ces clés en un chemin final, par exemple ["post", "byId", "query"], que nous utiliserons pour déterminer l'URL à interroger.

• La méthode apply est appelée lorsque nous invoquons une fonction sur le proxy, comme .query(args). Les args représentent les arguments passés à la fonction : lors de l'appel post.byId.query(args), nos args seront notre input, que nous transmettrons comme paramètres de requête ou corps de requête selon le type de procédure. Le createRecursiveProxy prend une fonction de rappel que nous mapperons à apply avec le chemin et les arguments.

Voici une représentation visuelle du fonctionnement du proxy lors de l'appel trpc.post.byId.query({ id: 1 }) :

🧩 Assemblage final​

Maintenant que nous avons cet utilitaire et comprenons son fonctionnement, utilisons-le pour créer notre client. Nous fournirons au createRecursiveProxy une fonction de rappel qui prendra le chemin et les arguments pour requêter le serveur via fetch. Nous ajouterons un générique à la fonction acceptant n'importe quel type de routeur tRPC (AnyTRPCRouter), puis nous casterons le type de retour vers le type DecorateRouterRecord créé précédemment :

ts
import { TRPCResponse } from '@trpc/server/rpc';
 
export const createTinyRPCClient = <TRouter extends AnyTRPCRouter>(
  baseUrl: string,
) =>
  createRecursiveProxy(async (opts) => {
    const path = [...opts.path]; // e.g. ["post", "byId", "query"]
    const method = path.pop()! as 'query' | 'mutate';
    const dotPath = path.join('.'); // "post.byId" - this is the path procedures have on the backend
    let uri = `${baseUrl}/${dotPath}`;
 
    const [input] = opts.args;
    const stringifiedInput = input !== undefined && JSON.stringify(input);
    let body: undefined | string = undefined;
    if (stringifiedInput !== false) {
      if (method === 'query') {
        uri += `?input=${encodeURIComponent(stringifiedInput)}`;
      } else {
        body = stringifiedInput;
      }
    }
 
    const json: TRPCResponse = await fetch(uri, {
      method: method === 'query' ? 'GET' : 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body,
    }).then((res) => res.json());
 
    if ('error' in json) {
      throw new Error(`Error: ${json.error.message}`);
    }
    // No error - all good. Return the data.
    return json.result.data;
  }, []) as DecorateRouterRecord<TRouter['_def']['record']>;
//   ^? provide empty array as path to begin with
Copy

ts
import { TRPCResponse } from '@trpc/server/rpc';
 
export const createTinyRPCClient = <TRouter extends AnyTRPCRouter>(
  baseUrl: string,
) =>
  createRecursiveProxy(async (opts) => {
    const path = [...opts.path]; // e.g. ["post", "byId", "query"]
    const method = path.pop()! as 'query' | 'mutate';
    const dotPath = path.join('.'); // "post.byId" - this is the path procedures have on the backend
    let uri = `${baseUrl}/${dotPath}`;
 
    const [input] = opts.args;
    const stringifiedInput = input !== undefined && JSON.stringify(input);
    let body: undefined | string = undefined;
    if (stringifiedInput !== false) {
      if (method === 'query') {
        uri += `?input=${encodeURIComponent(stringifiedInput)}`;
      } else {
        body = stringifiedInput;
      }
    }
 
    const json: TRPCResponse = await fetch(uri, {
      method: method === 'query' ? 'GET' : 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body,
    }).then((res) => res.json());
 
    if ('error' in json) {
      throw new Error(`Error: ${json.error.message}`);
    }
    // No error - all good. Return the data.
    return json.result.data;
  }, []) as DecorateRouterRecord<TRouter['_def']['record']>;
//   ^? provide empty array as path to begin with
Copy

Notons particulièrement que notre chemin utilise des . comme séparateurs plutôt que des /. Cela nous permet d'avoir un unique gestionnaire d'API côté serveur traitant toutes les requêtes, et non un par procédure. Si vous utilisez un framework avec routage basé sur les fichiers comme Next.js, vous reconnaîtrez peut-être le fichier catchall /api/trpc/[trpc].ts qui correspondra à tous les chemins de procédures.

Nous avons également une annotation de type TRPCResponse sur la requête fetch. Cela définit le format de réponse conforme à JSONRPC utilisé par le serveur. Vous pouvez en lire davantage ici. En bref : nous recevons soit un objet result soit un objet error, que nous pouvons utiliser pour déterminer si la requête a réussi et gérer les erreurs appropriées en cas de problème.

Et voilà ! C'est tout le code nécessaire pour appeler vos procédures tRPC côté client comme s'il s'agissait de fonctions locales. En surface, on dirait que nous appelons simplement la fonction de résolution de publicProcedure.query / mutation via des accès normaux aux propriétés, mais nous traversons en réalité une frontière réseau, ce qui nous permet d'utiliser des bibliothèques côté serveur comme Prisma sans exposer les identifiants de base de données.

Testons-le !​

Maintenant, créez le client en fournissant l'URL de votre serveur : vous obtiendrez une autocomplétion complète et une sécurité typographique lorsque vous appellerez vos procédures !

ts
const url = 'http://localhost:3000/api/trpc';
const client = createTinyRPCClient<AppRouter>(url);
// 🧙‍♀️ magic autocompletion
client.post.b;
// 👀 fully typesafe
const post = await client.post.byId.query({ id: '123' });
Copy

ts
const url = 'http://localhost:3000/api/trpc';
const client = createTinyRPCClient<AppRouter>(url);
// 🧙‍♀️ magic autocompletion
client.post.b;
// 👀 fully typesafe
const post = await client.post.byId.query({ id: '123' });
Copy

Le code complet du client est disponible ici, et les tests d'utilisation ici.

Conclusion​

J'espère que vous avez apprécié cet article et découvert le fonctionnement interne de tRPC. Vous ne devriez probablement pas utiliser cette version minimaliste au détriment de @trpc/client qui ne pèse que quelques kilo-octets de plus - il offre bien plus de flexibilité que ce que nous montrons ici :

• Options de requête pour signaux d'annulation, SSR, etc...

• Liens (Links)

• Regroupement de procédures (Batching)

• WebSockets / abonnements

• Gestion d'erreurs élégante

• Transformateurs de données

• Gestion des cas limites comme les réponses non conformes à tRPC

Nous n'avons pas non plus abordé en détail les aspects serveur aujourd'hui - nous les couvrirons peut-être dans un futur article. Si vous avez des questions, n'hésitez pas à me contacter sur Twitter.

Ce n'est un secret pour personne que TypeScript est le moteur derrière la remarquable DX que tRPC propose. L'adoption de TypeScript est aujourd'hui la norme moderne pour offrir des expériences JavaScript de qualité - mais cette certitude accrue autour des types comporte certains compromis.

Il n'est un secret pour personne que TypeScript est la force motrice derrière la manière dont tRPC fournit son incroyable expérience développeur (DX). L'adoption de TypeScript est la norme moderne pour offrir aujourd'hui d'excellentes expériences basées sur JavaScript - mais cette certitude accrue autour des types comporte certains compromis.

Aujourd'hui, le vérificateur de type TypeScript a tendance à devenir lent (même si les versions comme TS 4.9 sont prometteuses !). Les bibliothèques contiennent presque toujours les incantations TypeScript les plus sophistiquées de votre base de code, poussant votre compilateur TS à ses limites. Pour cette raison, les auteurs de bibliothèques comme nous doivent être conscients de notre contribution à cette charge et faire de notre mieux pour que votre IDE continue de fonctionner aussi rapidement que possible.

Automatisation des performances de la bibliothèque​

Alors que tRPC était en v9, nous avons commencé à recevoir des rapports de développeurs indiquant que leurs grands routeurs tRPC commençaient à avoir des effets néfastes sur leur vérificateur de types. C'était une nouvelle expérience pour tRPC car nous avons constaté une adoption massive pendant la phase v9 de son développement. Avec de plus en plus de développeurs créant des produits de plus en plus grands avec tRPC, des failles ont commencé à apparaître.

Votre bibliothèque n'est peut-être pas lente pour l'instant, mais il est important de surveiller les performances à mesure que votre bibliothèque évolue et change. Les tests automatisés peuvent vous soulager d'un immense fardeau lors de la création de bibliothèques (et de la construction d'applications !) en testant programmatiquement le code de votre bibliothèque à chaque commit.

Pour tRPC, nous faisons de notre meilleur possible pour garantir cela en générant et en testant un routeur avec 3 500 procédures et 1 000 routeurs. Mais cela ne teste que jusqu'où nous pouvons pousser le compilateur TS avant qu'il ne casse, et non la durée de la vérification de types. Nous testons les trois parties de la bibliothèque (serveur, client vanilla et client React) car elles ont toutes des chemins de code différents. Par le passé, nous avons observé des régressions isolées à une section de la bibliothèque et nous comptons sur nos tests pour nous alerter de ces comportements inattendus. (Nous voulons encore faire plus pour mesurer les temps de compilation)

tRPC n'est pas une bibliothèque lourde en temps d'exécution, donc nos métriques de performance sont centrées sur la vérification de types. Par conséquent, nous restons attentifs à :

• Un temps de vérification des types important avec tsc

• Un temps de réponse long du serveur de langage TypeScript après des modifications

Ce dernier point est celui auquel tRPC doit accorder le plus d'attention. Vous ne voulez jamais que vos développeurs attendent la mise à jour du serveur de langage après une modification. C'est là que tRPC doit maintenir ses performances pour que vous puissiez profiter d'une excellente DX.

Comment j'ai identifié des opportunités d'amélioration dans tRPC​

Il y a toujours un compromis entre la précision TypeScript et les performances du compilateur. Ces deux aspects sont cruciaux pour les autres développeurs, nous devons donc être extrêmement vigilants sur la façon dont nous écrivons nos types. Une application risque-t-elle des erreurs graves parce qu'un type est "trop permissif" ? Le gain de performance en vaut-il la peine ?

Y aura-t-il même un gain de performance significatif ? Excellente question.

Y aura-t-il même un gain de performances significatif ? Excellente question.

Voyons comment identifier des opportunités d'amélioration des performances dans du code TypeScript. Nous allons examiner le processus que j'ai suivi pour créer PR #2716, ce qui a entraîné une réduction de 59% du temps de compilation TypeScript.

slug: typescript-performance-lessons title: Leçons de performance TypeScript lors du refactoring pour la v10 authors: [sachinraja]​

TypeScript dispose d'un outil de traçage intégré qui peut vous aider à identifier les goulots d'étranglement dans vos types. Il n'est pas parfait, mais c'est le meilleur outil disponible.

Il est idéal de tester votre bibliothèque sur une application réelle pour simuler ce que votre bibliothèque fait pour de vrais développeurs. Pour tRPC, j'ai créé une application T3 de base qui ressemble à ce que beaucoup de nos utilisateurs utilisent.

Voici les étapes que j'ai suivies pour tracer tRPC :

1. Lier localement la bibliothèque à l'application exemple. Cela permet de modifier le code de la bibliothèque et tester immédiatement les changements.

2. Exécuter cette commande dans l'application exemple :

   sh
   tsc --generateTrace ./trace --incremental false
   Copy

   sh
   tsc --generateTrace ./trace --incremental false
   Copy

3. Un fichier trace/trace.json sera généré. Vous pouvez l'ouvrir dans une application d'analyse de traces (Perfetto ou chrome://tracing).

C'est là que cela devient intéressant pour analyser le profil de performance des types. Premier résultat du traçage :

Une barre plus longue indique un processus plus long. La barre verte sélectionnée montre que src/pages/index.ts est le goulot d'étranglement. Le champ Duration révèle 332ms - un temps énorme pour la vérification de types ! La barre bleue checkVariableDeclaration indique que le compilateur a passé la majorité du temps sur une variable. En cliquant dessus : Le champ pos donne la position de la variable dans le fichier. Dans src/pages/index.ts, le coupable est utils = trpc.useContext() !

Mais comment est-ce possible ? Ce simple hook semble inoffensif ! Examinons le code :

tsx
import type { AppRouter } from '~/server/trpc';
const trpc = createTRPCReact<AppRouter>();
const Home: NextPage = () => {
  const { data } = trpc.r0.greeting.useQuery({ who: 'from tRPC' });
  const utils = trpc.useContext();
  utils.r49.greeting.invalidate();
};
export default Home;
Copy

tsx
import type { AppRouter } from '~/server/trpc';
const trpc = createTRPCReact<AppRouter>();
const Home: NextPage = () => {
  const { data } = trpc.r0.greeting.useQuery({ who: 'from tRPC' });
  const utils = trpc.useContext();
  utils.r49.greeting.invalidate();
};
export default Home;
Copy

Rien de suspect en surface : juste un useContext et une invalidation de requête. Le problème doit donc être plus profond. Analysons les types sous-jacents :

ts
type DecorateProcedure<
  TRouter extends AnyRouter,
  TProcedure extends Procedure<any>,
  TProcedure extends AnyQueryProcedure,
> = {
  /**
   * @see https://tanstack.com/query/v4/docs/framework/react/guides/query-invalidation
   */
  invalidate(
    input?: inferProcedureInput<TProcedure>,
    filters?: InvalidateQueryFilters,
    options?: InvalidateOptions,
  ): Promise<void>;
  // ... and so on for all the other React Query utilities
};
export type DecoratedProcedureUtilsRecord<TRouter extends AnyRouter> =
  OmitNeverKeys<{
    [TKey in keyof TRouter['_def']['record']]: TRouter['_def']['record'][TKey] extends LegacyV9ProcedureTag
      ? never
      : TRouter['_def']['record'][TKey] extends AnyRouter
        ? DecoratedProcedureUtilsRecord<TRouter['_def']['record'][TKey]>
        : TRouter['_def']['record'][TKey] extends AnyQueryProcedure
          ? DecorateProcedure<TRouter, TRouter['_def']['record'][TKey]>
          : never;
  }>;
Copy

ts
type DecorateProcedure<
  TRouter extends AnyRouter,
  TProcedure extends Procedure<any>,
  TProcedure extends AnyQueryProcedure,
> = {
  /**
   * @see https://tanstack.com/query/v4/docs/framework/react/guides/query-invalidation
   */
  invalidate(
    input?: inferProcedureInput<TProcedure>,
    filters?: InvalidateQueryFilters,
    options?: InvalidateOptions,
  ): Promise<void>;
  // ... and so on for all the other React Query utilities
};
export type DecoratedProcedureUtilsRecord<TRouter extends AnyRouter> =
  OmitNeverKeys<{
    [TKey in keyof TRouter['_def']['record']]: TRouter['_def']['record'][TKey] extends LegacyV9ProcedureTag
      ? never
      : TRouter['_def']['record'][TKey] extends AnyRouter
        ? DecoratedProcedureUtilsRecord<TRouter['_def']['record'][TKey]>
        : TRouter['_def']['record'][TKey] extends AnyQueryProcedure
          ? DecorateProcedure<TRouter, TRouter['_def']['record'][TKey]>
          : never;
  }>;
Copy

Plusieurs éléments méritent explication. Commençons par comprendre ce code.

Nous avons un type récursif DecoratedProcedureUtilsRecord qui parcourt toutes les procédures du routeur pour les "décorer" (ajouter des méthodes) avec des utilitaires React Query comme invalidateQueries.

Dans tRPC v10, nous maintenons la compatibilité avec les anciens routeurs v9, mais les clients v10 ne peuvent pas appeler les procédures des routeurs v9. Pour chaque procédure, nous vérifions si c'est une procédure v9 (extends LegacyV9ProcedureTag) et la supprimons le cas échéant. C'est un travail conséquent pour TypeScript... s'il n'est pas évalué paresseusement.

Évaluation paresseuse​

Le problème ici est que TypeScript évalue tout ce code dans le système de types, même s'il n'est pas utilisé immédiatement. Notre code utilise uniquement utils.r49.greeting.invalidate, donc TypeScript devrait seulement avoir besoin de dérouler la propriété r49 (un routeur), puis la propriété greeting (une procédure), et enfin la fonction invalidate pour cette procédure. Aucun autre type n'est nécessaire dans ce code, et déterminer immédiatement le type de chaque méthode utilitaire React Query pour toutes vos procédures tRPC ralentirait inutilement TypeScript. TypeScript diffère l'évaluation des types pour les propriétés des objets jusqu'à ce qu'elles soient utilisées directement, donc théoriquement notre type ci-dessus devrait bénéficier d'une évaluation paresseuse... n'est-ce pas ?

Eh bien, ce n'est pas exactement un objet. Il y a en réalité un type qui englobe l'ensemble : OmitNeverKeys. Ce type est une utilitaire qui supprime les clés ayant la valeur never d'un objet. C'est à cette étape que nous retirons les procédures v9 pour qu'elles n'apparaissent pas dans l'Intellisense.

Mais cela crée un énorme problème de performance. Nous forçons TypeScript à évaluer les valeurs de tous les types immédiatement pour vérifier s'ils sont never.

Comment résoudre ce problème ? Modifions nos types pour faire moins.

Adoptons la paresse​

Nous devons trouver un moyen pour que l'API v10 s'adapte plus harmonieusement aux routeurs hérités v9. Les nouveaux projets tRPC ne devraient pas souffrir de la réduction de performance TypeScript du mode interop.

L'idée est de réorganiser les types fondamentaux. Les procédures v9 sont des entités différentes des procédures v10, elles ne devraient donc pas occuper le même espace dans notre code de bibliothèque. Côté serveur tRPC, cela signifie que nous avons dû stocker les types dans différents champs du routeur plutôt que dans un seul champ record (voir le DecoratedProcedureUtilsRecord ci-dessus).

Nous avons modifié le système pour que les routeurs v9 injectent leurs procédures dans un champ legacy lorsqu'ils sont convertis en routeurs v10.

Anciens types :

ts
export type V10Router<TProcedureRecord> = {
  record: TProcedureRecord;
};
// convert a v9 interop router to a v10 router
export type MigrateV9Router<TV9Router extends V9Router> = V10Router<{
  [TKey in keyof TV9Router['procedures']]: MigrateProcedure<
    TV9Router['procedures'][TKey]
  > &
    LegacyV9ProcedureTag;
}>;
Copy

ts
export type V10Router<TProcedureRecord> = {
  record: TProcedureRecord;
};
// convert a v9 interop router to a v10 router
export type MigrateV9Router<TV9Router extends V9Router> = V10Router<{
  [TKey in keyof TV9Router['procedures']]: MigrateProcedure<
    TV9Router['procedures'][TKey]
  > &
    LegacyV9ProcedureTag;
}>;
Copy

Si vous vous souvenez du type DecoratedProcedureUtilsRecord ci-dessus, vous verrez que nous avons attaché LegacyV9ProcedureTag ici pour différencier au niveau des types les procédures v9 et v10, et empêcher que les procédures v9 soient appelées depuis des clients v10.

Nouveaux types :

ts
export type V10Router<TProcedureRecord> = {
  record: TProcedureRecord;
  // by default, no legacy procedures
  legacy: {};
};
export type MigrateV9Router<TV9Router extends V9Router> = {
  // v9 routers inject their procedures into a `legacy` field
  legacy: {
    // v9 clients require that we filter queries, mutations, subscriptions at the top-level
    queries: MigrateProcedureRecord<TV9Router['queries']>;
    mutations: MigrateProcedureRecord<TV9Router['mutations']>;
    subscriptions: MigrateProcedureRecord<TV9Router['subscriptions']>;
  };
} & V10Router</* empty object, v9 routers have no v10 procedures to pass */ {}>;
Copy

ts
export type V10Router<TProcedureRecord> = {
  record: TProcedureRecord;
  // by default, no legacy procedures
  legacy: {};
};
export type MigrateV9Router<TV9Router extends V9Router> = {
  // v9 routers inject their procedures into a `legacy` field
  legacy: {
    // v9 clients require that we filter queries, mutations, subscriptions at the top-level
    queries: MigrateProcedureRecord<TV9Router['queries']>;
    mutations: MigrateProcedureRecord<TV9Router['mutations']>;
    subscriptions: MigrateProcedureRecord<TV9Router['subscriptions']>;
  };
} & V10Router</* empty object, v9 routers have no v10 procedures to pass */ {}>;
Copy

Maintenant, nous pouvons supprimer OmitNeverKeys car les procédures sont pré-triées : le type de la propriété record d'un routeur contiendra toutes les procédures v10, et sa propriété legacy contiendra toutes les procédures v9. Nous ne forçons plus TypeScript à évaluer entièrement l'énorme type DecoratedProcedureUtilsRecord. Nous pouvons aussi supprimer le filtrage des procédures v9 avec LegacyV9ProcedureTag.

Est-ce que ça a fonctionné ?​

Notre nouvelle trace montre que le goulot d'étranglement a été supprimé :

Une amélioration substantielle ! Le temps de vérification des types est passé de 332ms à 136ms 🤯 ! Cela peut sembler minime dans l'absolu, mais c'est une victoire majeure. 200ms, c'est peu une fois – mais considérez :

• combien d'autres bibliothèques TS sont dans un projet

• combien de développeurs utilisent tRPC aujourd'hui

• combien de fois leurs types se ré-évaluent pendant une session de travail

Cela représente beaucoup de 200ms qui s'accumulent pour former un très gros chiffre.

Nous cherchons toujours plus d'opportunités pour améliorer l'expérience des développeurs TypeScript, que ce soit avec tRPC ou un autre problème TS à résoudre. Mentionnez-moi sur Twitter si vous voulez parler TypeScript.

Un grand merci à Anthony Shew pour son aide dans la rédaction de cet article, et à Alex pour sa relecture !

tRPC offre une excellente expérience développeur en imposant des liaisons de types strictes sur toute la stack grâce à la puissance de TypeScript. Plus de dérive du contrat d'API, plus de génération de code.

Depuis notre dernière version majeure en août 2021, la communauté tRPC a connu une croissance substantielle :

• Nous comptons désormais plus de 15 000 étoiles sur GitHub

• Une communauté Discord de plus de 2 000 membres

• Plus de 100 000 téléchargements hebdomadaires sur npm

• Près de 200 contributeurs

• Un écosystème croissant d'extensions, d'exemples et de contenus

Aujourd'hui, nous lançons tRPC v10. Nous sommes ravis d'annoncer que la v10 est déjà utilisée en production par de nombreux grands projets TypeScript. Cette version officielle marque sa disponibilité générale pour toute la communauté.

Pour les nouveaux projets, vous pouvez démarrer rapidement avec une application exemple pour découvrir tRPC v10. Pour les projets utilisant déjà tRPC v9, consultez le guide de migration vers v10.

Vue d'ensemble des changements​

v10 est la plus importante version de tRPC jamais publiée. C'est la première fois que nous modifions fondamentalement la structure de tRPC, et nous pensons que ces changements ouvrent de nouvelles possibilités pour les équipes dynamiques travaillant sur des applications de pointe.

Expérience développeur améliorée​

tRPC v10 épouse parfaitement votre IDE. Nous voulons unifier vos types, mais nous avons aussi intégré votre expérience frontend, backend et d'édition dans cette version.

Avec v10, vous pouvez :

• Utiliser "Go to Definition" pour passer directement de votre consommateur frontend à votre procédure backend

• Utiliser "Rename Symbol" pour renommer un argument d'entrée ou une procédure dans toute votre application

• Inférer les types plus facilement lorsque vous souhaitez utiliser manuellement vos types tRPC

Backend puissant​

Dans v10, nous avons repensé la syntaxe de définition des procédures backend, offrant plus d'opportunités pour intégrer votre logique métier de manière optimale. Cette version de tRPC inclut :

• Des middlewares réutilisables avec Context Extension

• Des procédures chaînables et réutilisables supportant plusieurs parseurs d'entrée

• Une gestion d'erreurs flexible avec formatage personnalisé

• Des métadonnées de procédure pour enrichir vos procédures d'informations supplémentaires

Performances TypeScript massivement améliorées​

TypeScript permet aux développeurs de réaliser des choses extraordinaires, mais cela a un coût. Plusieurs techniques que nous utilisons pour maintenir vos types stricts sollicitent fortement le compilateur TypeScript. Nous avons reçu des retours indiquant que les plus grandes applications utilisant tRPC v9 subissaient des baisses de performances dans les IDE à cause de cette pression sur le compilateur.

Notre objectif est d'améliorer l'expérience des développeurs pour les applications de toute taille. Avec la v10, nous avons considérablement optimisé les performances TypeScript (particulièrement avec la compilation incrémentale) pour que votre éditeur reste réactif.

Migration progressive​

Nous avons également travaillé à rendre la migration la plus fluide possible, notamment avec une méthode interop() qui permet (presque) une rétrocompatibilité totale avec les routeurs v9. Consultez le guide de migration pour plus de détails.

Sachin de l'équipe principale a également créé un codemod qui automatise l'essentiel du travail de migration.

Un écosystème florissant​

Un riche écosystème de sous-bibliothèques continue de se développer autour de tRPC. Voici quelques exemples :

• trpc-openapi pour créer facilement des endpoints REST-compatibles

• create-t3-app pour initialiser une application Next.js full-stack avec tRPC

• create-t3-turbo pour démarrer votre application React Native avec tRPC

• trpc-chrome pour développer des extensions Chrome avec tRPC

• Des adaptateurs pour des frameworks comme Solid, Svelte et Vue

Pour plus de plugins, exemples et adaptateurs, découvrez la collection Awesome tRPC.

Merci !​

L'équipe principale et moi-même tenons à vous dire : ce n'est qu'un début. Nous travaillons déjà sur l'intégration des React Server Components et de Next.js 13.

Je tiens aussi à remercier chaleureusement Sachin, Julius, James, Ahmed, Chris, Theo, Anthony et tous les contributeurs ayant rendu cette version possible.

Merci d'utiliser et de soutenir tRPC.

slug: typescript-performance-lessons title: Leçons de performance TypeScript lors du refactoring pour la v10 authors: [sachinraja]​

• Suivez @trpcio sur Twitter.

• Rejoignez notre communauté Discord

• Essayez tRPC dans votre navigateur

tRPC vous offre une sécurité de typage de bout en bout entre votre serveur (Node) et votre client, sans même déclarer de types. Sur le backend, vous retournez simplement des données dans une fonction, et sur le frontend vous utilisez ces données via le nom du endpoint.

👋 Je suis Alex, alias "KATT" sur GitHub, et je souhaite vous présenter une bibliothèque nommée tRPC. Je n'ai pas encore publié d'articles à son sujet, donc j'écris cette intro pour lancer le mouvement (mais nous avons déjà dépassé >530 🌟 sur GitHub). Attendez-vous à des articles et vidéos de présentation prochainement ! Pour suivre les actualités ou poser des questions, suivez-moi sur Twitter @alexdotjs.

Voici à quoi ressemble un appel client vers un endpoint tRPC :

J'ai développé une bibliothèque pour React (@trpc/react) qui s'appuie sur l'excellent react-query, mais la librairie cliente (@trpc/client) fonctionne sans React (si vous souhaitez créer une lib spécifique pour Svelte/Vue/Angular/[..], contactez-moi !).

Aucune génération de code n'est requise et vous pouvez l'intégrer facilement à votre projet Next.js/CRA/Express existant.

Exemple​

Voici un exemple de procédure tRPC (endpoint) nommée hello qui prend un argument de type string.

tsx
const appRouter = trpc.router().query('hello', {
  input: z.string().optional(),
  resolve: ({ input }) => {
    return {
      text: `hello ${input ?? 'world'}`,
    };
  },
});
export type AppRouter = typeof appRouter;
Copy

tsx
const appRouter = trpc.router().query('hello', {
  input: z.string().optional(),
  resolve: ({ input }) => {
    return {
      text: `hello ${input ?? 'world'}`,
    };
  },
});
export type AppRouter = typeof appRouter;
Copy

Et voici un client utilisant ces données de manière type-safe :

tsx
import type { AppRouter } from './server';
async function main() {
  const client = createTRPCClient<AppRouter>({
    url: `http://localhost:2022`,
  });
  const result = await client.query('hello', '@alexdotjs');
  console.log(result); // --> { text: "hello @alexdotjs" }
}
main();
Copy

tsx
import type { AppRouter } from './server';
async function main() {
  const client = createTRPCClient<AppRouter>({
    url: `http://localhost:2022`,
  });
  const result = await client.query('hello', '@alexdotjs');
  console.log(result); // --> { text: "hello @alexdotjs" }
}
main();
Copy

C'est tout ce dont vous avez besoin pour la sécurité de typage ! Le result est inféré à partir des données retournées par la fonction backend. Les données d'entrée sont également inférées via le validateur, donc les données sont immédiatement exploitables - en réalité, vous devez passer les données d'entrée via un validateur (& tRPC fonctionne nativement avec zod/yup/validateurs personnalisés).

Lien CodeSandbox pour expérimenter l'exemple : https://githubbox.com/trpc/trpc/tree/main/examples/standalone-server (privilégiez la sortie terminal plutôt que l'aperçu !)

Quoi ? J'importe du code backend dans mon client ? - Non, absolument pas

Bien que cela y ressemble, aucun code n'est partagé du serveur vers le client ; le import type de TypeScript "[...] importe uniquement des déclarations pour les annotations et définitions de types. Il est toujours entièrement effacé, sans laisser de trace à l'exécution." - une fonctionnalité ajoutée dans TypeScript 3.8 - voir la doc TypeScript.

Aucune génération de code n'est impliquée, vous pouvez l'ajouter à votre application dès aujourd'hui tant que vous avez un moyen de partager les types entre serveur et client (un monorepo est idéal).

Mais ce n'est que le début !​

J'ai mentionné précédemment une bibliothèque React. Pour utiliser les données ci-dessus dans React :

tsx
const { data } = trpc.useQuery(['hello', '@alexdotjs']);
Copy

tsx
const { data } = trpc.useQuery(['hello', '@alexdotjs']);
Copy

.. et vous obtiendrez des données type-safe côté client.

Vous pouvez intégrer tRPC dès maintenant à votre projet brownfield existant (des adaptateurs existent pour Express/Next.js). Cela fonctionne parfaitement avec CRA et devrait aussi marcher avec React Native. La solution n'est même pas liée à React : si vous voulez développer une lib pour Svelte ou Vue, contactez-moi.

Quid des mutations de données ?​

Les mutations sont aussi simples que les requêtes - elles reposent sur le même mécanisme sous-jacent mais sont exposées différemment pour plus de clarté syntaxique et génèrent une requête HTTP POST plutôt qu'un GET.

Voici un exemple un peu plus complexe utilisant une base de données, tiré de notre démo TodoMVC sur todomvc.trpc.io / https://github.com/trpc/trpc/tree/main/examples/next-prisma-todomvc

tsx
const todoRouter = createRouter().mutation('add', {
  input: z.object({
    id: z.string().uuid(),
    data: z.object({
      completed: z.boolean().optional(),
      text: z.string().min(1).optional(),
    }),
  }),
  async resolve({ ctx, input }) {
    const { id, data } = input;
    const todo = await ctx.task.update({
      where: { id },
      data,
    });
    return todo;
  },
});
Copy

tsx
const todoRouter = createRouter().mutation('add', {
  input: z.object({
    id: z.string().uuid(),
    data: z.object({
      completed: z.boolean().optional(),
      text: z.string().min(1).optional(),
    }),
  }),
  async resolve({ ctx, input }) {
    const { id, data } = input;
    const todo = await ctx.task.update({
      where: { id },
      data,
    });
    return todo;
  },
});
Copy