esbuild-plugin-tsconfig-paths

English | 中文

在 esbuild 构建过程中，将 tsconfig.json 中 compilerOptions.paths 定义的
路径别名转换为相对导入路径。这样无需在运行时处理别名解析，产物更易于分发和使用。

示例

转换前
``typescript
// src/app/index.ts
import util from "@/utils/util"
`

转换后
`
import util from "../utils/util"
`

安装

`sh
npm install esbuild-plugin-tsconfig-paths --dev
`

使用

`typescript
import { tsconfigPathsPlugin } from "esbuild-plugin-tsconfig-paths";
import esbuild from "esbuild";

esbuild.build({
// ...other config
plugins: [
// ... other plugins
tsconfigPathsPlugin({
// tsconfig 文件所在目录
cwd: process.cwd(),
// tsconfig 文件名
tsconfig: "custom-tsconfig.json",
// 需要被转换的文件匹配规则
filter: /.*/,
})
]
})

`

参数说明

| 参数 | 类型 | 默认值 | 说明 |
|------------|-----------|------------------|------------------------------|
| filter | RegExp | /.*/ | 匹配需要转换的文件路径。 |
| tsconfig | string | tsconfig.json | 指定使用的 tsconfig 文件名。 |
| cwd | string | process.cwd() | 查找 tsconfig 的工作目录。 |

注意事项

- 需要在 tsconfig.json 中配置 compilerOptions.paths；baseUrl 默认 ./。
- 在 esbuild 的 onLoad 阶段执行，将匹配到的导入语句改写为相对路径。
- 以 loader: 'ts' 输出，目标为 TypeScript 源码；建议不要让 filter 匹配 .tsx` 文件。
- 仅改写静态导入语句；动态导入或非路径规则的解析不会变更。

为什么需要

- 产物不依赖运行时别名解析，部署更简单。
- 源码保持别名的整洁写法，构建后面向消费者的是相对路径。

许可协议

MIT