# @daviddios/xtrpc 中文文档

规范地址：https://npmcn.com/package/%40daviddios/xtrpc/

版本：1\.1\.0
npm 元数据更新时间：2025-12-16T12:34:59.193Z
中文译文更新时间：2026-11-11T15:57:19.435Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40daviddios/xtrpc
原文对照：https://npmcn.com/package/%40daviddios/xtrpc/?lang=original
项目主页：https://github.com/dios-david/xtrpc#readme
源码仓库：https://github.com/dios-david/xtrpc

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

- 包体积（解压后）：44.7 kB，18 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2025-12-16T11:08:27.887Z
- 最新版本发布：2025-12-16T12:34:58.808Z
- 近 30 天下载量：14777（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

导出您的 tRPC 路由器, 以大规模改善语言服务器的性能和/或让用户从打入的 SDK 中消耗您的 API

## 安装

```sh
npm install @daviddios/xtrpc
```

也可以使用：`pnpm add @daviddios/xtrpc`、`yarn add @daviddios/xtrpc`、`bun add @daviddios/xtrpc`

## README

# XXTRPC 函数

从您的 tRPC 路由器导出干净、轻量级类型Script

> **叉子为 [@algora/xtrpc (英语)](https://github.com/algoravioli/xtrpc)** - 改进性能和tRPC 11兼容性

## 有什么问题吗?

假设你已经建造了tRPC API服务器,想在您前端的app中使用这些类型(或与其他项目共享). 明显的解决方案是用 TypeScript 的声明文件生成导出类型 `tsc`。 。 。 .

但问题在于:

**您的类型文件变得庞大**

类型脚本生成一个 `.d.ts` 文档,它包括 _所有的东西_ 您的程序参考 - 不仅您实际需要的 API 输入和输出,而且还:

-   内部公用事业类型
-   数据库模型
-   辅助功能
-   每一种依赖的每个依赖

您的类型文件在大小上会爆炸,尽管消费者只需要知道"这里有程序名,这里有寄出,这里有你得到的"

**你的内脏漏出**

更糟的是,你的TRPC `Context` 类型(可能包含数据库连接、认证状态和内部服务等内容)也会被导出。 那是个安全隐患 你在揭露应该保密的实施细节.

**一切都会慢下来的**

所有这些额外类型意味着你的IDE必须更加努力地工作. 自动完成需要一秒钟 现在需要30 -60秒。 你的编辑开始感到迟钝。 类型检查爬行.

## XTRPC 如何解决它

xTRPC 在生成类型文件前取出您的路由器并清理它 :

1.  **删除执行** - 从程序和中间软件中剥去所有函数体,这样它们所使用的类型就不会最终出现在输出中
2.  **隐藏上下文** - 替换你的 `Context` 类型为 `any`,保持内部类型
3.  **只导出 API 形状** - 生成一个只有消费者需要的最小类型文件:程序名称、投入和产出

结果? 一个小而快的类型的文件,它保持您的执行细节的隐私,同时保持完整的类型安全.

## 安装

```bash
npm i -D @daviddios/xtrpc
```

## 快开始

### 1\. 创建配置文件

创建 `xtrpc.config.json` 在您的工程根中 :

```json
{
  "input": {
    "appRouterFilePath": "src/server/router.ts"
  }
}
```

见 [配置](https://npmcn.com/package/%40daviddios/xtrpc/#readme-configuration) 用于所有可用的选项.

### 2\. 生成您的类型

```bash
npx xtrpc
```

这创造了 `types/api.d.ts` 包含您的清洁路由器类型.

### 3\. 使用生成的类型

```ts
// Export the generated type
export { type AppRouter } from "my-server/types/api";

// Use it in your client
export const client = createTRPCClient<AppRouter>({
  // ... your config
});
```

就这样! 你的客户现在完全安全了 没有任何行李.

## 配置

创建 `xtrpc.config.json` 在您的项目根中。 仅 `input.appRouterFilePath` 需要 - 所有其它事物都有合理的默认值.

### 示例配置文件

```json
{
  "$schema": "node_modules/@daviddios/xtrpc/dist/xtrpc.schema.json", // Add this to your config file to get autocomplete and validation in your IDE
  "input": {
    "tsconfigPath": "tsconfig.json",
    "appRouterFilePath": "src/server/router.ts",
    "appRouterTypeName": "AppRouter",
    "routerPaths": ["src/server/**/*.ts", "!src/server/**/*.test.ts"]
  },
  "output": {
    "filePath": "types/api.d.ts"
  },
  "verbose": false
}
```

### 示例应用程序路由器

```ts
// This file contains your app router, the path of this file
// should be set in the configuration as `input.appRouterFilePath`
import { initTRPC } from '@trpc/server';

const t = initTRPC.create();

export const appRouter = t.router({
    getUsers: t.procedure
        .output(...)
        .query(...)
});

// This is the exported type of your app router, the name of this
// should be set in the configuration as `input.appRouterTypeName`
export type AppRouter = typeof appRouter;
```

### 可用选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `input.tsconfigPath` | 字符串 | `"tsconfig.json"` | 在哪里找到您的类型脚本配置 |
| `input.appRouterFilePath` | 字符串 | **(必须)** | 包含您的应用程序路由器的文件 |
| `input.appRouterTypeName` | 字符串 | `"AppRouter"` | 您导出的程序路由器类型的名称 |
| `input.routerPaths` | 字符串 \[\] | \- 说吧 | 搜索路由器和程序的可选 glob 模式 - 只有这些路径下的文件会被包含, 指定此模式可使 xtrpc 更快 |
| `output.filePath` | 字符串 | `"types/api.d.ts"` | 在哪里保存生成的类型 |
| `verbose` | 布尔 | `false` | 运行时显示详细输出 |

## 何时使用

**单曲**

您有服务器软件包和客户端软件包需要共享类型,但您不想将它们与执行细节合并.

**公共 APIs**

您正在构建一个公开的 API 并想要给用户一个打入的 SDK 而不暴露您的数据库计划或内部架构 .

**大型路由器**

您的 tRPC 路由器已经发展到足够大 以至于您的 IDE 在工作时明显缓慢 .

**安全意识项目**

您需要确保敏感类型( 自动上下文, 数据库模型, 内部服务) 永远不会离开您的服务器代码库 .

## 如何运作

xTRPC 用途 [ts-形态](https://github.com/dsherret/ts-morph) (使用 TypeScript 代码的工具) 到 :

1.  装入包含您路由器的文件
2.  查找您的路由器类型定义
3.  改变它:
    -   替换您的 `Context` 类型为 `any`
    -   将中间软件机构替换为简单的通过功能
    -   删除程序执行
4.  将清理后的版本保存为 `.d.ts` 文件

您的实际服务器代码没有被触碰 - 只有生成的类型文件被修改 .

## 已知的限制

**跳转到定义生成文件**

使用时 _"去定义"_ 在你的IDE中,它会带给你生成的 `.d.ts` 文件,而不是您实际的源代码。 这可能通过生成声明地图来固定, 但我们还没有测试过.

**需要手动配置**

您需要确切的告诉 xTRPC 您的路由器文件在哪里 - 它不会试图自动找到它 。 这是故意的(因为性能原因),但确实意味着有些手工设置.

## 捐款

找到窃听器了吗? 有主意吗? 打开一个问题或拉动请求 [GitHub 图像](https://github.com/dios-david/xtrpc)。 。 。 .

## 许可证

麻省理工学院Algora PBC.

麻省理工学院

## 鸣谢

这个项目是一个叉子 [@algora/xtrpc (英语)](https://github.com/algoravioli/xtrpc)为改进业绩而重建的TRPC 11支助。 感谢最初的作者对该问题的创新办法.

## 常见问题

### @daviddios/xtrpc 是什么？

导出您的 tRPC 路由器, 以大规模改善语言服务器的性能和/或让用户从打入的 SDK 中消耗您的 API

### 如何安装 @daviddios/xtrpc？

在项目目录运行 npm install @daviddios/xtrpc，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 xtrpc，可以用 npx xtrpc 直接运行。

### @daviddios/xtrpc 支持 TypeScript 吗？

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

### @daviddios/xtrpc 支持 ESM 还是 CommonJS？

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

### @daviddios/xtrpc 可以商用吗？

@daviddios/xtrpc 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @daviddios/xtrpc 的下载量有多少？

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

### @daviddios/xtrpc 还在维护吗？

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