Aller au contenu principal
Version : 11.x

Migrer de la v10 à la v11

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 →

Migration de la v10 vers la v11​

astuce

Pour la plupart des utilisateurs, la migration devrait être rapide et simple.

Si les trois étapes ci-dessous ne suffisent pas, consultez la section "rarement cassants" dans ce document.

1. Installez les nouvelles versions​

npm install @trpc/server@^11 @trpc/client@^11 @trpc/react-query@^11 @trpc/next@^11 @tanstack/react-query@^5 @tanstack/react-query-devtools@^5

2. Si vous utilisez des transformer, mettez à jour vos liens​

Voir les transformers déplacés vers les liens pour plus d'informations.

3. Si vous utilisez @trpc/react-query, mettez à jour votre version de @tanstack/react-query​

Voir react-query-v5 pour plus d'informations.

Journal des modifications complet (ordre chronologique inversé)​

Nouvelle intégration TanStack React Query ! (non cassant)​

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 !

Read the blog post for more information.

Arrêt des abonnements depuis le serveur (rarement cassant)​

Nous prenons désormais en charge l'arrêt des abonnements depuis le serveur, ce qui permet des fonctionnalités comme celle-ci :

ts
const myRouter = router({
  sub: publicProcedure.subscription(async function* (opts) {
    for await (const data of on(ee, 'data', {
      signal: opts.signal,
    })) {
      const num = data[0] as number | undefined;
      if (num === undefined) {
        // This will now stop the subscription on the client and trigger the `onComplete` callback
        return;
      }
      yield num;
    }
  }),
});
ts
const myRouter = router({
  sub: publicProcedure.subscription(async function* (opts) {
    for await (const data of on(ee, 'data', {
      signal: opts.signal,
    })) {
      const num = data[0] as number | undefined;
      if (num === undefined) {
        // This will now stop the subscription on the client and trigger the `onComplete` callback
        return;
      }
      yield num;
    }
  }),
});

Voir la documentation sur les abonnements pour plus d'informations.

Prise en charge du lazy-loading des routeurs (non cassant)​

Voir la documentation sur le lazy-loading des routeurs pour plus d'informations.

Dans le cadre de cette évolution, nous avons modifié l'argument de la méthode interne callProcedure() pour recevoir un paramètre { router: AnyRouter } au lieu de { _def: AnyRouter['_def'] }.

basePath personnalisé pour gérer les requêtes dans l'adaptateur standalone (non cassant)​

L'adaptateur standalone prend désormais en charge une option basePath qui tronquera ce préfixe au début du chemin de la requête.

Voir la documentation de l'adaptateur standalone pour plus d'informations.

Prise en charge des serveurs HTTP/2 (non cassant)​

Nous prenons désormais en charge les serveurs HTTP/2, vous pouvez donc utiliser les fonctions createHTTP2Handler et createHTTPServer pour créer des serveurs HTTP/2.

Voir la documentation de l'adaptateur standalone pour plus d'informations.

Déplacement de TRPCProcedureOptions vers @trpc/client (non cassant pour la plupart)​

Si vous utilisiez précédemment ProcedureOptions de @trpc/server, vous devez désormais utiliser TRPCProcedureOptions de @trpc/client.

Prise en charge des promesses dans les données imbriquées (non cassant)​

Nous autorisons désormais les promesses dans les données imbriquées lors de l'utilisation du httpBatchStreamLink, ce qui permet des fonctionnalités comme celle-ci :

ts
const router = router({
  embedPromise: publicProcedure.query(() => {
    async function slowThing() {
      await new Promise((resolve) => setTimeout(resolve, 1000));
      return 'slow';
    }
    return {
      instant: 'instant',
      slow: slowThing(),
    };
  }),
});
ts
const router = router({
  embedPromise: publicProcedure.query(() => {
    async function slowThing() {
      await new Promise((resolve) => setTimeout(resolve, 1000));
      return 'slow';
    }
    return {
      instant: 'instant',
      slow: slowThing(),
    };
  }),
});

Déplacement de reconnectAfterInactivityMs vers sse.client (non cassant)​

Section Améliorations du lien HTTP d'abonnement et documentation associée mises à jour.

TypeScript version >=5.7.2 désormais requis (non cassant)​

tRPC nécessite désormais TypeScript version 5.7.2 ou supérieure. Ce changement fait suite à un rapport de bug où nous avons opté pour une approche tournée vers l'avenir.

Si vous tentez d'installer tRPC avec une version non supportée de TypeScript, vous recevrez une erreur de dépendance peer lors de l'installation.

Si votre éditeur affiche des types any, c'est probablement parce qu'il n'utilise pas la bonne version de TypeScript. Configurez votre éditeur pour utiliser la version de TypeScript installée dans le package.json de votre projet.

Pour les utilisateurs de VSCode, ajoutez ces paramètres à votre .vscode/settings.json :

.vscode/settings.json
json
{
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}
.vscode/settings.json
json
{
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

Déplacement de experimental.sseSubscriptions -> sse (non cassant)​

L'option experimental.sseSubscriptions a été déplacée vers simplement sse dans la fonction initTRPC.create().

Ajout de la détection et de la récupération des connexions obsolètes :

Sur le serveur, vous pouvez configurer un intervalle de ping pour maintenir la connexion active :

ts
export const t = initTRPC.create({
  // ...
  sse: {
    ping: {
      enabled: true,
      intervalMs: 15_000,
    },
    client: {
      // Reconnect if no messages or pings are received for 20 seconds
      reconnectAfterInactivityMs: 20_000,
    },
  },
});
ts
export const t = initTRPC.create({
  // ...
  sse: {
    ping: {
      enabled: true,
      intervalMs: 15_000,
    },
    client: {
      // Reconnect if no messages or pings are received for 20 seconds
      reconnectAfterInactivityMs: 20_000,
    },
  },
});

Nous ajouterons probablement une configuration par défaut pour l'intervalle de ping et le timeout ultérieurement, mais cela n'est pas encore décidé. Vos retours sont bienvenus dans le canal 🎏-rfc-streaming sur Discord.

Voir la documentation du httpSubscriptionLink pour plus de détails sur ces fonctionnalités.

Voir retryLink - permet de réessayer les opérations ayant échoué

Améliorations de useSubscription (non cassant)​

  • Lors de l'abonnement à des procédures via le hook useSubscription, celui-ci renvoie désormais des informations sur l'état de l'abonnement et de la connexion.

  • Possibilité d'utiliser un ponyfill avec le httpSubscriptionLink

Le type de sortie des procédures d'abonnement devient AsyncGenerator (non cassant)​

Si vous avez utilisé des abonnements avec des générateurs asynchrones en v11, ce changement pourrait impacter votre inférence de types.

Details

We changed the inferred output from:

ts
SubscriptionProcedure<{
  input: __INPUT__;
  output: __OUTPUT__;
}>;
ts
SubscriptionProcedure<{
  input: __INPUT__;
  output: __OUTPUT__;
}>;

to

ts
SubscriptionProcedure<{
  input: __INPUT__;
  output: AsyncGenerator<__OUTPUT__, void, unknown>;
}>;
ts
SubscriptionProcedure<{
  input: __INPUT__;
  output: AsyncGenerator<__OUTPUT__, void, unknown>;
}>;

If you need to infer the value you can use a helper like the below:

ts
type inferAsyncIterableYield<TOutput> =
  TOutput extends AsyncGenerator<infer $Yield> ? $Yield : never;
ts
type inferAsyncIterableYield<TOutput> =
  TOutput extends AsyncGenerator<infer $Yield> ? $Yield : never;

Cette modification garantit la compatibilité avec les futures mises à jour et permet d'utiliser le type return dans les AsyncGenerator des abonnements.

Voir la documentation sur les abonnements pour plus d'informations.

Prise en charge des validateurs de sortie dans les abonnements (non cassant)​

Voir la documentation sur les abonnements pour plus d'informations.

Dépréciation des abonnements renvoyant des Observable (non cassant)​

Nous prenons désormais en charge les fonctions générateur asynchrones pour les abonnements et avons précédemment ajouté un httpSubscriptionLink.

Voir comment utiliser les fonctions générateur asynchrones pour les abonnements dans la documentation sur les abonnements.

Suppression du ponyfill AbortControllerEsque (rarement cassant)​

Nous avons supprimé le ponyfill AbortControllerEsque de tRPC. Pour supporter les anciens navigateurs, utilisez un polyfill comme abortcontroller-polyfill.

Prise en charge des Server-sent events (SSE) (non cassant)​

Nous prenons désormais en charge les SSE pour les abonnements, ce qui évite d'avoir à déployer un serveur WebSocket pour obtenir des mises à jour en temps réel. Le client peut automatiquement se reconnecter et reprendre si la connexion est perdue.

👉 Voir plus dans la documentation du httpSubscriptionLink.

Prise en charge du streaming des réponses via HTTP (non cassant)​

Nous prenons désormais en charge le streaming des mutations et requêtes avec le httpBatchStreamLink.

Cela signifie que les résolveurs de requêtes et mutations peuvent soit être des AsyncGenerator avec yield, soit renvoyer des promesses qui peuvent être différées pour plus tard. Vous pouvez ainsi utiliser des réponses en flux continu via HTTP, sans recourir aux WebSockets.

Nous attendons vos retours sur cette fonctionnalité ! Essayez-la et dites-nous ce que vous en pensez dans le canal 🎏-rfc-streaming sur notre Discord.

👉 Plus de détails dans la documentation de httpBatchStreamLink

resolveHTTPRequest a été remplacé par resolveRequest utilisant les APIs Fetch (rarement cassant)​

La fonction resolveHTTPRequest a été remplacée par resolveRequest qui utilise l'API Fetch - Request/Response.

Ce changement est cassant pour les adaptateurs HTTP, mais ne devrait pas vous affecter en tant qu'utilisateur.

Si vous développez un adaptateur, consultez le fonctionnement de nos adaptateurs dans le code et n'hésitez pas à demander de l'aide sur notre Discord.

TRPCRequestInfo a été mis à jour (rarement cassant)​

Les entrées sont maintenant matérialisées de manière paresseuse lorsque la procédure les requiert, ce qui signifie que l'entrée et le type de procédure ne sont plus disponibles lorsque tRPC appelle createContext.

Vous pouvez toujours accéder à l'entrée via info.calls[index].getRawInput().

Tous les supports expérimentaux form-data ont été remplacés (rarement cassant)​

Ceci ne vous concerne que si vous utilisiez les fonctionnalités expérimentales formdata

  • experimental_formDataLink → utilisez httpLink

  • experimental_parseMultipartFormData → plus nécessaire

  • experimental_isMultipartFormDataRequest → plus nécessaire

  • experimental_composeUploadHandlers → plus nécessaire

  • experimental_createMemoryUploadHandler → plus nécessaire

  • experimental_NodeOnDiskFile et experimental_createFileUploadHandler → non pris en charge dans cette première version, ouvrez une issue si vous devez conserver des données sur disque

  • experimental_contentTypeHandlers → plus nécessaire, mais pourrait revenir si la communauté en a besoin pour des types de données novateurs

Voir la nouvelle approche dans examples/next-formdata

Déplacement de Procedure._def._output_in / Procedure._def._input_in vers Procedure._def.$types (non cassant)​

Ce changement est cassant pour les internes de tRPC, mais ne devrait pas vous affecter en tant qu'utilisateur.

Aucune action requise, sauf si vous utilisez directement Procedure._def._output_in ou Procedure._def._input_in dans votre code.

Vérifications explicites du Content-Type (non cassant)​

Nous effectuons maintenant des vérifications explicites de l'en-tête Content-Type pour les requêtes POST. Si vous envoyez une requête avec un Content-Type incompatible, vous obtiendrez une erreur 415 Unsupported Media Type.

Nos clients tRPC envoient déjà les en-têtes content-type, donc ce changement n'est potentiellement cassant que si vous appelez tRPC manuellement.

Ajout du support pour le remplacement de méthode (rarement cassant)​

Permet de forcer l'envoi des procédures via POST pour contourner certaines limitations comme la longueur maximale des URL.

Ferme #3910

Ajout du support pour les requêtes infinies bidirectionnelles (non cassant)​

Voir useInfiniteQuery()

Ajout de l'utilitaire inferProcedureBuilderResolverOptions<T> (non-breaking)​

Ajoute un utilitaire pour inférer les options d'un résolveur de builder de procédure. Utile pour créer des fonctions réutilisables entre différentes procédures.

Voir le test ici comme référence d'utilisation

Déplacement des transformers vers les links (breaking) -​

TypeScript vous guidera lors de cette migration

Ne concerne que les utilisateurs de transformers de données.

Vous devez désormais configurer les transformers de données dans le tableau links plutôt qu'à l'initialisation du client tRPC :

Ajoutez transformer: superjson à chaque HTTP Link utilisant des transformers :

ts
httpBatchLink({
  url: '/api/trpc',
  transformer: superjson, // <-- add this
});
ts
httpBatchLink({
  url: '/api/trpc',
  transformer: superjson, // <-- add this
});
ts
createTRPCNext<AppRouter>({
  // [..]
  transformer: superjson, // <-- add this
});
ts
createTRPCNext<AppRouter>({
  // [..]
  transformer: superjson, // <-- add this
});

Le mode SSR de @trpc/next nécessite désormais un helper prepass avec ssr: true (rarement breaking)​

Corrige https://github.com/trpc/trpc/issues/5378 où react-dom était importé inutilement sans cette fonctionnalité.

Voir la doc SSR

Ajout du support des définitions raccourcies de routeurs (non-breaking)​

Voir Fusion de routeurs

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

Suppression de inferHandlerInput<T> et ProcedureArgs<T> (non-breaking pour la plupart)​

Ignorez ceci si ces types ne vous sont pas familiers

Utilisez plutôt inferProcedureInput<TProcedure> et TRPCProcedureOptions

Ajout de useSuspenseQueries()​

Voir useSuspenseQueries

https://github.com/trpc/trpc/pull/5226

Refonte des génériques internes (rarement breaking)​

Refonte des génériques internes pour améliorer la lisibilité (TODO : lien vers procedure builder)

React >=18.2.0 requis (rarement breaking)​

Consultez leur guide de migration : https://react.dev/blog/2022/03/08/react-18-upgrade-guide

NodeJS 18+ et navigateurs modernes requis (rarement breaking)​

Ajout de FormData, File, Blob et ReadableStream. NodeJS 18 est désormais requis (ces APIs sont supportées depuis longtemps dans les navigateurs).

  • Possibilité de passer une Promise dans le callback url lors des déplacements de serveurs

  • Nouvelle option lazy déconnectant automatiquement le websocket sans requêtes en attente

rawInput dans les middlewares devient getRawInput (rarement breaking)​

Bien que le fonctionnement interne reste inchangé, cela prépare une fonctionnalité très demandée : les content types autres que JSON.

Simplification des types et sorties .d.ts​

Les procédures n'émettent désormais que leur input & output - auparavant, elles incluaient l'objet context complet, créant une complexité inutile dans les .d.ts.

React Query peerDep passe en v5 (breaking) -​

L'essentiel à faire sera de remplacer de nombreuses occurrences de isLoading par isPending

Consultez leur guide de migration : https://tanstack.com/query/v5/docs/framework/react/guides/migrating-to-v5

Les exports nommés AbcProxyXyz ont été renommés en AbcXyz (non-breaking)​

Les noms avec "Proxy" existaient car v9 utilisait les noms AbcXyz. Ceux-ci ont été supprimés et les versions "proxy" ont été renommées avec les noms originaux, par exemple :

  • createTRPCClient était déprécié depuis v9 et est maintenant complètement supprimé. createTRPCProxyClient a été renommé en createTRPCClient. createTRPCProxyClient est maintenant marqué comme déprécié.

Helpers SSG (rarely breaking)​

  • createSSGHelpers était destiné à v9 et a maintenant été supprimé. L'équivalent v10 createProxySSGHelpers a été renommé en createSSGHelpers.

  • createProxySSGHelpers est maintenant déprécié mais reste aliasé vers createSSGHelpers pour la rétrocompatibilité.

  • Suppression du type exporté CreateSSGHelpersOptions

Le mode interop a été supprimé (rarely breaking) -​

Nous avons supprimé le mode interop de tRPC. Ce mode permettait une transition simplifiée entre v9 et v10. Il n'était pas destiné à être supporté à long terme et a donc été retiré.