如何将MUI主题从宿主应用传递到自定义MUI组件库？

核心原因 #

组件库如果打包了独立的MUI实例，会和宿主应用的MUI实例形成隔离，导致主题无法跨实例传递。即便设置了peerDependency，若构建时未排除MUI代码，依然会出现主题不生效的问题。

具体解决方案 #

1. 组件库依赖配置

确保package.json中MUI相关包仅存在于peerDependencies，**绝对不能出现在dependencies**中，示例配置：

{
  "name": "jaa-my-component-library",
  "peerDependencies": {
    "@mui/material": "^5.0.0",
    "@emotion/react": "^11.0.0",
    "@emotion/styled": "^11.0.0"
  },
  "devDependencies": {
    "@mui/material": "^5.0.0",
    "@emotion/react": "^11.0.0",
    "@emotion/styled": "^11.0.0",
    // 其他开发依赖（vite、react等）
  }
}

这样组件库开发时会安装MUI用于本地调试，但发布时不会将MUI代码打包进去，完全依赖宿主应用提供的版本。

2. Vite构建配置排除MUI依赖

修改组件库的vite.config.js，在rollupOptions中把MUI相关包设为外部依赖，避免打包进组件库产物：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    lib: {
      entry: 'src/index.js', // 你的组件库入口文件
      name: 'JaaComponentLibrary',
      fileName: (format) => `jaa-component-library.${format}.js`,
    },
    rollupOptions: {
      // 排除MUI、React等核心依赖，由宿主应用提供
      external: ['@mui/material', '@emotion/react', '@emotion/styled', 'react', 'react-dom'],
      output: {
        // 为UMD格式提供全局变量映射（可选，非必须）
        globals: {
          react: 'React',
          'react-dom': 'ReactDOM',
          '@mui/material': 'MaterialUI',
          '@emotion/react': 'EmotionReact',
          '@emotion/styled': 'EmotionStyled',
        },
      },
    },
  },
});

3. 组件库组件不要嵌套ThemeProvider

组件库中的组件直接使用MUI组件即可，绝对不要在组件内部添加自己的ThemeProvider，否则会覆盖宿主应用的主题。示例：

// 组件库的JaaTable.jsx
import { Table, TableBody, TableCell, TableHead, TableRow } from '@mui/material';

export const JaaTable = ({ data }) => {
  // 直接使用MUI组件，无需额外嵌套ThemeProvider
  return (
    <Table>
      <TableHead>
        <TableRow>
          <TableCell>ID</TableCell>
          <TableCell>Name</TableCell>
        </TableRow>
      </TableHead>
      <TableBody>
        {data.map((row) => (
          <TableRow key={row.id}>
            <TableCell>{row.id}</TableCell>
            <TableCell>{row.name}</TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  );
};

4. 宿主应用正确配置ThemeProvider

确保宿主应用的ThemeProvider包裹整个应用，包括从组件库导入的所有组件：

// 宿主应用的App.jsx
import { ThemeProvider, createTheme } from '@mui/material/styles';
import CssBaseline from '@mui/material/CssBaseline';
import { JaaTable } from 'jaa-my-component-library';
import { Table, TableBody, TableCell, TableHead, TableRow } from '@mui/material';

// 自定义宿主应用主题
const theme = createTheme({
  palette: {
    mode: 'dark', // 切换light/dark测试明暗模式同步效果
    primary: {
      main: '#2196f3',
    },
  },
});

function App() {
  return (
    <ThemeProvider theme={theme}>
      <CssBaseline /> {/* 重置全局样式，确保主题完全生效 */}
      <div className="App">
        {/* 组件库的表格，会自动继承宿主主题 */}
        <JaaTable data={[{ id: 1, name: '组件库表格' }]} />
        
        {/* 宿主应用直接使用的MUI表格 */}
        <Table>
          <TableHead>
            <TableRow>
              <TableCell>ID</TableCell>
              <TableCell>Name</TableCell>
            </TableRow>
          </TableHead>
          <TableBody>
            <TableRow>
              <TableCell>1</TableCell>
              <TableCell>宿主表格</TableCell>
            </TableRow>
          </TableBody>
        </Table>
      </div>
    </ThemeProvider>
  );
}

export default App;

验证步骤 #

1. 重新构建组件库：npm run build
2. 发布更新后的组件库到npm（或本地用npm link快速测试）
3. 宿主应用更新组件库版本，重启开发服务
4. 切换宿主应用的明暗模式，检查组件库的表格是否同步变化

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