Monorepo中npm link本地React UI包至应用时类型声明缺失问题

在npm工作区（Monorepo）中，将自研React UI库通过npm link关联到另一个React应用后，库文件夹已出现在主应用的node_modules目录下，但仍出现TypeScript错误：

Could not find a declaration file for module 'ui'. 'C:/Users/.../Documents/.../.../packages/ui/lib/index.js' implicitly has an 'any' type.

UI库的package.json配置 #

{
  "name": "ui",
  "private": true,
  "version": "1.0.0",
  "license": "UNLICENSED",
  "scripts": {
    "dev": "vite",
    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
    "preview": "vite preview"
  },
  "peerDependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "@types/node": "^20.6.3",
    "@types/react": "^18.2.15",
    "@types/react-dom": "^18.2.7",
    "@typescript-eslint/eslint-plugin": "^6.0.0",
    "@typescript-eslint/parser": "^6.0.0",
    "@vitejs/plugin-react": "^4.0.3",
    "eslint": "^8.45.0",
    "eslint-plugin-react-hooks": "^4.6.0",
    "eslint-plugin-react-refresh": "^0.4.3",
    "react": "^17.0.2 || ^18.2.0",
    "react-dom": "^17.0.2 || ^18.2.0",
    "typescript": "^5.0.2",
    "vite": "^4.4.5",
    "vite-plugin-dts": "^3.5.3"
  },
  "main": "./lib/index.js",
  "module": "dist/ptr-ui.es.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/ptr-ui.es.js",
      "require": "./dist/ptr-ui.umd.js",
      "types": "./dist/index.d.ts"
    }
  },
  "dependencies": {
    "@tanstack/react-table": "^8.10.3"
  }
}

主应用的package.json配置 #

{
  "name": "client-app",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@types/md5": "^2.2.1",
    "@types/react": "^17.0.38",
    "@types/react-dom": "^17.0.11",
    "md5": "^2.3.0",
    "merge": "^1.2.1",
    "moment": "^2.29.2",
    "node-sass": "npm:sass@^1.26.5",
    "oidc-client": "^1.9.1",
    "print-js": "^1.6.0",
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "react-json-pretty": "^2.2.0",
    "react-scripts": "^5.0.1",
    "rimraf": "^2.7.1",
    "ui": "1.0.0"
  },
  "devDependencies": {
    "@types/node": "^17.0.5",
    "react-app-env": "^1.2.3",
    "react-context-devtool": "^2.0.3",
    "typescript": "^4.5.4"
  },
  "eslintConfig": {
    "extends": "react-app"
  },
  "browserslist": [
    ">0.2%",
    "not dead",
    "not op_mini all"
  ]
}

两者使用相同Node版本，以下是排查方案：

• 检查UI库类型文件是否生成：给UI库的scripts添加"build": "vite build"并执行，确认dist目录下是否生成index.d.ts及相关类型文件。vite-plugin-dts仅在构建时生成完整类型，dev模式不会自动生成。
• 统一package.json路径配置：UI库的main指向lib目录，但types和exports指向dist，路径不一致。要么将main改为./dist/index.js，统一输出到dist；要么调整types和exports路径到lib，确保TypeScript能匹配到类型文件。
• 修正主应用TypeScript配置：在主应用tsconfig.json中添加路径映射，明确UI库的类型文件位置：

  {
    "compilerOptions": {
      "baseUrl": ".",
      "paths": {
        "ui": ["../packages/ui/dist"] // 根据实际目录调整
      },
      "moduleResolution": "node16"
    }
  }
  

  同时确保include字段覆盖到关联库的类型文件路径。
• 清除缓存并重新关联：
  1. 在UI库执行npm unlink，主应用执行npm unlink ui
  2. 删除主应用node_modules/.cache（若存在）及UI库的构建缓存
  3. 重新在UI库执行npm link，主应用执行npm link ui
• 对齐TypeScript版本：UI库用TS 5.0.2，主应用用4.5.4，版本差异可能导致类型解析异常。将主应用TS版本升级到与UI库一致的兼容版本。
• 检查private字段影响：UI库private: true可能导致元数据解析异常，临时改为false，重新构建关联后测试。

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