# @convex-dev/react-query 中文文档

规范地址：https://npmcn.com/package/%40convex-dev/react-query/

版本：0\.1\.0
npm 元数据更新时间：2026-10-07T00:51:51.449Z
中文译文更新时间：2026-11-10T17:40:42.452Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40convex-dev/react-query
原文对照：https://npmcn.com/package/%40convex-dev/react-query/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：106 kB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：convex ^1\.29\.3，@tanstack/react-query ^5\.0\.0
- 首次发布：2024-07-19T00:27:26.696Z
- 最新版本发布：2025-11-20T03:41:16.310Z
- 近 30 天下载量：860304（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 1 个）

## 中文简介

而不是投票,你订阅 接收更新 从服务器端查询功能 在康维克斯部署。 Convex是一个带有服务器侧(db-side?)的数据库. 类似存储程序)的功能,可以被动更新.

## 安装

```sh
npm install @convex-dev/react-query
```

也可以使用：`pnpm add @convex-dev/react-query`、`yarn add @convex-dev/react-query`、`bun add @convex-dev/react-query`

## README

# @ convex-dev/ react-query (英语)

而不是投票,您要通过服务器端查询获得更新 用于Convex部署。 Convex 是带有服务器侧的数据库 (db -边? 类似存储程序)的功能,可以被动更新.

将所有相关订阅的新结果推给客户 同时更新数据,所以数据永远不僵化,没有必要打电话 `queryClient.invalidateQueries()`。 。 。 .

## 设置

见 [./src/例.tsx (中文(简体) )](https://npmcn.com/package/%40convex-dev/react-query/src/example.tsx) 对于一个真正的例子。 将军 样式 :

1.  创建 Convex 客户端和 Convex 查询客户端 。 设置全局默认值 `queryKeyHashFn` 改为 `convexQueryClient.hashFn()` 财务报告和审定财务报表 `queryFn` 改为 `convexQueryClient.queryFn()`连接 Convex 查询中心到反应 出问入道.

```ts
const convexClient = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);
const convexQueryClient = new ConvexQueryClient(convexClient);
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      queryKeyHashFn: convexQueryClient.hashFn(),
      queryFn: convexQueryClient.queryFn(),
    },
  },
});
convexQueryClient.connect(queryClient);
```

2.  使用 `useQuery()` 与 `convexQuery` 选项厂函数调用 a 一个 `api` 导入对象 `../convex/_generated/server` 和论点 用于此查询功能。 这两个构成查询密钥.

```ts
const { isPending, error, data } = useQuery({
  ...convexQuery(api.repos.get, { repo: "made/up" }),
  gcTime: 10000, // unsubscribe after 10s of no use
});
```

`staleTime` 设置为 `Infinity` 数据从不僵化,而是 服务器上查询结果更新时主动更新 。 (见 [tkdodo 的贴文](https://tkdodo.eu/blog/using-web-sockets-with-react-query#increasing-staletime) 更多关于这个) 如果你喜欢,自定义 `gcTime` 时间长度a 查询订阅毕竟应该保持活动 `useQuery()` 钩子用它 已卸载.

如果你需要使用 Convex 动作作为查询, 它不会是反应; 你会得到 react Query 中的所有普通工具来进行回溯.

# 使用 TanStack 查询的区别 `fetch`

从服务器上推出新的查询结果, 所以 a `staleTime` 联 合 国 `Infinity` 应当使用.

您的应用程序将一直订阅到查询 `gcTime` 已经过去了。 调色板 通常使用至少一个值的交换方式 几秒钟.

# 示例

要运行这个例子:

-   `npm install`
-   `npm run dev`

# 变异和行动

如果你把应用包在 `ConvexProvider` 你会使用螺旋钩 喜欢 `useConvexMutation` 财务报告和审定财务报表 `useConvexAction`· :

```tsx
<ConvexProvider client={convex}>
  <QueryClientProvider client={queryClient}>
    <App />
  </QueryClientProvider>
</ConvexProvider>
```

您可以直接使用此变异函数, 也可以在 TanStack 查询中将其包裹 `useMutation`数字 :

```ts
const mutationFn = useConvexMutation(api.board.createColumn);
const { mutate } = useMutation({ mutationFn });
```

```ts
const { mutate } = useMutation({
  mutationFn: useConvexAction(api.time.getTotal),
});
```

# 认证

**说明:** 例应用包括基本 Convex Auth 执行 参考文献.

TanStack Query 并不是关于认证; 认证代码可能是一个元素 查询密钥。 用Convex不用再加一个 auth 代码的密钥; auth 是所有 Convex 查询和 当认证信息发生变化时,这些查询将被重审.

Convex auth 通常是通过 JWT 完成的: 如果 打电话前请 `convexReactClinet.setAuth()` 具有 提供标志.

Auth 设置看起来就像推荐在 [对流文件](https://docs.convex.dev/auth),使用 使用本地对流钩. 对于办事员来说,这看起来可能是这样的:a `ClerkProvider` 用于认证, a `ConvexProviderWithClerk` 对于对流客户端,和 a `QueryClient`。 。 。 .

```
<ClerkProvider publishableKey="pk_test_...">
  <ConvexProviderWithClerk client={convex} useAuth={useAuth}>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </ConvexProviderWithClerk>
</ClerkProvider>
```

见 [Convex Auth 文档](https://docs.convex.dev/auth) 用于设置指令.

# 开始

-   认证
-   发送查询
-   清除/ 未订阅使用效果; 热重装入可能不是 工作权利

# 捐款

复制后, 重播运行 `npm i` 以安装依赖。 此软件包使用 [hy](https://github.com/isaacs/tshy) 发布无害环境管理。 如果有需要的话 对于一个 CJS 构建, 我们可以在“ dialects” 部分添加“ cjs ” 那个包裹 json.

要发布 alpha 版本, 请在 package.json 中将版本更新为某种内容 喜欢 `0.0.0-alpha.1` 运行 `just rush-pnpm publish --tag alpha`。 。 。 .

要发布定期发布, 将版本更新为 package.json 到某样东西 喜欢 `0.1.2` 运行 `just rush-pnpm publish`。 。 。 .

## 常见问题

### @convex-dev/react-query 是什么？

而不是投票,你订阅 接收更新 从服务器端查询功能 在康维克斯部署。 Convex是一个带有服务器侧\(db-side?\)的数据库\. 类似存储程序\)的功能,可以被动更新\.

### 如何安装 @convex-dev/react-query？

在项目目录运行 npm install @convex-dev/react-query，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：convex（^1\.29\.3）、@tanstack/react-query（^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @convex-dev/react-query 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @convex-dev/react-query 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @convex-dev/react-query 可以商用吗？

@convex-dev/react-query 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @convex-dev/react-query 的下载量有多少？

根据 npm 官方下载统计，@convex-dev/react-query 在 2026/10/11 – 2026/11/09 这 30 天内被下载 860,304 次，日均约 28,677 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @convex-dev/react-query 还在维护吗？

最新版本 0\.1\.0 发布于 2025/11/20（11 个月前）；至今共发布 10 个版本，其中过去 12 个月发布了 1 个；首次发布于 2024/07/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。