TypeScript transpileModule API 处理 JSX 的注意事项

TypeScript 的 transpileModule API 是一个强大的工具，它允许开发者在内存中直接编译 TypeScript 代码而不需要写入文件系统。然而，在使用这个 API 处理包含 JSX 的代码时，开发者可能会遇到一些意料之外的行为。

问题现象

当尝试使用 transpileModule 编译包含 JSX 的代码时，如果配置不当，输出的结果可能会出现语法错误。例如，对于以下简单的 JSX 代码：

export const x = <div className="foo">hello</div>

在某些配置下，transpileModule 可能会输出如下无效的 JavaScript 代码：

export const x = className;
"foo" > hello < /div>;

这显然不是我们期望的结果。正确的输出应该包含 React JSX 运行时导入和正确的 JSX 转换：

import { jsx as _jsx } from "react/jsx-runtime";
export const x = _jsx("div", { className: "foo", children: "hello" });

问题原因

经过分析，这个问题主要与两个因素有关：

1. 模块系统设置：当使用 ModuleKind.NodeNext 作为模块系统时，transpileModule 的行为可能会受到影响。

2. 文件扩展名：transpileModule 会根据提供的 fileName 参数中的扩展名来决定如何处理模块。使用 .mts 扩展名可以强制输出 ES 模块，但使用 .mtsx 扩展名时却会导致 JSX 转换失败。

解决方案

要解决这个问题，可以采用以下方法之一：

1. 使用 ESNext 模块系统： 将 module 选项设置为 ts.ModuleKind.ESNext，这样可以确保正确转换 JSX 并输出有效的 ES 模块代码。

const { outputText } = ts.transpileModule(source, {
  fileName: "input.tsx",
  compilerOptions: {
    target: ts.ScriptTarget.ESNext,
    module: ts.ModuleKind.ESNext,
    jsx: ts.JsxEmit.ReactJSX,
  },
});

2. 调整文件扩展名： 如果确实需要使用 NodeNext 模块系统，可以尝试使用 .tsx 扩展名而不是 .mtsx，虽然这会输出 CommonJS 模块，但至少 JSX 转换是正确的。

深入理解

transpileModule API 的设计初衷是提供轻量级的编译功能，它不会执行完整的类型检查，而是专注于代码转换。在处理 JSX 时，它会依赖以下几个关键配置项：

• jsx: 控制 JSX 的转换方式，JsxEmit.ReactJSX 会使用 React 17+ 的自动运行时导入
• module: 决定输出的模块系统格式
• fileName: 影响模块格式的推断和 JSX 工厂的引入

值得注意的是，transpileModule 的行为与完整编译过程有所不同，特别是在模块系统推断方面。在完整编译过程中，TypeScript 会综合考虑 tsconfig.json 和各种启发式规则，而 transpileModule 则更依赖于显式提供的选项。

最佳实践

对于需要在内存中编译包含 JSX 的 TypeScript 代码的场景，建议：

1. 明确指定所有相关的编译器选项，不要依赖默认值
2. 优先使用 ESNext 作为模块系统，除非有特殊需求
3. 在开发过程中验证输出结果，确保 JSX 转换符合预期
4. 考虑使用 transform API 替代 transpileModule 以获得更精细的控制

TypeScript 团队可能会在未来版本中改进 transpileModule 的 JSX 处理逻辑，但目前开发者需要了解这些限制并采取适当的应对措施。