用途与定位
TypeScript Expert 是一个面向 TypeScript 与 JavaScript 开发的高级专家技能,围绕类型级编程、性能优化、monorepo 管理、迁移策略和现代工具链提供实践性指导。它面向真实项目问题,而不是抽象的语言教程。
主要能力
类型系统
- 品牌类型(Branded Types)用于领域建模,避免原始类型混用,如将 UserId、OrderId 区分为不同名义类型。
- 高级条件类型与递归类型操作,例如 DeepReadonly、模板字面量类型构建类型安全事件系统。
- 类型推断技巧,包括使用
satisfies做约束校验(TS 5.0+)、as const获取字面量类型。 - 类型测试:推荐 Vitest 的
expectTypeOf,适用于发布库、复杂泛型函数、类型级工具和 API 契约。
性能优化
- 使用
npx tsc --extendedDiagnostics --incremental false诊断类型检查耗时。 - 常见修复:用接口替代类型交叉、拆分超大联合类型(>100 成员)、避免循环泛型约束、用类型别名打断递归。
- 构建侧建议:
skipLibCheck: true、incremental: true配合.tsbuildinfo、精确配置 include/exclude、monorepo 使用带composite: true的项目引用。
问题排查
- 针对“inferred type cannot be named”、“Excessive stack depth comparing types”、缺少类型声明等常见错误给出修复优先级。
- 模块解析:检查 moduleResolution 与打包工具是否匹配、baseUrl 与 paths 对齐、monorepo 的 workspace 协议、清理缓存。
- 指出 TypeScript paths 仅在编译期生效,运行时需配合 ts-node 的 tsconfig-paths、loader 或预编译方案。
- 调试:tsx/ts-node 的 inspect 模式、
tsc --traceResolution、tsc --generateTrace配合 analyze-trace、增大 Node 内存上限。
迁移与工具链
- JavaScript 转 TypeScript 的增量迁移:先开启 allowJs 与 checkJs,逐步重命名文件、逐文件补类型、逐个启用严格选项;可选 ts-migrate、typesync 辅助。
- 工具迁移决策表:ESLint+Prettier 转 Biome、TSC 做 lint 转纯类型检查、Lerna 转 Nx/Turborepo、CJS 转 ESM,并标注迁移成本。
- Biome 与 ESLint 的取舍:Biome 速度快、单工具完成 lint+format、TypeScript 优先,但规则较少且暂不支持类型感知 lint;复杂自定义规则、Vue/Angular 场景建议保留 ESLint。
Monorepo 管理
- Turborepo 适合结构简单、追求速度、包数量少于 20 的场景;Nx 适合复杂依赖、需要可视化和插件,包数量超过 50 时通常表现更好。
- 给出根 tsconfig 的项目引用示例,包含 references、composite、declaration、declarationMap。
最佳实践与代码审查
- 默认严格模式配置示例:strict、noUncheckedIndexedAccess、noImplicitOverride、exactOptionalPropertyTypes、noPropertyAccessFromIndexSignature。
- ESM 优先:package.json 设置
"type": "module"、必要时使用 .mts、现代工具配置moduleResolution: bundler、CJS 用动态 import。 - 代码审查清单覆盖类型安全、最佳实践、性能、模块系统、错误处理、代码组织六个方面。
使用方式
技能被调用后会先做项目探测:确认 tsc 与 node 版本,解析 package.json 识别工具链(biome、eslint、prettier、vitest、jest、turborepo、nx),检测 monorepo 标记文件(pnpm-workspace.yaml、lerna.json、nx.json、turbo.json)。随后匹配现有导入风格与 paths 配置,优先使用项目已有脚本,再定位问题类别并给出方案。验证阶段使用一次性命令:npm run -s typecheck || npx tsc --noEmit、npm test -s || npx vitest run --reporter=basic --no-watch,必要时才运行构建,避免 watch/serve 长驻进程。
适用范围与限制
当问题涉及打包器内部机制时应转交 typescript-build-expert;复杂 ESM/CJS 迁移或循环依赖分析转交 typescript-module-expert;类型性能剖析或编译器内部转交 typescript-type-expert。该技能仅适用于明确匹配上述范围的任务,输出不能替代针对具体环境的验证、测试或专家审查;缺少必要输入、权限、安全边界或成功标准时应先询问澄清。