node-typescript

node-typescript

生成的 TypeScript 配置应当明确、严格，并符合代码的使用方式。此技能解决的问题：模型照搬 tsconfig，而其中的隐式默认值会随 TypeScript 主版本变化；为未打包的 Node 包选择 bundler 解析方式（导致使用者无法正常使用）；以及在大型代码库中一次性开启严格模式，导致改动无法审查。

不适用场景

• Lint/格式规则 → node-lint。
• 打包和 exports 映射／使用者类型解析 → node-packaging （此技能负责声明文件的生成；打包技能负责使用者如何解析声明文件）。
• 测试运行器的 TS 支持 → node-testing。

工作流

1. 首先遵循配置显式原则。 绝不依赖生成的默认值或版本默认值——TypeScript 主版本曾多次更改这些值。应按照 references/tsconfig-playbook.md 中的配置块，明确写出每个重要选项。
2. 根据使用方式选择配置，而不是追逐潮流：
   • 已发布／未打包的 Node 包 → 选择 nodenext 系列的 module／moduleResolution；启用 verbatimModuleSyntax；设置 declaration + declarationMap；在 API 表面允许的情况下启用 isolatedDeclarations（支持并行且与工具无关的声明文件生成）。
   • 打包的应用代码 → 使用 bundler 解析方式并设置 noEmit（由打包器生成文件）。
3. 加入门禁：将 tsc --noEmit（或项目引用使用 -b）设为脚本和 CI 任务（接线 → node-ci）。
4. 现有代码库的严格化应逐步推进，而不是一次性切换：先评估错误范围，再逐步启用选项（逐个选项或逐个目录），并通过禁止新增错误的规则保持 CI 通过。具体顺序见操作手册。
5. 验证：运行 tsc --noEmit 并确保没有错误；对于已发布的包，确认声明文件能够生成，并将使用者解析验证交由 node-packaging 的门禁处理。

输出规范

明确写出每个关键选项的 tsconfig；类型检查脚本和 CI 门禁；对于库，生成带映射的声明文件；说明选择模块和解析方式的理由；如适用，提供包含可衡量检查点的严格化计划。

注意事项

• 直接由 Node 使用的包若采用 bundler 解析方式，本地类型检查可能通过，但使用者会遇到问题——始终根据使用方式做出选择。
• verbatimModuleSyntax 会要求类型专用导入必须使用 import type，并限制 CJS 输出中的默认导出——应与 codemod 一起启用。
• isolatedDeclarations 要求导出的 API 显式声明返回类型——对库很有用，对应用则可能带来大量噪声；不要盲目将其加入应用配置。
• TypeScript 7（原生编译器，2026 年 7 月 GA）是 typescript@latest 安装的版本；显式 tsconfig 仍能保持兼容，但 6.0 弃用的功能（baseUrl、target: es5、moduleResolution: classic）在 7 中会成为硬错误——操作手册列出了这些功能，以及适用于依赖 API 的工具的 @typescript/typescript6 回退方案。
• 版本门禁：每次 TypeScript 主版本变化时，都要根据官方 TSConfig 参考文档重新验证默认值和选项行为。

文件

• references/tsconfig-playbook.md — 显式配置块（库／应用）、nodenext 与 bundler 的选择、严格化步骤、验证命令。