vite-plugin-dts

一款用于在 库模式 中从 .ts(x) 或 .vue 源文件生成类型文件（*.d.ts）的 Vite 插件。

中文 | English

安装

1pnpm i vite-plugin-dts -D

使用

在 vite.config.ts：

1import { resolve } from 'path'
2import { defineConfig } from 'vite'
3import dts from 'vite-plugin-dts'
4
5export default defineConfig({
6  build: {
7    lib: {
8      entry: resolve(__dirname, 'src/index.ts'),
9      name: 'MyLib',
10      formats: ['es'],
11      fileName: 'my-lib'
12    }
13  },
14  plugins: [dts()]
15})

默认情况，生成的类型文件会跟随源文件的结构。

如果你希望将所有的类型合并到一个文件中，只需指定 rollupTypes: true：

1{
2  plugins: [dts({ rollupTypes: true })]
3}

如果你从 Vite 官方模板开始，你应该指定 tsconfigPath：

1{
2  plugins: [dts({ tsconfigPath: './tsconfig.app.json' })]
3}

从 3.0.0 开始，你可以在 Rollup 中使用该插件。

常见问题

此处将收录一些常见的问题并提供一些解决方案。

打包时出现了无法从 node_modules 的包中推断类型的错误

这是 TypeScript 通过软链接 (pnpm) 读取 node_modules 中过的类型时会出现的一个已知的问题，可以参考这个 issue，目前已有的一个解决方案，在你的 tsconfig.json 中添加 baseUrl 以及在 paths 添加这些包的路径：

1{
2  "compilerOptions": {
3    "baseUrl": ".",
4    "paths": {
5      "third-lib": ["node_modules/third-lib"]
6    }
7  }
8}

在 rollupTypes: true 时出现 Internal Error

参考这个 issue，这是由于 @microsoft/api-extractor 或者是 TypeScript 解析器的一些限制导致的。

主要原因在于 tsconfig.json 中指定了 baseUrl 并且在引入时直接使用非标准路径。

例如：指定了 baseUrl: 'src' 并且在 <root>/src/index.ts 中引入 <root>/src/components/index.ts 时使用了 import 'components' 而不是 import './components'。

目前想要正常打包，需要规避上述情况，或使用别名代替（配合 paths 属性）。

打包时出现找不到模块的错误

这很有可能是因为在你的默认 tsconfig.json 中未有正确配置 include 导致的。

由于一些局限性，插件依赖最上层的 tsconfig.json 来解析需要包含的文件，所以你需要在最上层的 tsconfig.json 中指定正确的 include，或者通过插件的 tsconfigPath 选项指定一个包含了正确 include 的配置文件路径，例如在 Vite 初始模板中它是 tsconfig.app.json。

可以参考这个 评论.

过时的

打包后出现类型文件缺失 (1.7.0 之前)

默认情况下 skipDiagnostics 选项的值为 true，这意味着打包过程中将跳过类型检查（一些项目通常有 vue-tsc 等的类型检查工具），这时如果出现存在类型错误的文件，并且这是错误会中断打包过程，那么这些文件对应的类型文件将不会被生成。

如果您的项目没有依赖外部的类型检查工具，这时候可以您可以设置 skipDiagnostics: false 和 logDiagnostics: true 来打开插件的诊断与输出功能，这将帮助您检查打包过程中出现的类型错误并将错误信息输出至终端。

Vue 组件中同时使用了 script 和 setup-script 后出现类型错误（3.0.0 之前）

这通常是由于分别在 script 和 setup-script 中同时使用了 defineComponent 方法导致的。 vue/compiler-sfc 为这类文件编译时会将 script 中的默认导出结果合并到 setup-script 的 defineComponent 的参数定义中，而 defineComponent 的参数类型与结果类型并不兼容，这一行为将会导致类型错误。

这是一个简单的示例，您应该将位于 script 中的 defineComponent 方法移除，直接导出一个原始的对象。

选项

1import type ts from 'typescript'
2import type { IExtractorConfigPrepareOptions, IExtractorInvokeOptions } from '@microsoft/api-extractor'
3import type { LogLevel } from 'vite'
4
5type MaybePromise<T> = T | Promise<T>
6
7export type RollupConfig = Omit<
8  IExtractorConfigPrepareOptions['configObject'],
9  | 'projectFolder'
10  | 'mainEntryPointFilePath'
11  | 'compiler'
12  | 'dtsRollup'
13  >
14
15export interface Resolver {
16  /**
17   * 解析器的名称
18   *
19   * 靠后的同名解析器将会覆盖靠前的
20   */
21  name: string,
22  /**
23   * 判断解析器是否支持该文件
24   */
25  supports: (id: string) => void | boolean,
26  /**
27   * 将源文件转换为类型文件
28   *
29   * 注意，返回的文件的路径应该基于 `outDir`，或者相对于 `root`
30   */
31  transform: (payload: {
32    id: string,
33    code: string,
34    root: string,
35    outDir: string,
36    host: ts.CompilerHost,
37    program: ts.Program,
38  }) => MaybePromise<{ path: string, content: string }[]>
39}
40
41export interface PluginOptions {
42  /**
43   * 指定根目录
44   *
45   * 默认为 Vite 配置的 'root'，使用 Rollup 为 `process.cwd()`
46   */
47  root?: string,
48
49  /**
50   * 指定输出目录
51   *
52   * 可以指定一个数组来输出到多个目录中
53   *
54   * 默认为 Vite 配置的 'build.outDir'，使用 Rollup 时为 tsconfig.json 的 `outDir`
55   */
56  outDir?: string | string[],
57
58  /**
59   * 用于手动设置入口文件的根路径（通常用在 monorepo）
60   *
61   * 在计算每个文件的输出路径时将基于该路径
62   *
63   * 默认为所有源文件的最小公共路径
64   */
65  entryRoot?: string,
66
67  /**
68   * 限制类型文件生成在 `outDir` 内
69   *
70   * 如果为 `true`，生成在 `outDir` 外的文件将被忽略
71   *
72   * @default true
73   */
74  strictOutput?: boolean,
75
76  /**
77   * 覆写 CompilerOptions
78   *
79   * @default null
80   */
81  compilerOptions?: ts.CompilerOptions | null,
82
83  /**
84   * 指定 tsconfig.json 的路径
85   *
86   * 插件会解析 tsconfig.json 的 include 和 exclude 选项
87   *
88   * 未指定时插件默认从根目录开始寻找配置文件
89   */
90  tsconfigPath?: string,
91
92  /**
93   * 指定自定义的解析器
94   *
95   * @default []
96   */
97  resolvers?: Resolver[],
98
99  /**
100   * 解析 tsconfig.json 的 `paths` 作为别名
101   *
102   * 注意，这些别名仅用在类型文件中使用
103   *
104   * @default true
105   * @remarks 只使用每个路径的第一个替换
106   */
107  pathsToAliases?: boolean,
108
109  /**
110   * 设置在转换别名时哪些路径需要排除
111   *
112   * @default []
113   */
114  aliasesExclude?: (string | RegExp)[],
115
116  /**
117   * 是否将 '.vue.d.ts' 文件名转换为 '.d.ts'
118   *
119   * 如果转换后出现重名，将会回退到原来的名字。
120   *
121   * @default false
122   */
123  cleanVueFileName?: boolean,
124
125  /**
126   * 是否将动态引入转换为静态（例如：`import('vue').DefineComponent` 转换为 `import { DefineComponent } from 'vue'`）
127   *
128   * 开启 `rollupTypes` 时强制为 `true`
129   *
130   * @default false
131   */
132  staticImport?: boolean,
133
134  /**
135   * 手动设置包含路径的 glob（相对于 root）
136   *
137   * 默认基于 tsconfig.json 的 `include` 选项（相对于 tsconfig.json 所在目录）
138   */
139  include?: string | string[],
140
141  /**
142   * 手动设置排除路径的 glob
143   *
144   * 默认基于 tsconfig.json 的 `exclude` 选线，未设置时为 `'node_modules/**'`
145   */
146  exclude?: string | string[],
147
148  /**
149   * 是否移除 `import 'xxx'`
150   *
151   * @default true
152   */
153  clearPureImport?: boolean,
154
155  /**
156   * 是否生成类型入口文件
157   *
158   * 当为 `true` 时会基于 package.json 的 `types` 字段生成，或者 `${outDir}/index.d.ts`
159   *
160   * 当开启 `rollupTypes` 时强制为 `true`
161   *
162   * @default false
163   */
164  insertTypesEntry?: boolean,
165
166  /**
167   * 设置是否将发出的类型文件打包进单个文件
168   *
169   * 基于 `@microsoft/api-extractor`，过程将会消耗一些时间
170   *
171   * @default false
172   */
173  rollupTypes?: boolean,
174
175  /**
176   * 设置 `@microsoft/api-extractor` 的 `bundledPackages` 选项
177   *
178   * @default []
179   * @see https://api-extractor.com/pages/configs/api-extractor_json/#bundledpackages
180   */
181  bundledPackages?: string[],
182
183  /**
184   * 覆写 `@microsoft/api-extractor` 的配置
185   *
186   * @default null
187   * @see https://api-extractor.com/pages/setup/configure_api_report/
188   */
189  rollupConfig?: RollupConfig,
190
191  /**
192   * 覆写 `@microsoft/api-extractor` 的调用选项
193   *
194   * @default null
195   * @see https://api-extractor.com/pages/setup/invoking/#invoking-from-a-build-script
196   */
197  rollupOptions?: IExtractorInvokeOptions,
198
199  /**
200   * 是否将源码里的 .d.ts 文件复制到 `outDir`
201   *
202   * @default false
203   * @remarks 在 2.0 之前它默认为 `true`
204   */
205  copyDtsFiles?: boolean,
206
207  /**
208   * 是否只生成类型文件
209   *
210   * 当为 `true` 时会强制删除所有 Vite（Rollup）的原始产物
211   *
212   * @default false
213   */
214  declarationOnly?: boolean,
215
216  /**
217   * 指定插件的输出等级
218   *
219   * 默认基于 Vite 配置的 'logLevel' 选项
220   */
221  logLevel?: LogLevel,
222
223  /**
224   * 获取诊断信息后的钩子
225   *
226   * 可以根据 `diagnostics.length` 来判断有误类型错误
227   *
228   * @default () => {}
229   */
230  afterDiagnostic?: (diagnostics: readonly ts.Diagnostic[]) => MaybePromise<void>,
231
232  /**
233   * 类型声明文件被写入前的钩子
234   *
235   * 可以在钩子里转换文件路径和文件内容
236   *
237   * 当返回 `false` 或 `Promise<false>` 时会跳过该文件
238   *
239   * @default () => {}
240   */
241  beforeWriteFile?: (
242    filePath: string,
243    content: string
244  ) => MaybePromise<
245    | void
246    | false
247    | {
248      filePath?: string,
249      content?: string
250    }
251  >,
252
253  /**
254   * 类型文件被打包进单个文件后的钩子
255   *
256   * @default () => {}
257   */
258  afterRollup?: (result: ExtractorResult) => MaybePromise<void>,
259
260  /**
261   * 在所有类型文件被写入后的钩子
262   *
263   * 它会接收一个记录了那些最终被写入的文件的映射（path -> content）
264   *
265   * @default () => {}
266   */
267  afterBuild?: (emittedFiles: Map<string, string>) => MaybePromise<void>
268}

贡献者

感谢他们的所做的一切贡献！

示例

克隆项目然后执行下列命令：

1pnpm run test:ts

然后检查 examples/ts/types 目录。

examples 目录下同样有 Vue 和 React 的案例。

一个使用该插件的真实项目：Vexip UI。

授权

MIT 授权。