如何使用Vite构建的Node模块自动生成的TypeScript声明文件？

我用Vite创建了一个Node模块，本地安装到项目后，TypeScript无法自动找到模块的声明文件，必须手动在项目目录添加types.d.ts才能消除编译错误。如何让TS正确识别自动生成的声明文件？

文件夹结构 #

root
|-my-module
||-lib
|||-index.d.ts // 预期包含所有组件定义
|||-dict.enum.d.ts // 预期包含字典枚举
||-src
|||-components
||||-MyComponent.vue
|||-dict.enum.ts
|||-main.ts
|||-App.vue
|-project

我通过npm install ../my-module完成本地模块安装。

项目的tsconfig配置 #

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "skipLibCheck": true,

    /* Bundler mode */
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "preserve",

    /* Linting */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,

    /* Typing */
    "typeRoots": [
      "node_modules/@types",
      "node_modules/my-module"
    ]
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"],
  "references": [{ "path": "./tsconfig.node.json" }]
}

模块的package.json配置 #

{
    [...]
    "type": "module",
    "scripts": {
        "serve": "vite",
        "build": "vue-tsc --declaration && vite build",
        "preview": "vite preview"
    },
    "main": "./lib/my-module.umd.cjs",
    "module": "./lib/my-module.js",
    "exports": {
        ".": {
            "import": "./lib/my-module.js",
            "require": "./lib/my-module.umd.cjs"
        },
        "./style.css": "./lib/style.css"
    },
    "types": "./lib/index.d.ts",
    "dependencies": {
        "vite-plugin-dts": "^3.5.2",
        "vue": "^3.3.4"
    },
    "devDependencies": {
        "@vitejs/plugin-vue": "^4.2.3",
        "typescript": "^5.1.6",
        "vite": "^4.4.5",
        "vite-plugin-svg-icons": "^2.0.1",
        "vue-tsc": "^1.8.8"
    }
}

模块的Vite配置 #

import { defineConfig } from "vite";
import path, { resolve } from "path";
import { createSvgIconsPlugin } from "vite-plugin-svg-icons";
import vue from "@vitejs/plugin-vue";
import dts from "vite-plugin-dts";

export default defineConfig({
    plugins: [
        vue(),
        dts({
            rollupTypes: true 
        }),
    ],
    build: {
        outDir: './lib',
        lib: {
            entry: resolve(__dirname, "src/main.ts"),
            name: "MyModule",
            fileName: "my-module",
        },
        rollupOptions: {
            external: ["vue"],
            output: {
                globals: {
                    vue: "Vue",
                },
            },
        },
    },
});

执行构建脚本后，生成的index.d.ts内容为export * from '/main.ts'，路径明显异常。

解决方案 #

1. 修复vite-plugin-dts的声明生成路径问题 #

调整vite-plugin-dts配置，指定entryRoot为源码目录，避免生成绝对路径导出：

dts({
  rollupTypes: true,
  entryRoot: './src', // 指定源码根目录
  outputDir: './lib'  // 指定声明文件输出目录
}),

2. 移除重复的声明生成命令 #

你的build脚本同时执行vue-tsc --declaration和vite build，会导致两次生成声明文件冲突。vite-plugin-dts会在Vite构建过程中自动生成声明，因此修改package.json的build脚本：

"build": "vite build"

3. 优化项目的tsconfig配置 #

不需要手动配置typeRoots指向目标模块，TypeScript会自动读取node_modules中模块package.json的types字段。删除typeRoots配置，恢复默认逻辑：

/* Typing */
// 移除下面的typeRoots配置
// "typeRoots": [
//   "node_modules/@types",
//   "node_modules/my-module"
// ]

4. 重新构建并安装模块 #

1. 在my-module目录执行npm run build，检查lib/index.d.ts内容，确保导出路径为相对路径（如export * from './main'），且包含正确的类型定义。
2. 在project目录执行npm install ../my-module更新本地模块。
3. 重启TypeScript服务（如VSCode中按Ctrl+Shift+P选择"TypeScript: Restart TS Server"），让TS重新识别声明文件。

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