正确导出TypeScript Vue组件库：集成vue-router、vue-notifications配置

问题现状 #

• 开发目标：构建集成vue-notifications、vue-router能力的Vue组件库，要求组件内部可直接调用this.$router、this.$notify方法，且方法实例直接复用消费项目已初始化的对象，不重复创建。
• 初始开发状态：
  • 组件库入口采用Vue插件标准install方法注册内置组件
  • 基础类型声明文件仅包含*.vue单文件组件的全局兜底声明
• 现存异常：
  • 组件库本身可正常完成构建流程
  • 消费项目引入组件库后，使用相关组件时会抛出「this.$notify does not exist on type ...」的TypeScript类型报错
• 已尝试的无效修改：
  • 在原.d.ts声明文件中引入vue-router并扩展Vue实例的$router类型定义，修改后组件库构建时出现.vue组件无法被识别、导出找不到组件的报错

异常根因 #

TypeScript的模块作用域规则：一旦在.d.ts声明文件顶部引入任意外部模块（即添加import语法），该文件就会从「全局声明文件」变为「模块文件」，原本全局生效的*.vue模块声明会失去全局作用域，导致TypeScript无法识别单文件组件的导出，最终触发构建报错。

分步调整方案 #

1. 拆分独立类型声明文件，避免作用域冲突
   • 保留原有的vue-shims.d.ts，仅存放全局单文件组件声明，该文件全程不添加任何import语法，保持全局声明的作用域：

     // vue-shims.d.ts 内容
     declare module '*.vue' {
       import Vue from 'vue';
       export default Vue;
     }
     

2. 新建独立的Vue实例类型扩展文件vue-global-types.d.ts
   • 该文件专门用于扩展Vue的全局实例类型，因本身包含import语法属于模块文件，需要通过declare module 'vue/types/vue'的方式做类型增强，保证类型扩展全局生效：

     // vue-global-types.d.ts 内容
     import Vue from 'vue';
     import Router from 'vue-router';
     
     // 定义$notify的方法签名，匹配vue-notifications的实际能力
     type NotifyOptions = {
       title?: string;
       message: string;
       type?: 'success' | 'error' | 'warning' | 'info';
     };
     type NotifyFn = (options: NotifyOptions) => void;
     
     // 扩展Vue实例接口，挂载自定义类型
     declare module 'vue/types/vue' {
       interface Vue {
         $router: Router;
         $notify: NotifyFn;
       }
     }
     

3. 调整组件库包配置，暴露类型声明入口
   • 修改组件库package.json的导出配置，保证消费项目可以正常加载到类型扩展文件：

     {
       "types": "./dist/types/index.d.ts",
       "exports": {
         ".": {
           "types": "./dist/types/index.d.ts",
           "default": "./dist/my-component-library.esm.js"
         },
         "./vue-global-types": "./dist/vue-global-types.d.ts"
       }
     }
     

4. 优化组件库install逻辑，适配实例复用要求
   • 调整插件安装逻辑，避免重复安装依赖插件，优先复用消费项目已初始化的$router、$notify实例：

     // index.ts 调整后的插件入口
     import MyComponent1 from './components/MyComponent1.vue';
     import MyComponent2 from './components/MyComponent2.vue';
     import VueRouter from 'vue-router';
     import VueNotifications from 'vue-notifications';
     
     export default {
       install(Vue: any) {
         // 无对应实例时才做兜底安装，不覆盖消费项目的已有实例
         if (!Vue.prototype.$router) {
           Vue.use(VueRouter);
         }
         if (!Vue.prototype.$notify) {
           Vue.use(VueNotifications);
         }
         Vue.component('MyComponent1', MyComponent1);
         Vue.component('MyComponent2', MyComponent2);
       }
     }
     

消费项目配套配置 #

• 消费项目在全局类型声明入口（如src/shims-vue.d.ts）中引入组件库导出的类型扩展文件，即可消除对应的类型报错：

  // 消费项目shims-vue.d.ts 顶部添加引用
  /// <reference types="my-component-library/vue-global-types" />
  

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