如何为Vue 3全局组件库添加TypeScript类型支持？

问题背景 #

基于Vue3、Vite、TypeScript开发的组件库，通过插件形式安装并批量注册全局组件，但业务项目使用时，全局组件无法获得TypeScript类型提示。手动在业务项目中添加类型增强文件可解决问题，但希望类型支持直接由组件库提供。

当前组件库核心实现代码：

// src/index.ts
const globalComponents = import.meta.glob("./components/**/*.vue", {
  eager: true,
});

export default {
  install(app: App, options: Record<string, string>) {
    Object.entries(globalComponents).forEach(
      ([item, definition]: [string, any]) => {
        const componentName = item
          ?.split("/")
          ?.pop()
          ?.replace(/\.\w+$/, "");

        app.component(componentName, definition.default);
      }
    );
  },
};

export { /* other exports */ };

Vite构建配置：

// vite.config.ts
export default defineConfig({
  plugins: [vue()],
  build: {
    target: "esnext",
    lib: {
      formats: ["es"],
      entry: path.resolve(__dirname, "src/index.ts"),
      fileName: (format) => `bundle.${format}.js`,
    },
    rollupOptions: {
      external: [...Object.keys(pkg.dependencies || {})],
    },
  },
});

构建命令：

vite build && vue-tsc --emitDeclarationOnly && mv dist/src dist/types

解决方案 #

1. 自动生成全局组件类型增强文件 #

手动维护每个组件的类型声明效率低，编写Node脚本自动遍历组件目录，生成global-components.d.ts：

创建脚本文件src/scripts/generate-global-types.ts：

import fs from 'fs';
import path from 'path';

const componentsDir = path.resolve(__dirname, '../components');
const outputPath = path.resolve(__dirname, '../global-components.d.ts');

// 遍历组件目录，获取所有.vue文件
const getComponentFiles = (dir: string): string[] => {
  let files: string[] = [];
  const entries = fs.readdirSync(dir, { withFileTypes: true });

  for (const entry of entries) {
    const fullPath = path.join(dir, entry.name);
    if (entry.isDirectory()) {
      files = [...files, ...getComponentFiles(fullPath)];
    } else if (entry.name.endsWith('.vue')) {
      files.push(fullPath);
    }
  }
  return files;
};

const componentFiles = getComponentFiles(componentsDir);

// 生成类型声明内容
const importStatements = componentFiles.map(file => {
  const relativePath = path.relative(path.resolve(__dirname, '../'), file);
  const componentName = path.basename(file, '.vue');
  return `import ${componentName} from './${relativePath.replace(/\\/g, '/')}';`;
}).join('\n');

const globalComponentsInterface = componentFiles.map(file => {
  const componentName = path.basename(file, '.vue');
  return `  ${componentName}: typeof ${componentName};`;
}).join('\n');

const content = `
${importStatements}

declare module '@vue/runtime-core' {
  export interface GlobalComponents {
${globalComponentsInterface}
  }
}

export {};
`;

// 写入文件
fs.writeFileSync(outputPath, content.trim());

在package.json中添加脚本命令：

{
  "scripts": {
    "generate:types": "tsx src/scripts/generate-global-types.ts"
  }
}

2. 配置TypeScript识别类型文件 #

修改tsconfig.json，确保生成的类型文件被包含：

{
  "include": [
    "src/**/*.ts",
    "src/**/*.d.ts",
    "src/**/*.vue",
    "src/global-components.d.ts"
  ]
}

3. 配置package.json指向类型入口 #

在package.json中指定类型文件入口，让业务项目自动识别：

{
  "types": "dist/types/global-components.d.ts"
}

如果需要统一管理类型，可创建src/index.d.ts作为主类型入口：

/// <reference path="./global-components.d.ts" />
export * from './index';

然后修改package.json：

{
  "types": "dist/types/index.d.ts"
}

4. 更新构建命令 #

将类型生成脚本加入构建流程，确保每次构建都更新类型：

pnpm generate:types && vite build && vue-tsc --emitDeclarationOnly && mv dist/src dist/types

原理说明 #

• 通过脚本自动生成的类型增强文件，扩展@vue/runtime-core的GlobalComponents接口，让TypeScript识别全局组件类型。
• 配置package.json的types字段后，业务项目安装组件库时，TypeScript会自动加载库的类型声明文件，无需手动添加。

内容的提问来源于stack exchange，提问作者chris