XXTRPC 函数
从您的 tRPC 路由器导出干净、轻量级类型Script
叉子为 @algora/xtrpc (英语) - 改进性能和tRPC 11兼容性
有什么问题吗?
假设你已经建造了tRPC API服务器,想在您前端的app中使用这些类型(或与其他项目共享). 明显的解决方案是用 TypeScript 的声明文件生成导出类型 tsc。 。 。 .
但问题在于:
您的类型文件变得庞大
类型脚本生成一个 .d.ts 文档,它包括 所有的东西 您的程序参考 - 不仅您实际需要的 API 输入和输出,而且还:
- 内部公用事业类型
- 数据库模型
- 辅助功能
- 每一种依赖的每个依赖
您的类型文件在大小上会爆炸,尽管消费者只需要知道"这里有程序名,这里有寄出,这里有你得到的"
你的内脏漏出
更糟的是,你的TRPC Context 类型(可能包含数据库连接、认证状态和内部服务等内容)也会被导出。 那是个安全隐患 你在揭露应该保密的实施细节.
一切都会慢下来的
所有这些额外类型意味着你的IDE必须更加努力地工作. 自动完成需要一秒钟 现在需要30 -60秒。 你的编辑开始感到迟钝。 类型检查爬行.
XTRPC 如何解决它
xTRPC 在生成类型文件前取出您的路由器并清理它 :
- 删除执行 - 从程序和中间软件中剥去所有函数体,这样它们所使用的类型就不会最终出现在输出中
- 隐藏上下文 - 替换你的
Context类型为any,保持内部类型 - 只导出 API 形状 - 生成一个只有消费者需要的最小类型文件:程序名称、投入和产出
结果? 一个小而快的类型的文件,它保持您的执行细节的隐私,同时保持完整的类型安全.
安装
npm i -D @daviddios/xtrpc
快开始
1. 创建配置文件
创建 xtrpc.config.json 在您的工程根中 :
{
"input": {
"appRouterFilePath": "src/server/router.ts"
}
}
见 配置 用于所有可用的选项.
2. 生成您的类型
npx xtrpc
这创造了 types/api.d.ts 包含您的清洁路由器类型.
3. 使用生成的类型
// 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 需要 - 所有其它事物都有合理的默认值.
示例配置文件
{
"$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
}
示例应用程序路由器
// 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-形态 (使用 TypeScript 代码的工具) 到 :
- 装入包含您路由器的文件
- 查找您的路由器类型定义
- 改变它:
- 替换您的
Context类型为any - 将中间软件机构替换为简单的通过功能
- 删除程序执行
- 替换您的
- 将清理后的版本保存为
.d.ts文件
您的实际服务器代码没有被触碰 - 只有生成的类型文件被修改 .
已知的限制
跳转到定义生成文件
使用时 "去定义" 在你的IDE中,它会带给你生成的 .d.ts 文件,而不是您实际的源代码。 这可能通过生成声明地图来固定, 但我们还没有测试过.
需要手动配置
您需要确切的告诉 xTRPC 您的路由器文件在哪里 - 它不会试图自动找到它 。 这是故意的(因为性能原因),但确实意味着有些手工设置.
捐款
找到窃听器了吗? 有主意吗? 打开一个问题或拉动请求 GitHub 图像。 。 。 .
许可证
麻省理工学院Algora PBC.
麻省理工学院
鸣谢
这个项目是一个叉子 @algora/xtrpc (英语)为改进业绩而重建的TRPC 11支助。 感谢最初的作者对该问题的创新办法.