將公司專案轉換成 Monorepo 遇到的那些事 - 第十篇 未來的 Monorepo：Module Federation 微前端的實務落地

// portal/src/App.tsx
import React, { Suspense, lazy } from 'react';
import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom';
import { Layout } from './components/Layout';
import { AuthGuard } from './components/AuthGuard';
import { ModuleLoadingSpinner } from './components/ModuleLoadingSpinner';

// 動態載入各個模組
const FinanceModule = lazy(() => import('finance/Module'));
const LogisticsModule = lazy(() => import('logistics/Module'));

function App() {
  return (
    <BrowserRouter>
      <Layout>
        <AuthGuard>
          <Routes>
            {/* 首頁重定向 */}
            <Route path="/" element={<Navigate to="/dashboard" replace />} />

            {/* 各個業務模組的路由 */}
            <Route
              path="/finance/*"
              element={
                <Suspense fallback={<ModuleLoadingSpinner module="財務管理" />}>
                  <FinanceModule />
                </Suspense>
              }
            />

            <Route
              path="/logistics/*"
              element={
                <Suspense fallback={<ModuleLoadingSpinner module="物流管理" />}>
                  <LogisticsModule />
                </Suspense>
              }
            />

            {/* 404 處理 */}
            <Route path="*" element={<NotFoundPage />} />
          </Routes>
        </AuthGuard>
      </Layout>
    </BrowserRouter>
  );
}

// finance/src/FinanceModule.tsx
import React from 'react';
import { Routes, Route } from 'react-router-dom';
import { FinanceNavigation } from './components/FinanceNavigation';

// 財務模組的各個頁面
import { BillingPage } from './pages/BillingPage';
import { InvoicePage } from './pages/InvoicePage';
import { PaymentPage } from './pages/PaymentPage';

export const FinanceModule = () => {
  return (
    <div className="finance-module">
      <FinanceNavigation />
      <div className="finance-content">
        <Routes>
          {/* 模組內部的路由 */}
          <Route index element={<Navigate to="billing" replace />} />
          <Route path="billing" element={<BillingPage />} />
          <Route path="invoice/*" element={<InvoicePage />} />
          <Route path="payment/*" element={<PaymentPage />} />
        </Routes>
      </div>
    </div>
  );
};

// shared/hooks/useAppNavigation.ts
import { useNavigate, useLocation } from 'react-router-dom';
import { useCallback } from 'react';

export const useAppNavigation = () => {
  const navigate = useNavigate();
  const location = useLocation();

  const navigateToModule = useCallback((module: string, path: string = '') => {
    const fullPath = `/${module}${path ? `/${path}` : ''}`;
    navigate(fullPath);
  }, [navigate]);

  const navigateToFinance = useCallback((subPath?: string) => {
    navigateToModule('finance', subPath);
  }, [navigateToModule]);

  const navigateToLogistics = useCallback((subPath?: string) => {
    navigateToModule('logistics', subPath);
  }, [navigateToModule]);

  return {
    navigateToModule,
    navigateToFinance,
    navigateToLogistics,
    currentPath: location.pathname,
    goBack: () => navigate(-1),
  };
};

// 在任何模組中都可以直接使用
// const { navigateToFinance } = useAppNavigation();
// navigateToFinance('billing/create-invoice');

// shared/components/Breadcrumb.tsx
import React from 'react';
import { useLocation } from 'react-router-dom';
import { Breadcrumb as AntBreadcrumb } from 'antd';

const moduleNameMap = {
  finance: '財務管理',
  logistics: '物流管理',
};

const pathNameMap = {
  billing: '帳單管理',
  invoice: '發票管理',
  payment: '付款管理',
  dashboard: '儀表板',
};

export const AppBreadcrumb = () => {
  const location = useLocation();
  const pathSegments = location.pathname.split('/').filter(Boolean);

  const breadcrumbItems = pathSegments.map((segment, index) => {
    const isModule = index === 0;
    const displayName = isModule
      ? moduleNameMap[segment] || segment
      : pathNameMap[segment] || segment;

    const path = '/' + pathSegments.slice(0, index + 1).join('/');

    return {
      title: displayName,
      path: path,
    };
  });

  return (
    <AntBreadcrumb
      items={breadcrumbItems.map((item) => ({
        title: <Link to={item.path}>{item.title}</Link>,
      }))}
    />
  );
};

// 獨立微前端的複雜路由協調（僅作對比說明）
class MicrofrontendRouterCoordinator {
  constructor() {
    this.activeRoutes = new Map();
    this.routeHistory = [];
    this.setupEventListeners();
  }

  setupEventListeners() {
    // 監聽各個微前端的路由變化
    window.addEventListener('microfrontend-route-change', (event) => {
      this.handleRouteChange(event.detail);
    });

    // 監聽瀏覽器前進後退
    window.addEventListener('popstate', (event) => {
      this.handleBrowserNavigation(event.state);
    });
  }

  handleRouteChange({ microfrontendId, newRoute, oldRoute }) {
    // 更新活躍路由記錄
    this.activeRoutes.set(microfrontendId, newRoute);

    // 同步到其他微前端
    this.broadcastRouteChange(microfrontendId, newRoute);

    // 更新瀏覽器歷史
    this.updateBrowserHistory();
  }

  handleBrowserNavigation(state) {
    // 當使用者點擊前進後退時，需要協調各個微前端
    if (state && state.microfrontendRoutes) {
      Object.entries(state.microfrontendRoutes).forEach(([id, route]) => {
        this.notifyMicrofrontend(id, route);
      });
    }
  }

  // 這只是複雜實現的冰山一角...
}

// Module Federation 中的深層連結天然支援
// 使用者直接訪問 https://app.company.com/finance/invoice/INV-12345
// 系統會自然地：
// 1. 載入 finance 模組
// 2. 在 finance 模組內路由到 invoice/INV-12345
// 3. 渲染對應的發票詳情頁面

// finance/src/pages/InvoicePage.tsx
import { useParams } from 'react-router-dom';

export const InvoiceDetailPage = () => {
  const { invoiceId } = useParams(); // 直接獲取 URL 參數

  // 無需任何特殊處理，與單體應用程式完全相同
  return (
    <div>
      <h1>發票詳情：{invoiceId}</h1>
      {/* 發票內容 */}
    </div>
  );
};

// portal/src/components/AuthGuard.tsx
import React from 'react';
import { useLocation, Navigate } from 'react-router-dom';
import { useSelector } from 'react-redux';
import { RootState } from '../store';

const routePermissions = {
  '/finance': ['finance.read', 'admin'],
  '/finance/billing': ['finance.billing', 'admin'],
  '/logistics': ['logistics.read', 'admin'],
};

export const AuthGuard: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const location = useLocation();
  const { user, permissions } = useSelector((state: RootState) => state.auth);

  const checkPermission = (path: string) => {
    const requiredPermissions = routePermissions[path] || [];
    return requiredPermissions.some(permission =>
      permissions.includes(permission) || permissions.includes('admin')
    );
  };

  if (!user) {
    return <Navigate to="/login" state={{ from: location }} replace />;
  }

  const hasPermission = checkPermission(location.pathname);
  if (!hasPermission) {
    return <Navigate to="/unauthorized" replace />;
  }

  return <>{children}</>;
};

// config/routeConfig.ts
export const MODULE_ROUTES = {
  // 核心業務模組
  FINANCE: {
    prefix: '/finance',
    children: {
      billing: '/billing',
      invoice: '/invoice',
      payment: '/payment',
    }
  },

  LOGISTICS: {
    prefix: '/logistics',
    children: {
      shipment: '/shipment',
      tracking: '/tracking',
    }
  },

  // 管理功能模組
  ADMIN: {
    prefix: '/admin',
    children: {
      users: '/users',
      roles: '/roles',
      settings: '/settings',
    }
  },

  // 工具模組
  TOOLS: {
    prefix: '/tools',
    children: {
      integration: '/integration',
      workflow: '/workflow',
      reporting: '/reporting',
    }
  }
} as const;

// 路由建置工具
export const buildRoute = (module: keyof typeof MODULE_ROUTES, subPath?: string) => {
  const moduleConfig = MODULE_ROUTES[module];
  return `${moduleConfig.prefix}${subPath || ''}`;
};

// 使用範例
// const financeInvoiceRoute = buildRoute('FINANCE', '/invoice/create');
// 結果：'/finance/invoice/create'

// config/routeGuards.ts
interface RouteGuardConfig {
  path: string;
  permissions: string[];
  roles: string[];
  redirectTo?: string;
  loadingComponent?: React.ComponentType;
}

export const routeGuards: RouteGuardConfig[] = [
  {
    path: '/finance/*',
    permissions: ['finance.access'],
    roles: ['finance_user', 'admin'],
    redirectTo: '/unauthorized'
  },
  {
    path: '/finance/billing/*',
    permissions: ['finance.billing'],
    roles: ['finance_manager', 'admin'],
  },
  {
    path: '/admin/*',
    permissions: ['admin.access'],
    roles: ['admin'],
    redirectTo: '/dashboard'
  },
];

// portal/src/components/RouteGuard.tsx
import React from 'react';
import { useMatch } from 'react-router-dom';
import { routeGuards } from '../../config/routeGuards';

export const RouteGuard: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const matchedGuard = routeGuards.find(guard =>
    useMatch({ path: guard.path, end: false })
  );

  if (matchedGuard) {
    // 執行權限檢查邏輯
    const hasPermission = checkUserPermissions(matchedGuard);
    if (!hasPermission) {
      return <Navigate to={matchedGuard.redirectTo || '/unauthorized'} />;
    }
  }

  return <>{children}</>;
};

enterprise-monorepo/
├── apps/
│   ├── portal/                    # Container 應用
│   ├── finance/                   # 財務管理模組
│   ├── logistics/                 # 物流管理模組
├── libs/
│   ├── shared/
│   │   ├── components/            # 共享 UI 組件
│   │   ├── hooks/                 # 共享 React Hooks
│   │   ├── utils/                 # 工具函數庫
│   │   ├── data-access/           # API 封裝
│   │   ├── types/                 # TypeScript 類型定義
│   │   └── assets/                # 共享資源
│   ├── feature-common/            # 通用業務功能
│   └── config/                    # 配置管理
└── tools/
    ├── webpack/                   # Webpack 配置
    └── deploy/                    # 部署腳本

// portal/module-federation.config.js
const ModuleFederationPlugin = require('webpack/lib/container/ModuleFederationPlugin');

const createRemoteConfig = (environment) => {
  const remoteUrls = {
    development: {
      finance: 'http://localhost:4001',
      logistics: 'http://localhost:4002',
    },
    production: {
      finance: 'https://cdn.company.com/finance',
      logistics: 'https://cdn.company.com/logistics',
    },
  };

  return Object.entries(remoteUrls[environment]).reduce((acc, [name, url]) => {
    acc[name] = `${name}@${url}/remoteEntry.js`;
    return acc;
  }, {});
};

module.exports = {
  name: 'portal',
  remotes: createRemoteConfig(process.env.NODE_ENV),
  shared: {
    react: { singleton: true, eager: true },
    'react-dom': { singleton: true, eager: true },
    'react-router-dom': { singleton: true },
    '@reduxjs/toolkit': { singleton: true },
    antd: { singleton: true },
  },
  // 關鍵依賴的 blacklist 策略
  shareScope: (name, config) => {
    const blacklist = [
      '@company/shared-components',
      '@company/shared-hooks',
      '@company/shared-utils',
      'react-phone-number-input',
    ];

    if (blacklist.includes(name)) {
      return false;
    }
    return config;
  },
};

// finance/module-federation.config.js
module.exports = {
  name: 'finance',
  filename: 'remoteEntry.js',
  exposes: {
    './Module': './src/bootstrap.tsx',
    './routes': './src/routes.tsx',
    './store': './src/store/index.ts',
  },
  shared: {
    react: { singleton: true },
    'react-dom': { singleton: true },
  },
};

// finance/src/bootstrap.tsx
import React from 'react';
import { Provider } from 'react-redux';
import { store } from './store';
import { FinanceModule } from './FinanceModule';

export const FinanceApp = () => {
  return (
    <Provider store={store}>
      <FinanceModule />
    </Provider>
  );
};

export default FinanceApp;

// portal/src/routing/DynamicRouteLoader.tsx
import React, { Suspense, lazy } from 'react';
import { Route, Routes } from 'react-router-dom';
import { ModuleRegistry } from './ModuleRegistry';

const DynamicRouteLoader = () => {
  const moduleConfigs = [
    {
      path: '/finance/*',
      module: 'finance',
      component: lazy(() => import('finance/Module')),
    },
    {
      path: '/logistics/*',
      module: 'logistics',
      component: lazy(() => import('logistics/Module')),
    },
  ];

  return (
    <Routes>
      {moduleConfigs.map(({ path, module, component: Component }) => (
        <Route
          key={module}
          path={path}
          element={
            <Suspense fallback={<ModuleLoadingFallback module={module} />}>
              <ErrorBoundary module={module}>
                <Component />
              </ErrorBoundary>
            </Suspense>
          }
        />
      ))}
    </Routes>
  );
};

// shared/store/rootStore.ts
import { configureStore } from '@reduxjs/toolkit';
import { authSlice } from './auth/authSlice';
import { uiSlice } from './ui/uiSlice';
import { notificationSlice } from './notification/notificationSlice';

// 動態載入模組 store
const createRootStore = () => {
  const store = configureStore({
    reducer: {
      auth: authSlice.reducer,
      ui: uiSlice.reducer,
      notifications: notificationSlice.reducer,
      // 模組專用的 store slice 會在運行時動態註冊
    },
    middleware: (getDefaultMiddleware) =>
      getDefaultMiddleware({
        serializableCheck: {
          ignoredActions: ['persist/PERSIST', 'persist/REHYDRATE'],
        },
      }),
  });

  // 提供模組動態註冊 reducer 的能力
  store.registerModuleReducer = (moduleName, reducer) => {
    store.replaceReducer({
      ...store.getState(),
      [moduleName]: reducer,
    });
  };

  return store;
};

export const globalStore = createRootStore();

// tools/webpack/module-federation-base.js
const createSharedConfig = (excludeList = []) => {
  const defaultBlacklist = [
    // 狀態管理相關 - 需要全局唯一
    '@company/shared-components',
    '@company/shared-hooks',
    '@company/shared-utils',

    // 版本敏感的第三方庫
    'react-phone-number-input',
    'moment',
    'lodash',

    // 性能考量 - 直接打包更好
    'crypto-js',
    'validator',
  ];

  const combinedBlacklist = [...defaultBlacklist, ...excludeList];

  return (packageName, config) => {
    if (combinedBlacklist.includes(packageName)) {
      return false; // 不共享，各模組獨立打包
    }

    // 針對大型庫的特殊處理
    if (packageName === 'antd') {
      return {
        singleton: true,
        requiredVersion: '^5.0.0',
        eager: true,
      };
    }

    return config;
  };
};

// portal/src/components/ModuleErrorBoundary.tsx
class ModuleErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false, retryCount: 0 };
  }

  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  componentDidCatch(error, errorInfo) {
    // 記錄模組載入失敗
    console.error(`Module ${this.props.moduleName} failed to load:`, error);

    // 嘗試重新載入模組（最多3次）
    if (this.state.retryCount < 3) {
      setTimeout(() => {
        this.setState({
          hasError: false,
          retryCount: this.state.retryCount + 1,
        });
      }, 2000);
    }
  }

  render() {
    if (this.state.hasError) {
      return (
        <div className="module-error-fallback">
          <h3>模組暫時無法載入</h3>
          <p>我們正在嘗試重新連接...</p>
          <button onClick={() => window.location.reload()}>重新整理頁面</button>
        </div>
      );
    }

    return this.props.children;
  }
}

// tools/webpack/environment-config.js
const createEnvironmentConfig = (env) => {
  const configs = {
    development: {
      remoteType: 'script',
      remoteUrls: {
        finance: 'http://localhost:4001/remoteEntry.js',
        logistics: 'http://localhost:4002/remoteEntry.js',
      },
      cacheGroups: {
        vendor: false, // 開發環境不分割 vendor chunk
      },
    },
    production: {
      remoteType: 'script',
      remoteUrls: {
        finance: 'https://cdn.company.com/v2/finance/remoteEntry.[hash].js',
        logistics: 'https://cdn.company.com/v2/logistics/remoteEntry.[hash].js',
      },
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          chunks: 'all',
          name: 'vendors',
        },
      },
    },
  };

  return configs[env] || configs.development;
};

// nx.json (簡化版)
{
  "tasksRunnerOptions": {
    "default": {
      "runner": "@nx/s3-remote-cache",
      "options": {
        "cacheableOperations": ["build", "lint", "test"],
        "bucket": "company-nx-cache",
        "region": "ap-southeast-1"
      }
    }
  },
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "cache": true
    }
  }
}

// 在 Module Federation 中的使用
// 這些庫被列入 blacklist，確保版本一致性
import { sharedComponents } from '@company/shared-components';
// 各個模組直接使用，無需擔心跨模組通信