使用Yarn Workspaces时无法通过declare module扩展库类型

检查TypeScript配置的类型解析路径 #

• 在根目录的tsconfig.json中，确保compilerOptions里的typeRoots包含工作区的类型目录，示例配置：

  {
    "compilerOptions": {
      "typeRoots": ["./node_modules/@types", "./packages/*/@types"]
    }
  }
  

• 同时确认baseUrl与paths设置正确，保证TypeScript能解析工作区内部模块：

  "baseUrl": ".",
  "paths": {
    "@your-workspace/*": ["./packages/*/src"]
  }
  

规范类型扩展文件的命名与位置 #

• 在目标子包（如some-code-to-validate）内，创建src/types/vanilla-extract.d.ts，或直接放在子包根目录的@types/vanilla-extract/css/index.d.ts，文件需遵循正确的类型扩展语法：

  import '@vanilla-extract/css';
  
  declare module '@vanilla-extract/css' {
    export interface CustomStyleExtension {
      // 自定义类型内容
    }
  }
  

• 确保子包的tsconfig.json中include字段包含该类型文件：

  "include": ["src/**/*", "@types/**/*"]
  

排查依赖安装与版本问题 #

• 执行yarn install --force重新安装依赖，清除缓存可能引发的异常
• 确认根目录与所有子包的package.json中，@vanilla-extract/css的版本完全一致，避免版本冲突导致类型解析失败

验证TypeScript类型解析 #

• 在子包目录下执行tsc --noEmit，查看具体错误信息，定位是路径问题还是类型声明语法错误
• 检查是否存在重复的类型声明文件（如根目录与子包同时存在同库的类型文件），这类冲突会导致类型扩展失效

内容的提问来源于stack exchange，提问作者Святослав Марюха