React Router 架构决策 ADR-0008：TypeScript 模板为何只转换 app 代码为 JavaScript

React Router 架构决策 ADR-0008TypeScript 模板为何只转换 app 代码为 JavaScript【免费下载链接】react-routerDeclarative routing for React项目地址: https://gitcode.com/GitHub_Trending/re/react-router本篇技术文章围绕 React Router 仓库中一份已采纳的架构决策记录ADR展开Only support JS conversion for app code。该决策解释了为什么在脚手架工具中为 JavaScript 用户动态降级 TypeScript 模板时只转换应用目录app/内的代码而不转换构建脚本与配置文件并剖析了 ESM/CJS 双路线各自踩中的技术深坑。读完本文你能理解模板即单一可信源的脚手架设计思想看懂 Node.js 模块系统在真实工程中的约束并能对照 create-react-router 的当前源码验证这套决策最终是如何被模板化机制承接的。背景TypeScript 默认、JavaScript 可选的选择困境React Router及其前身 Remix的项目脚手架默认使用 TypeScript但始终有一批用户更倾向纯 JavaScript。决策文档日期 2023-01-20状态 accepted记录了当时npx create-remix的交互场景——CLI 会直接询问用户选择 TS 还是 JS❯ npx create-remixlatest ? Where would you like to create your app? ./my-remix-app ? What type of app do you want to create? Just the basics ? Where do you want to deploy? Choose Remix App Server if youre unsure; its easy to change deployment targets. Remix App Server ? TypeScript or JavaScript? (Use arrow keys) ❯ TypeScript JavaScript这个语言选择看似只是一个选项背后却要维护两套完整的项目模板由此引出了模板维护成本问题。模板方案的演进从双份模板到仅维护 TS 变体文档还原了一条清晰的演进链最初为每个模板分别维护 TypeScript 和 JavaScript 两个变体。它能用但巨大的模板内容被完整复制了两份两套变体极难维护——任何一处功能更新都要同步改两次。改进团队决定只维护每个模板的 TS 变体。当用户选择 JavaScript 时CLI 会先把 TS 模板拷贝下来然后动态地把所有 TypeScript 相关代码转换成 JavaScript 等价物。这个方案的边界划分很关键转换app/目录即 Remix/React Router 应用代码内的文件是可靠的因为这部分代码由 Vite 统一构建构建管线对 TS/JS 的处理是透明的而转换app/目录之外的 TS 相关代码则棘手且易错。app 代码内可靠、app 代码外易错这个判断是整个 ADR 的支点下面逐一拆解易错具体难在哪里。为什么 app 目录之外的转换如此困难app/之外通常是什么package.json里的 scripts、server.ts/seed.ts这类 Node 直接执行的脚本、vite.config.ts、tsconfig.json、种子数据工具等。这些文件绕过了构建管线由 Node 直接加载于是 Node 的模块解析规则成为硬约束。问题 1.ts文件的陈旧引用Stale references文档给出的实例是 Indie 与 Blues 两个官方栈模板当用户选择JavaScript后模板里的构建/启动脚本仍然引用着server.ts和seed.ts脚本依赖也随之引用了ts-node这类 TS 专用运行工具——结果就是脚本直接跑不起来。这个问题揭示了一个通用规律模板转换不仅是文件内容翻译还必须同时改写所有指向这些文件的引用点package.jsonscripts、import 语句、工具链依赖。引用点分散在 JSON、shell 命令、代码三种介质中静态改写很容易漏。问题 2.aESM 路线.mjsapp/之外转 JS 时最直觉的做法是转成 ESM 风格的.mjs因为 Remix 应用代码本身就用 ESM 语法。但 ESM 在 Node 中有两种启用方式文档逐一分析了两者的死结方式 a在package.json中设置type: module—— 文档指出这会立即破坏构建因为该设置作用于整个包目录覆盖到 app 代码而不只是 app 之外的脚本与 Remix 的构建配置产生冲突。方式 b使用.mjs扩展名—— 看起来更有希望但.mjs文件的 import 说明符必须带完整文件扩展名。而原 TS 模板中的相对导入普遍不带扩展名于是出现这样的困境// ./script.mjs (converted from ./script.js) import myHelper from ./my-helper; // Should this be converted to ./my-helper.mjs? // Probably, but can we be sure? myHelper();把无扩展名相对导入可靠地补上正确扩展名是不可治理untractable的——因为目标文件未必都是.js/.mjs转换器无法保证每一次补全都正确。文档的结论是或许存在某种解法但复杂度代价过高。问题 2.bCJS 路线如果不用.mjsNode 会把 app 目录外的脚本默认当作 CommonJS 处理。而 CJS 不支持 ESM 风格的import/export那就需要把所有import/export改写成require/module.exports。文档补充了一条容易被忽视的约束转换后的代码是要给其他开发者阅读和编辑的因此不能像构建产物那样生成一堆 import/export 的样板适配代码。import/export 的转换或许可行但同样复杂度代价很高。三条路线双模板、ESM、CJS全部被排除后决策的收敛方向就清晰了。决策JS 转换只覆盖 app 代码Only support JS conversion for app code, not for scripts or code outside of the Remix app directory.只为 app 代码提供 JS 转换不为 app 目录之外的脚本和代码提供转换。这个决策的实质是划定转换能力的可信边界构建管线管辖范围内app/的 TS→JS 转换交给工具自动化构建管线管辖范围外Node 直接执行的脚本与配置保持 TypeScript 原样把语言选择的责任上移给用户——通过选择模板来表达。用户的三个选项与手动清理路径根据决策用户面对想用 JavaScript这一诉求时有三种选择使用 TypeScript 模板使用 TypeScript 模板但app 目录被自动转换为 JSapp/外仍是 TS 文件与 TS 工具链;使用专门的 JavaScript 模板dedicated Javascript template。如果选项 2 残留的 TS 让用户无法接受、又找不到合适的选项 3 模板文档给出了完整的手动清理清单删除tsconfig.json或替换为等价的jsconfig.json把 TS 专用工具替换为 JS 对应物例如ts-node-node把剩余的.ts文件改为.mjs并同步更新所有引用点——包括 import 与package.jsonscripts 中的文件名引用。注意这份清单恰好对应了前面分析的三类坑配置文件、工具链依赖、陈旧引用——手动操作时照单排查即可。源码印证模板机制在 create-react-router 中的落地ADR 提出时 CLI 还内置了TS 或 JS的交互式提问到了当前仓库的 create-react-router语言选择已经彻底模板化——在packages/create-react-router包内检索不到任何 TypeScript/JavaScript 的交互提问逻辑语言差异完全由--template指定的模板承载这正是 ADR 选项 3专门模板成为主流路径后的自然演进。当前 CLI 的模板机制可以从源码中完整验证模板来源的五种合法形式copyTemplate 的入口注释明确列出——本地文件或目录、GitHubowner/repo简写、owner/repo/directory简写、完整 GitHub 仓库 URL、任意 tarball URL非法模板会抛出 CopyTemplateError。GitHub 简写解析copyTemplateFromGithubRepoShorthand 将owner/name[/path]拆段后经 codeload 下载仓库 tarball 并解压getRepoInfo 负责从tree分支 URL 中提取分支与子目录。子目录过滤tarball 解压时通过 tar 的map钩子copy-template.ts按前缀过滤只保留指定子目录——这就是能选owner/repo/templates/basic这类仓库内某目录作为模板的实现基础。默认模板copyTemplateToTempDirStep 中未传--template时回退到 remix-run 官方 templates 仓库的 default 模板printHelp 的--help输出把上述五种模板形式与示例逐条列出私有仓库还支持--token传访问令牌。CLI 流程index.ts 中整个创建流程是显式步骤数组introStep→projectNameStep→copyTemplateToTempDirStep→copyTempDirToAppDirStep→ 依赖安装与 git 初始化等模板拷贝先落到临时目录再复制到目标目录并在 copyTempDirToAppDirStep 中做文件冲突检测--overwrite可强制覆盖。这条源码证据链说明ADR 时代的CLI 动态转换与今天的模板选择并不矛盾——--template机制把选语言变成了选模板把转换的责任从 CLI 的脆弱字符串改写前移到模板作者的一次性维护从工程上规避了问题 1、2.a、2.b 的全部风险。要点回顾维护 TS/JS 双份模板的重复成本催生了仅维护 TS 模板 动态转换的中间方案app/之外的转换在 ESM.mjs扩展名强制、type: module污染全包与 CJSimport/export 全量改写且产物需可读两条路上都代价过高加上package.jsonscripts 中的.ts陈旧引用问题最终决策为只转换 app 代码用户因此拥有 TS 模板 / 半转换模板 / 纯 JS 模板三条路径且文档提供了tsconfig.json→jsconfig.json、ts-node→node、.ts→.mjs三步手动清理清单当前 create-react-router 源码显示该决策的落地形态语言选择交由--template模板机制承担CLI 本身不再做任何交互式语言提问或代码级 TS→JS 转换。这份 ADR 的价值在于它示范了一种务实的架构决策方法先穷举候选路线并给出每条路线的失败证据带代码示例再把能力边界收缩到可靠区间内剩下的复杂性交还给用户可控的模板层。对于任何需要为多语言用户提供脚手架的项目这都是一份可直接借鉴的决策样本。【免费下载链接】react-routerDeclarative routing for React项目地址: https://gitcode.com/GitHub_Trending/re/react-router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考