从经典 React 客户端迁移

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

迁移有几种可选方案，这个新版库相比经典客户端有显著差异，我们不期望一次性完成迁移。您可能需要结合多种方式...

Codemod 迁移方案

信息

当前 codemod 仍在开发中，亟需社区协助完善。若您有意贡献，请参阅 Julius 的评论。

我们正在开发 codemod 工具帮助迁移现有代码库。目前工具已可用，但需要您的反馈和贡献来优化。由于 codemod 开发难度较高，我们期待您协助提升其效果。

运行升级 CLI：

sh
npx @trpc/upgrade

sh
npx @trpc/upgrade

提示出现时，请选择 Migrate Hooks to xxxOptions API 和 Migrate context provider setup 转换项。

渐进式迁移

新版与经典客户端完全兼容，可在同一应用中并存。 这意味着您可以在新功能中使用新版客户端，并根据需要逐步迁移现有代码。关键是两者 Query Key 完全一致，因此混合使用时仍可依赖 TanStack Query 的缓存机制。

迁移查询

经典查询示例如下：

tsx
import { trpc } from './trpc';
function Users() {
  const greetingQuery = trpc.greeting.useQuery({ name: 'Jerry' });
  // greetingQuery.data === 'Hello Jerry'
}

tsx
import { trpc } from './trpc';
function Users() {
  const greetingQuery = trpc.greeting.useQuery({ name: 'Jerry' });
  // greetingQuery.data === 'Hello Jerry'
}

现改为：

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

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

迁移失效操作及其他 QueryClient 用法

经典查询示例如下：

tsx
import { trpc } from './trpc';
function Users() {
  const utils = trpc.useUtils();
  async function invalidateGreeting() {
    await utils.greeting.invalidate({ name: 'Jerry' });
  }
}

tsx
import { trpc } from './trpc';
function Users() {
  const utils = trpc.useUtils();
  async function invalidateGreeting() {
    await utils.greeting.invalidate({ name: 'Jerry' });
  }
}

现改为：

tsx
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { useTRPC } from './trpc';
function Users() {
  const trpc = useTRPC();
  const queryClient = useQueryClient();
  async function invalidateGreeting() {
    await queryClient.invalidateQueries(
      trpc.greeting.queryFilter({ name: 'Jerry' }),
    );
  }
}

tsx
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { useTRPC } from './trpc';
function Users() {
  const trpc = useTRPC();
  const queryClient = useQueryClient();
  async function invalidateGreeting() {
    await queryClient.invalidateQueries(
      trpc.greeting.queryFilter({ name: 'Jerry' }),
    );
  }
}

所有 QueryClient 用法都遵循此原则，现在您可直接参考 TanStack 文档，无需使用 tRPC 的 useUtils。

迁移变更操作

经典变更操作示例如下：

tsx
import { trpc } from './trpc';
function Users() {
  const createUserMutation = trpc.createUser.useMutation();
  createUserMutation.mutate({ name: 'Jerry' });
}

tsx
import { trpc } from './trpc';
function Users() {
  const createUserMutation = trpc.createUser.useMutation();
  createUserMutation.mutate({ name: 'Jerry' });
}

现改为：

tsx
import { useMutation } from '@tanstack/react-query';
import { useTRPC } from './trpc';
function Users() {
  const trpc = useTRPC();
  const createUserMutation = useMutation(trpc.createUser.mutationOptions());
  createUserMutation.mutate({ name: 'Jerry' });
}

tsx
import { useMutation } from '@tanstack/react-query';
import { useTRPC } from './trpc';
function Users() {
  const trpc = useTRPC();
  const createUserMutation = useMutation(trpc.createUser.mutationOptions());
  createUserMutation.mutate({ name: 'Jerry' });
}