如何让TypeScript自动加载npm包中自定义扩展的.d.ts声明文件？

核心方案：利用TypeScript的typesVersions字段 #

TypeScript的typesVersions字段可以让npm包中的类型声明被自动加载，无需用户手动修改tsconfig.json的include配置，这是实现目标的关键。

步骤1：整理包内类型文件结构 #

在你的插件npm包中，创建types目录，将自定义扩展名的类型声明文件放入其中。比如创建types/users.d.ts，内容示例如下：

declare module "*.user" {
  // 定义自定义文件对应的类型，以类JSON的用户列表为例
  type User = {
    id: number;
    name: string;
  };
  const users: User[];
  export default users;
}

步骤2：配置package.json #

在插件的package.json中添加以下配置，明确告知TypeScript加载类型文件的规则：

{
  "name": "your-vite-plugin-name",
  "main": "index.js",
  "types": "index.d.ts", // 若插件本身有类型声明，指定入口文件
  "typesVersions": {
    "*": {
      "*": ["types/*"]
    }
  },
  "files": [
    "index.js",
    "types", // 确保类型目录被包含在发布的npm包中
    // 插件其他核心文件
  ]
}

• typesVersions的"*": {"*": ["types/*"]}配置，对所有版本的TypeScript生效，会自动从types目录下匹配并加载对应的类型声明，*.user的模块类型就能被识别。
• files字段必须包含types目录，否则发布npm包时类型文件不会被上传。

步骤3：验证效果 #

发布插件包后，用户安装插件并添加到vite.config.ts的plugins列表后，直接导入./xxx.user文件，TypeScript会自动识别其类型，不会再抛出"找不到模块或对应类型声明"的错误。

为什么之前的方法不生效？ #

• 直接在包根目录放置users.d.ts，TypeScript默认只会加载package.json中types字段指定的文件，不会自动扫描根目录的其他.d.ts文件。
• exports字段主要用于模块导入路径的映射，对TypeScript类型自动识别的支持不如typesVersions直接。

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