ESBuild中保留未使用TypeScript导入的配置技巧

在构建工具链中，ESBuild因其极快的编译速度而广受欢迎。但在处理TypeScript转换时，开发者可能会遇到一个常见问题：未被显式使用的导入语句会被自动移除。这种情况在Svelte/Vue单文件组件中尤为明显，因为这些框架的模板语法会隐式引用导入的变量。

问题现象

当使用ESBuild转换以下TypeScript代码时：

import title from './title'

转换后的结果会变成空输出。这是因为ESBuild默认遵循TypeScript的类型擦除特性——任何看似未被使用的导入都可能被视为类型导入而被移除。

技术背景

TypeScript 5.0引入的verbatimModuleSyntax选项改变了模块导入的处理方式。启用后：

1. 使用import type明确表示类型导入
2. 常规import语句将始终保留
3. 提供了更精确的模块语义控制

解决方案

在ESBuild中，可以通过tsconfig-raw参数传递TypeScript配置：

esbuild.transform(code, {
  tsconfigRaw: {
    compilerOptions: {
      verbatimModuleSyntax: true
    }
  }
})

应用场景

这种配置特别适用于：

1. Svelte/Vue单文件组件
2. JSX/TSX模板中隐式使用的变量
3. 需要保留导入副作用的情况
4. 与框架特定的转换管道集成

注意事项

1. 启用此选项后，所有常规导入都会保留，可能导致打包体积增大
2. 对于明确只用于类型的导入，建议改用import type语法
3. 在复杂项目中，可能需要结合其他Tree Shaking配置

通过合理配置ESBuild的TypeScript处理选项，开发者可以更好地控制模块导入行为，满足各种框架和特殊场景的需求。