vite-plugin-define-types-dts

根据 Vite 的 define 配置自动生成 TypeScript 声明文件。

安装

pnpm add -D vite-plugin-define-types-dts

使用方式

import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'
import { defineTypesPlugin } from 'vite-plugin-define-types-dts'

export default defineConfig({
  define: {
    __APP_NAME__: JSON.stringify('my-app'),
    __ENABLE_DEMO__: true,
    __BUILD_NUMBER__: 42,
  },
  plugins: [
    vue(),
    defineTypesPlugin({
      outputPath: 'src/define-types.d.ts',
      excludeKeys: ['__BUILD_NUMBER__'],
      strictDefineKey: true,
    }),
  ],
})

生成文件示例：

// Auto-generated by defineTypesPlugin — do not edit
declare const __APP_NAME__: string
declare const __ENABLE_DEMO__: boolean
declare const __BUILD_NUMBER__: number

API

defineTypesPlugin(options?: DefineTypesPluginOptions)

• options.outputPath： 声明文件输出路径，基于 Vite config.root 解析。 默认值：define-types.d.ts。
• options.apply： 插件生效阶段，类型为 Plugin['apply']，支持 serve、build 或函数形式。 默认值：serve（仅开发环境）。
• options.excludeKeys： 指定不生成声明的 define key 列表。 默认值：[]。
• options.strictDefineKey： 是否仅处理 __xxx__ 形式的 key。 默认值：true。

函数形式示例：

defineTypesPlugin({
  apply(_, env) {
    return env.command === 'serve'
  },
})

TypeScript 配置

请确保 tsconfig 的 include 包含生成的声明文件路径（可参考 examples/vite-vue/tsconfig.app.json）。

默认会生成到根目录 define-types.d.ts，请在 include 中显式包含该文件：

{
  "include": [
    "define-types.d.ts",
    "src/**/*.ts",
    "src/**/*.tsx",
    "src/**/*.vue",
    "src/**/*.d.ts"
  ]
}

项目命令

• pnpm run dev：本地监听构建（watch）。
• pnpm run build：执行正式构建并产出 dist。
• pnpm run test：运行测试。
• pnpm run lint：执行代码检查。
• pnpm run typecheck：执行 TypeScript 类型检查。
• pnpm run release：使用 bumpp 更新版本并创建发布提交。
• pnpm run publish:npm：发布当前包到 npm。

注意事项

• strictDefineKey: true 时，仅会生成匹配 ^__[A-Za-z0-9_]+__$ 的 key。
• strictDefineKey: false 时，会生成所有合法变量名（如 APP_NAME、$FLAG），不合法标识符会跳过。
• 无法可靠推断的 define 值会回退为 unknown。
• 仅在内容变化时写入文件，避免无意义改动。

License

MIT License © BINGWU2003