Vue 3 NPM库sigma-scrollkit无法生成/导出TS类型问题

我正在开发一个Vue3虚拟滚动NPM库sigma-scrollkit。

问题描述 #

已在配置文件和package.json中指定类型路径，但无法生成TS类型。在其他项目中按以下方式导入时：

import {VirtualScroller, VirtualScrollerRow} from 'sigma-scrollkit';
import type {VirtualEntry} from 'sigma-scrollkit';

出现错误：

Cannot find module 'sigma-scrollkit' or its corresponding type declarations

库代码配置 #

Package.json #

"files": [
    "dist",
    "types/index.d.ts"
  ],
  "type": "module",
  "types": "./dist/types/index.d.ts",
  "typings": "./dist/types/index.d.ts",

tsconfig.json #

{
  "compilerOptions": {
    "outDir": "dist/types",
    "baseUrl": "./",
    "target": "esnext",
    "useDefineForClassFields": true,
    "module": "esnext",
    "moduleResolution": "node",
    "isolatedModules": true,
    "strict": true,
    "jsx": "preserve",
    "sourceMap": true,
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "lib": ["esnext", "dom", "dom.iterable", "scripthost"],
    "skipLibCheck": true
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"]
}

Vite配置 #

export default defineConfig({
  build: {
    lib: {
      entry: path.resolve(__dirname, 'src/index.ts'),
      name: 'sigma-scrollkit',
      fileName: 'sigma-scrollkit'
    },
    outDir: 'dist',
    emptyOutDir: true,
    minify: true,
    rollupOptions: {
      external: ['vue'],
      output: {
        // Global vars for UMD build
        globals: {
          vue: 'Vue'
        }
      }
    }
  },
  ...
})

解决步骤 #

1. 开启TypeScript声明生成
   你的tsconfig.json缺少生成类型文件的核心配置，需在compilerOptions中添加：

   "compilerOptions": {
     // ... 原有配置
     "declaration": true,
     "declarationMap": true, // 可选，生成类型映射文件方便调试
     "emitDeclarationOnly": false
   }
   

2. 补充类型生成命令
   Vite默认不会自动生成类型文件，需在package.json的scripts中添加类型生成步骤：

   "scripts": {
     "build": "vite build && tsc --emitDeclarationOnly"
   }
   

   执行npm run build时，会先构建库代码，再将类型文件生成到dist/types目录。

3. 校验类型文件与路径

   • 确认dist/types/index.d.ts文件存在，且正确导出了VirtualScroller、VirtualScrollerRow和VirtualEntry；
   • 修正package.json的files字段，确保包含所有类型文件：

     "files": [
       "dist",
       "dist/types/**/*.d.ts"
     ]
     

   • 保留types字段即可，typings字段与它作用重复，可删除。

4. 本地测试链路排查
   用npm link关联本地库后，若测试项目仍报错：

   • 检查测试项目的tsconfig.json是否排除了node_modules的类型检查；
   • 尝试直接将本地库的dist目录复制到测试项目的node_modules/sigma-scrollkit下，验证是否是link导致的路径问题。

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