メインコンテンツへスキップ
バージョン: 11.x

v10 から v11 への移行

非公式ベータ版翻訳

このページは PageTurner AI で翻訳されました（ベータ版）。プロジェクト公式の承認はありません。 エラーを見つけましたか？ 問題を報告 →

v10 から v11 への移行​

ヒント

ほとんどのユーザーにとって、移行は迅速かつ簡単に行えるはずです。

以下の3ステップで十分でない場合は、このドキュメント内の "rarely breaking" セクションを参照してください。

1. 新しいバージョンをインストール​

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. transformer を使用している場合、リンクを更新​

詳細は トランスフォーマーのリンクへの移動 を参照してください。

3. @trpc/react-query を使用している場合、@tanstack/react-query のバージョンを更新​

詳細は react-query-v5 を参照してください。

完全な逆時系列変更履歴​

新しい TanStack React Query 統合！ (非破壊的変更)​

tRPC の next リリースで、新しい TanStack React Query 統合が利用可能になりました！

Read the blog post for more information.

サーバー側からのサブスクリプション停止 (稀に破壊的変更)​

サーバー側からサブスクリプションを停止できるようになりました。これにより以下のような操作が可能です：

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;
    }
  }),
});

詳細は サブスクリプションのドキュメント を参照してください。

ルーターの遅延読み込みをサポート (非破壊的変更)​

詳細は ルーターの遅延読み込みドキュメント を参照してください。

これに伴い、内部メソッド callProcedure() の引数が { _def: AnyRouter['_def'] } パラメータから { router: AnyRouter } パラメータを受け取るように変更されました。

スタンドアロンアダプターでのカスタム basePath サポート (非破壊的変更)​

スタンドアロンアダプターが basePath オプションをサポートし、リクエストパスの先頭からベースパスを切り取るようになりました。

詳細は スタンドアロンアダプターのドキュメント を参照してください。

HTTP/2 サーバーのサポート追加 (非破壊的変更)​

HTTP/2 サーバーをサポートしました。これにより createHTTP2Handler および createHTTPServer 関数を使用して HTTP/2 サーバーを作成できます。

詳細は スタンドアロンアダプターのドキュメント を参照してください。

TRPCProcedureOptions を @trpc/client へ移動 (ほとんどの場合非破壊的)​

以前 @trpc/server から ProcedureOptions を使用していた場合、代わりに @trpc/client の TRPCProcedureOptions を使用する必要があります。

ネストされたデータへの Promise 埋め込みを許可 (非破壊的変更)​

httpBatchStreamLink 使用時にネストされたデータへの Promise 埋め込みが許可され、以下のような操作が可能になりました：

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(),
    };
  }),
});

reconnectAfterInactivityMs を sse.client へ移動 (非破壊的変更)​

HTTP サブスクリプションリンクの改善 セクションと関連ドキュメントを更新。

TypeScript バージョン >=5.7.2 が必須に (非破壊的変更)​

tRPC では TypeScript バージョン 5.7.2 以上が必須になりました。この変更は バグレポート を受け、将来的な対応を考慮して行われました。

サポートされていないTypeScriptバージョンでtRPCをインストールしようとすると、インストール中にpeer dependencyエラーが発生します。

エディターでany型が表示される場合、エディターがプロジェクトのpackage.jsonにインストールされた正しいTypeScriptバージョンを使用していない可能性があります。これを修正するには、エディターをプロジェクトのTypeScriptバージョンを使用するように設定する必要があります。

VSCodeユーザーの場合、.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
}

experimental.sseSubscriptionsをsseに移動（非破壊的変更）​

initTRPC.create()関数内のexperimental.sseSubscriptionsオプションがsseに変更されました。

古くなった接続の検出と復旧をサポートするようになりました：

サーバー側では、接続を維持するためのping間隔を設定できます：

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,
    },
  },
});

将来的にはデフォルトのping間隔とタイムアウト設定を追加する可能性がありますが、現時点では未定です。Discordの🎏-rfc-streamingチャンネルでフィードバックをお待ちしています。

詳細はhttpSubscriptionLinkドキュメントをご覧ください。

retryLinkの導入（非破壊的変更）​

retryLink - 失敗した操作をリトライできます

useSubscriptionの改善（非破壊的変更）​

  • useSubscriptionフックを使用した手続きのサブスクリプションでは、サブスクリプションと接続のステータス情報が返されるようになりました

  • httpSubscriptionLink使用時にポリフィルを適用可能に

サブスクリプション手続きの出力タイプがAsyncGeneratorに変更（非破壊的変更）​

v11で非同期ジェネレーターを使用したサブスクリプションを実装している場合、型推論方法に互換性の問題が生じる可能性があります。

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;

この変更はライブラリの将来の更新との互換性を確保し、サブスクリプションのAsyncGeneratorでreturn型を使用できるようにするために行われました。

詳細はサブスクリプションのドキュメントをご覧ください。

サブスクリプションでの出力バリデータのサポート追加（非破壊的変更）​

詳細はサブスクリプションのドキュメントをご覧ください。

Observableを返すサブスクリプションの非推奨化（非破壊的変更）​

サブスクリプションで非同期ジェネレーター関数を返す機能をサポートし、以前にhttpSubscriptionLinkを追加しました。

非同期ジェネレーター関数を使用したサブスクリプションの実装方法はサブスクリプションのドキュメントをご覧ください。

AbortControllerEsqueポリフィルの削除（稀に破壊的変更）​

tRPCからAbortControllerEsqueポリフィルを削除しました。古いブラウザをサポートする必要がある場合はabortcontroller-polyfillなどのポリフィルを使用してください。

Server-sent events (SSE)のサポート（非破壊的変更）​

サブスクリプションでSSEをサポートするようになりました。これによりアプリケーションでリアルタイム更新を得るためにWebSocketサーバーを立ち上げる必要がなくなり、接続が切断された場合にクライアントが自動的に再接続して復旧できます。

👉 詳細はhttpSubscriptionLinkドキュメントをご覧ください。

HTTP経由のストリーミングレスポンスのサポート（非破壊的変更）​

httpBatchStreamLinkを使用してミューテーションとクエリのストリーミングをサポートするようになりました。

これは、クエリとミューテーションのリゾルバーが、yieldを含むAsyncGeneratorになるか、後で遅延可能なPromiseを返せることを意味します。これにより、WebSocketを使用せずにHTTP経由でストリーム応答を利用できます。

この機能についてフィードバックをお待ちしています！ぜひお試しいただき、Discordの🎏-rfc-streamingチャンネルでご意見をお聞かせください。

👉 詳細はhttpBatchStreamLinkのドキュメントをご覧ください

resolveHTTPRequestがFetch APIを使用するresolveRequestに置き換えられました（まれに破壊的変更）​

resolveHTTPRequest関数は、Fetch API（Request/Response）を使用するresolveRequestに置き換えられました。

これはHTTPアダプターにとって破壊的変更ですが、通常のユーザーには影響しません。

アダプターを構築している場合は、コード内の実装例を参考にし、Discordで気軽に質問してください。

TRPCRequestInfoが更新されました（まれに破壊的変更）​

入力はプロシージャが必要とする際に遅延評価されるようになりました。つまり、tRPCがcreateContextを呼び出す時点では入力値とプロシージャの型が利用できなくなっています。

info.calls[index].getRawInput()を呼び出すことで入力値にアクセスできます。

実験的なform-dataサポートがすべて置き換えられました（まれに破壊的変更）​

これは実験的なformdata機能を使用していた場合のみ影響します

  • experimental_formDataLink → httpLinkを使用してください

  • experimental_parseMultipartFormData → 不要になりました

  • experimental_isMultipartFormDataRequest → 不要になりました

  • experimental_composeUploadHandlers → 不要になりました

  • experimental_createMemoryUploadHandler → 不要になりました

  • experimental_NodeOnDiskFile と experimental_createFileUploadHandler → 初回リリースではサポートされていません。ディスク保存が必要な場合はイシューを作成してください

  • experimental_contentTypeHandlers → 不要になりました（コミュニティから新規データタイプの要望があれば再実装する可能性あり）

新しいアプローチはexamples/next-formdataで確認できます

Procedure._def._output_in / Procedure._def._input_in が Procedure._def.$types に移動しました（非破壊的変更）​

これはtRPC内部の破壊的変更ですが、通常のユーザーには影響しません。

コードで直接Procedure._def._output_inやProcedure._def._input_inを使用していない限り、対応は不要です。

明示的なContent-Typeチェックの追加（非破壊的変更）​

POSTリクエスト時にContent-Typeヘッダーの明示的なチェックが追加されました。期待されるContent-Typeと一致しない場合、415 Unsupported Media Typeエラーが返されます。

tRPCクライアントは自動的にcontent-typeヘッダーを送信するため、手動でtRPCを呼び出す場合にのみ影響する可能性があります。

メソッドオーバーライドのサポート追加（まれに破壊的変更）​

プロシージャのHTTPメソッドを常にPOSTで送信するようにオーバーライドできるようになりました。これによりURLの最大長制限などの問題を回避できます。

#3910 に対応

双方向無限クエリのサポート追加（非破壊的変更）​

useInfiniteQuery()を参照

inferProcedureBuilderResolverOptions<T>ヘルパーの追加 (破壊的変更なし)​

手続きビルダーのリゾルバオプションを推論するヘルパーを追加。異なる手続きで再利用可能な関数を作成する場合に便利です。

使用方法の参考例としてこちらのテストを参照

トランスフォーマーがリンクに移動 (破壊的変更) -​

TypeScriptがこの移行をガイドします

データトランスフォーマーを使用している場合のみ適用されます

データトランスフォーマーの設定をtRPCクライアント初期化時からlinks配列内に移動:

トランスフォーマーを使用する場合、HTTPリンクがある場所では必ずtransformer: superjsonを追加:

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
});

@trpc/nextのSSRモードでssr: trueのプレパスヘルパーが必要に (稀に破壊的変更)​

https://github.com/trpc/trpc/issues/5378 の問題を修正するため。この機能を使用していない場合でもreact-domが常にインポートされる問題を解決

SSRドキュメントを参照

短縮形ルーター定義のサポート追加 (破壊的変更なし)​

ルーターのマージを参照

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(() => '...'),
  }),
});

inferHandlerInput<T>とProcedureArgs<T>の削除 (ほとんどの場合破壊的変更なし)​

これらの型が意味をなさない場合やコードベースで使用していない場合は無視してください

代わりにinferProcedureInput<TProcedure>とTRPCProcedureOptionsを使用

useSuspenseQueries()の追加​

useSuspenseQueriesを参照

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

内部ジェネリックのリファクタリング (稀に破壊的変更)​

内部ジェネリックをリファクタリングし可読性を向上 (TODO: 手続きビルダーのソースリンク追加)

Reactの要件が>=18.2.0に (稀に破壊的変更)​

移行ガイドを確認: https://react.dev/blog/2022/03/08/react-18-upgrade-guide

NodeJS 18+とモダンブラウザが必須に (稀に破壊的変更)​

FormData、File、Blob、ReadableStreamの使用を追加。NodeJS 18が必須となりましたが、ブラウザでは長年サポートされています

wsLinkの改良 (軽微)​

  • デプロイ中にサーバー位置が切り替わる場合にurlコールバックでPromiseを渡せる機能

  • 保留中のリクエストがない場合にWebSocketを自動切断する新しいlazyオプション追加

ミドルウェアのrawInputがgetRawInputに (稀に破壊的変更)​

内部的にはまだ変更ありませんが、tRPCで強く要望されていた機能であるJSON以外のコンテンツタイプのサポート実装に向けた準備

型と.d.ts出力の簡素化​

ルーター内の手続きは入力と出力のみを出力するよう変更。以前はすべての手続きに完全なコンテキストオブジェクトが含まれていたため、.d.tsなどで不必要な複雑さが生じていました

React QueryのpeerDepがv5に (破壊的変更) -​

主に必要な変更は、多数の isLoading を isPending に置き換えることです

移行ガイドを参照してください: https://tanstack.com/query/v5/docs/framework/react/guides/migrating-to-v5

エクスポート名 AbcProxyXyz が AbcXyz に変更されました (非破壊的変更)​

プロキシ名はv9で AbcXyz 名を使用していたため存在していましたが、これらは削除され、プロキシ名は非プロキシ名に変更されました。例:

  • createTRPCClient はv9で非推奨となり、現在は完全に削除されました。createTRPCProxyClient は createTRPCClient に名称変更されました。createTRPCProxyClient は現在非推奨とマークされています

SSGヘルパー (稀に破壊的変更)​

  • v9用の createSSGHelpers は削除されました。v10相当の createProxySSGHelpers は createSSGHelpers に名称変更されました

  • createProxySSGHelpers は現在非推奨ですが、後方互換性のために createSSGHelpers としてエイリアスされています

  • エクスポート型 CreateSSGHelpersOptions を削除

interopモードが削除されました (稀に破壊的変更) -​

tRPCから interop モードを削除しました。これはv9からv10への移行期間を容易にするためのモードでしたが、長期的なサポートを意図したものではなく、現在は削除されています