vite-plugin-dts

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

中文 | English

安装

 pnpm i vite-plugin-dts -D

使用

在 vite.config.ts：

 import { resolve } from 'path'
import { defineConfig } from 'vite'
import dts from 'vite-plugin-dts'

export default defineConfig({
  build: {
    lib: {
      entry: resolve(__dirname, 'src/index.ts'),
      name: 'MyLib',
      formats: ['es'],
      fileName: 'my-lib'
    }
  },
  plugins: [dts()]
})

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

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

 {
  plugins: [dts({ rollupTypes: true })]
}

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

常见问题

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

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

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

 {
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "third-lib": ["node_modules/third-lib"]
    }
  }
}

在 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 属性）。

选项

 import type ts from 'typescript'
import type { IExtractorConfigPrepareOptions, IExtractorInvokeOptions } from '@microsoft/api-extractor'
import type { LogLevel } from 'vite'

type MaybePromise<T> = T | Promise<T>

export type RollupConfig = Omit<
  IExtractorConfigPrepareOptions['configObject'],
  | 'projectFolder'
  | 'mainEntryPointFilePath'
  | 'compiler'
  | 'dtsRollup'
  >

export interface Resolver {
  /**
   * 解析器的名称
   *
   * 靠后的同名解析器将会覆盖靠前的
   */
  name: string,
  /**
   * 判断解析器是否支持该文件
   */
  supports: (id: string) => void | boolean,
  /**
   * 将源文件转换为类型文件
   *
   * 注意，返回的文件的路径应该基于 `outDir`，或者相对于 `root`
   */
  transform: (payload: {
    id: string,
    code: string,
    root: string,
    outDir: string,
    host: ts.CompilerHost,
    program: ts.Program,
    service: ts.LanguageService
  }) => MaybePromise<{ path: string, content: string }[]>
}

export interface PluginOptions {
  /**
   * 指定根目录
   *
   * 默认为 Vite 配置的 'root'，使用 Rollup 为 `process.cwd()`
   */
  root?: string,

  /**
   * 指定输出目录
   *
   * 可以指定一个数组来输出到多个目录中
   *
   * 默认为 Vite 配置的 'build.outDir'，使用 Rollup 时为 tsconfig.json 的 `outDir`
   */
  outDir?: string | string[],

  /**
   * 用于手动设置入口文件的根路径（通常用在 monorepo）
   *
   * 在计算每个文件的输出路径时将基于该路径
   *
   * 默认为所有源文件的最小公共路径
   */
  entryRoot?: string,

  /**
   * 限制类型文件生成在 `outDir` 内
   *
   * 如果为 `true`，生成在 `outDir` 外的文件将被忽略
   *
   * @default true
   */
  strictOutput?: boolean,

  /**
   * 覆写 CompilerOptions
   *
   * @default null
   */
  compilerOptions?: ts.CompilerOptions | null,

  /**
   * 指定 tsconfig.json 的路径
   *
   * 插件会解析 tsconfig.json 的 include 和 exclude 选项
   *
   * 未指定时插件默认从根目录开始寻找配置文件
   */
  tsconfigPath?: string,

  /**
   * 指定自定义的解析器
   *
   * @default []
   */
  resolvers?: Resolver[],

  /**
   * 解析 tsconfig.json 的 `paths` 作为别名
   *
   * 注意，这些别名仅用在类型文件中使用
   *
   * @default true
   * @remarks 只使用每个路径的第一个替换
   */
  pathsToAliases?: boolean,

  /**
   * 设置在转换别名时哪些路径需要排除
   *
   * @default []
   */
  aliasesExclude?: (string | RegExp)[],

  /**
   * 是否将 '.vue.d.ts' 文件名转换为 '.d.ts'
   *
   * @default false
   */
  cleanVueFileName?: boolean,

  /**
   * 是否将动态引入转换为静态（例如：`import('vue').DefineComponent` 转换为 `import { DefineComponent } from 'vue'`）
   *
   * 开启 `rollupTypes` 时强制为 `true`
   *
   * @default false
   */
  staticImport?: boolean,

  /**
   * 手动设置包含路径的 glob（相对于 root）
   *
   * 默认基于 tsconfig.json 的 `include` 选项（相对于 tsconfig.json 所在目录）
   */
  include?: string | string[],

  /**
   * 手动设置排除路径的 glob
   *
   * 默认基于 tsconfig.json 的 `exclude` 选线，未设置时为 `'node_modules/**'`
   */
  exclude?: string | string[],

  /**
   * 是否移除 `import 'xxx'`
   *
   * @default true
   */
  clearPureImport?: boolean,

  /**
   * 是否生成类型入口文件
   *
   * 当为 `true` 时会基于 package.json 的 `types` 字段生成，或者 `${outDir}/index.d.ts`
   *
   * 当开启 `rollupTypes` 时强制为 `true`
   *
   * @default false
   */
  insertTypesEntry?: boolean,

  /**
   * 设置是否将发出的类型文件打包进单个文件
   *
   * 基于 `@microsoft/api-extractor`，过程将会消耗一些时间
   *
   * @default false
   */
  rollupTypes?: boolean,

  /**
   * 设置 `@microsoft/api-extractor` 的 `bundledPackages` 选项
   *
   * @default []
   * @see https://api-extractor.com/pages/configs/api-extractor_json/#bundledpackages
   */
  bundledPackages?: string[],

  /**
   * 覆写 `@microsoft/api-extractor` 的配置
   *
   * @default null
   * @see https://api-extractor.com/pages/setup/configure_api_report/
   */
  rollupConfig?: RollupConfig,

  /**
   * 覆写 `@microsoft/api-extractor` 的调用选项
   *
   * @default null
   * @see https://api-extractor.com/pages/setup/invoking/#invoking-from-a-build-script
   */
  rollupOptions?: IExtractorInvokeOptions,

  /**
   * 是否将源码里的 .d.ts 文件复制到 `outDir`
   *
   * @default false
   * @remarks 在 2.0 之前它默认为 `true`
   */
  copyDtsFiles?: boolean,

  /**
   * 是否只生成类型文件
   *
   * 当为 `true` 时会强制删除所有 Vite（Rollup）的原始产物
   *
   * @default false
   */
  declarationOnly?: boolean,

  /**
   * 指定插件的输出等级
   *
   * 默认基于 Vite 配置的 'logLevel' 选项
   */
  logLevel?: LogLevel,

  /**
   * 获取诊断信息后的钩子
   *
   * 可以根据 `diagnostics.length` 来判断有误类型错误
   *
   * @default () => {}
   */
  afterDiagnostic?: (diagnostics: readonly ts.Diagnostic[]) => MaybePromise<void>,

  /**
   * 类型声明文件被写入前的钩子
   *
   * 可以在钩子里转换文件路径和文件内容
   *
   * 当返回 `false` 或 `Promise<false>` 时会跳过该文件
   *
   * @default () => {}
   */
  beforeWriteFile?: (
    filePath: string,
    content: string
  ) => MaybePromise<
    | void
    | false
    | {
      filePath?: string,
      content?: string
    }
  >,

  /**
   * 类型文件被打包进单个文件后的钩子
   *
   * @default () => {}
   */
  afterRollup?: (result: ExtractorResult) => MaybePromise<void>,

  /**
   * 在所有类型文件被写入后的钩子
   *
   * 它会接收一个记录了那些最终被写入的文件的映射（path -> content）
   *
   * @default () => {}
   */
  afterBuild?: (emittedFiles: Map<string, string>) => MaybePromise<void>
}

贡献者

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

示例

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

 pnpm run test:ts

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

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

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

授权

MIT 授权。