Vite构建的React Monorepo组件多实例问题咨询与解决方案

我有一个基于 Node 的 TS React Monorepo 方案，包含 Shared Components 应用，使用 Vite 构建 Web 应用。项目结构如下：

- root-app/
  - node_modules/
  - package.json
  - ...
  - shared-components/
    - node_modules/
    - package.json
    - Components
      - Context
      - GrommetWrapper
    - ...
  - webapp/
    - node_modules/
    - package.json
    - ...

目前遇到 App Context、Grommet 主题等组件被多次实例化的问题，导致异常行为与性能问题，现咨询以下问题：

1. 如何确保 App Context 和 Grommet 主题在整个应用中仅创建一个实例？ #

核心思路：单例化定义 + 统一依赖树 #

（1）单例化 Context 与主题配置

在 shared-components 中仅一次定义 Context 和 Grommet 主题实例，避免在多个模块或子应用中重复创建：

// shared-components/src/Context/AppContext.tsx
import { createContext, useContext, ReactNode } from 'react';

// 模块级别创建单例 Context
const AppContext = createContext<{ user: { name: string } | null } | undefined>(undefined);

export const AppProvider = ({ children }: { children: ReactNode }) => {
  const value = { user: { name: 'Test User' } };
  return <AppContext.Provider value={value}>{children}</AppContext.Provider>;
};

export const useAppContext = () => {
  const context = useContext(AppContext);
  if (!context) throw new Error('useAppContext 必须在 AppProvider 内部使用');
  return context;
};

// shared-components/src/Components/GrommetWrapper/GrommetTheme.ts
// 单例主题配置
export const grommetTheme = {
  global: { colors: { brand: '#228BE6' } }
};

// shared-components/src/Components/GrommetWrapper/GrommetWrapper.tsx
import { Grommet } from 'grommet';
import { grommetTheme } from './GrommetTheme';

export const GrommetWrapper = ({ children }: { children: ReactNode }) => {
  return <Grommet theme={grommetTheme}>{children}</Grommet>;
};

（2）在 Web 应用顶层仅渲染一次 Provider

在 webapp 的入口文件中，仅在最外层包裹一次 Provider 和 GrommetWrapper：

// webapp/src/EntryClient.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { AppProvider } from 'shared-components/Components/Context/AppContext';
import { GrommetWrapper } from 'shared-components/Components/GrommetWrapper/GrommetWrapper';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <AppProvider>
      <GrommetWrapper>
        <App />
      </GrommetWrapper>
    </AppProvider>
  </React.StrictMode>
);

（3）强制依赖统一

配置 Vite 确保 React、Grommet 等依赖指向根目录的 node_modules，避免子包重复安装：

// webapp/vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      'react': path.resolve(__dirname, '../node_modules/react'),
      'react-dom': path.resolve(__dirname, '../node_modules/react-dom'),
      'grommet': path.resolve(__dirname, '../node_modules/grommet'),
      'shared-components': path.resolve(__dirname, '../shared-components/src')
    }
  },
  optimizeDeps: { include: ['react', 'react-dom', 'grommet'] }
});

2. 使用 Vite 构建含共享组件的 Monorepo 的最佳实践 #

（1）用 Workspace 统一依赖管理 #

在根目录 package.json 中配置 Workspace，将公共依赖（React、TypeScript、Vite 等）安装在根目录，子包声明为 peerDependencies：

// root-app/package.json
{
  "name": "root-app",
  "private": true,
  "workspaces": ["shared-components", "webapp"],
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "grommet": "^2.34.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "vite": "^5.0.0",
    "@vitejs/plugin-react": "^4.2.0"
  }
}

（2）统一 TypeScript 配置 #

根目录创建 tsconfig.json，子包继承该配置，确保类型规则一致：

// root-app/tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "jsx": "react-jsx",
    "strict": true,
    "moduleResolution": "bundler",
    "skipLibCheck": true,
    "noEmit": true
  },
  "include": ["shared-components/src", "webapp/src"],
  "references": [{ "path": "./shared-components" }, { "path": "./webapp" }]
}

（3）共享组件按库模式构建 #

配置 shared-components 的 Vite 为库模式，避免打包 React 等依赖：

// shared-components/vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    lib: {
      entry: 'src/index.ts',
      name: 'SharedComponents',
      formats: ['es', 'cjs'],
      fileName: (format) => `shared-components.${format}.js`
    },
    rollupOptions: {
      external: ['react', 'react-dom', 'grommet'],
      output: {
        globals: { react: 'React', 'react-dom': 'ReactDOM', grommet: 'Grommet' }
      }
    }
  }
});

（4）本地开发优化 #

• 用路径别名直接引入共享组件源码，避免 npm link 带来的依赖冲突
• 开启 Vite 的 optimizeDeps 缓存，确保公共依赖仅预构建一次

3. 排查与修复该问题的其他建议 #

• 检查依赖重复：执行 npm ls react 或 pnpm list react，查看是否存在多版本依赖，若子包 node_modules 中有 React/Grommet，需删除子包 node_modules 后重新从根目录安装
• 调试实例创建：在 Context/主题定义处添加日志（console.log('创建 AppContext 实例')），若多次打印则追踪引入路径，定位重复创建的模块
• 用 React DevTools 检查：查看组件树中相同 Provider 的数量，若存在多个则定位重复渲染的代码位置
• 验证导出逻辑：确保共享组件导出的是模块级别的单例，而非在函数内部动态创建实例
• 清理缓存：删除 Vite 的 .vite 缓存目录，重新构建应用，排除缓存导致的依赖重复问题

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