如何让peer dependency的模块扩展在下游CRA项目中正常生效？

解决方案 #

你可以按照以下几个步骤配置，就能让包内的MUI主题模块扩展在下游CRA项目中生效：

1. 调整类型声明文件结构 #

不要把模块扩展代码写在普通业务源码文件中，单独在包根目录新建augment-mui.d.ts全局类型声明文件，内容示例如下：

// augment-mui.d.ts
import '@mui/material/styles';

declare module '@mui/material/styles' {
  // 扩展Theme接口，添加你的自定义字段
  interface Theme {
    customConfig: {
      brandColor: string;
      cardRadius: number;
    };
  }
  // 同步扩展ThemeOptions，避免创建主题时类型报错
  interface ThemeOptions {
    customConfig?: {
      brandColor?: string;
      cardRadius?: number;
    };
  }
}

2. 修改package.json配置 #

• 新增types字段，指向打包后的类型入口，比如："types": "./dist/index.d.ts"
• 确保files字段包含所有.d.ts类型文件，或者在TS配置中开启自动打包类型声明的能力，TSDX默认已支持该能力，无需额外配置
• 确认peerDependencies字段中已声明兼容的MUI v5版本范围

3. 显式引入扩展声明到类型入口 #

在你包的类型入口文件（一般是src/index.ts）顶部，添加一行三斜杠指令，显式引用你的扩展声明文件：

/// <reference path="../augment-mui.d.ts" />

4. 下游项目适配 #

如果下游是TypeScript版CRA，默认TS配置会自动加载node_modules下的类型声明，无需额外修改；如果是纯JavaScript版CRA，只要项目开启了checkJs配置或安装了TypeScript语法支持插件，也会自动识别你包内的类型扩展。 #

常见注意事项 #

• 不要在全局类型声明文件中添加普通export导出语句，否则TS会将其识别为普通模块，不会自动生效全局类型扩展
• 不要把MUI相关依赖配置到dependencies中，避免下游项目出现重复安装MUI的问题

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