Host và remote đầu tiên

Bạn đã mở được shell và catalog ở hai port riêng. Bước tiếp theo là để shell hiển thị UI của catalog mà không import source catalog vào build của mình. Khi làm được điều đó, bạn mới có một đường tải remote để quan sát, thay vì chỉ có hai frontend đặt cạnh nhau.

Bài này dựng lát cắt nhỏ nhất: shell tải một React component do catalog expose qua Module Federation của webpack 5. Catalog vẫn chạy standalone để bạn kiểm tra UI mà không phụ thuộc shell.

Mục lụcCopy Anchor Link

• Kết quả cần đạt
• Đường tải module và các tên cần phân biệt
• Cài React và JSX tooling
• Tạo remote catalog
  • Viết component công khai
  • Tạo entry standalone với async boundary
  • Cấu hình webpack cho catalog
• Tạo host shell
  • Khai báo URL remote và shared dependencies
  • Tạo entry React cho shell
  • Render remote với loading và fallback
• Vì sao cần các cấu hình này
  • Async boundary không phải eager loading
  • Shared React không phải shared state
  • Asset của remote phải tải từ remote
• Chạy và kiểm chứng
  • Mở hai dev server
  • Quan sát Network
  • Đổi catalog mà không rebuild shell
  • Build từng app độc lập
• Những lỗi thường gặp
• Checklist hoàn thành
• Bước tiếp theo
• Tài liệu tham khảo

Kết quả cần đạtCopy Anchor Link

Sau bài này, hai trang có vai trò khác nhau:

Bài chưa thêm routing, nút thêm giỏ, cart controller, API, auth hay CSS tooling. Vì mục tiêu là kiểm chứng đường tải module, mình dùng JavaScript và JSX trước; public types và kiểm tra tương thích sẽ được bàn ở các bài Module Federation.

Phần code mới trong hai app có cấu trúc như sau. Giữ package.json và scripts từ bài workspace; lệnh cài đặt sẽ bổ sung dependency vào đúng manifest.

Đường tải module và các tên cần phân biệtCopy Anchor Link

Host là bên consume module; remote là bên expose module. Trong ví dụ này, shell chỉ consume, catalog chỉ expose. Một build có thể làm cả hai, nhưng chưa cần dùng khả năng đó ở bước đầu.

direction: down
n0: "Browser mở shell :3000"
n1: "React.lazy tải CatalogPage"
n2: ":3001/remoteEntry.js"
n3: "Khởi tạo share scope\nLấy ./CatalogPage"
n4: "Chunks từ :3001"
n5: "Render trong React tree của\nshell"
n0 -> n1 -> n2 -> n3 -> n4 -> n5

Đây không phải iframe. Browser không mở trang HTML của catalog rồi nhúng vào shell; nó tải JavaScript của remote và chạy component trong cùng trang, cùng React tree. Vì vậy, remote cũng dùng chung môi trường DOM và quyền thực thi JavaScript của trang host, không có isolation như một iframe khác origin.

Trước khi viết config, chốt các tên sau:

Hai tên catalog và shop_catalog cố ý khác nhau. Trong chuỗi shop_catalog@http://localhost:3001/remoteEntry.js, phần trước @ phải khớp container phía remote; key catalog là tên host tự chọn để import.

remoteEntry.js là điểm vào container, không nhất thiết chứa toàn bộ implementation của catalog. Sau khi tải entry, webpack còn có thể tải các chunk chứa component và dependency. Đừng chỉ kiểm tra entry trả HTTP 200 rồi kết luận remote đã dùng được.

Cài React và JSX toolingCopy Anchor Link

Dừng dev server shell/catalog nếu đang chạy, rồi cài từ root shop-workspace:

npm install --save-exact react@19 react-dom@19 --workspace=@shop/shell --workspace=@shop/catalog
npm install --save-dev --save-exact @babel/core@7 @babel/preset-react@7 babel-loader@9 --workspace=@shop/shell --workspace=@shop/catalog

Lệnh đầu chọn major React 19 và ghi version chính xác được resolve vào manifest của hai app. Giữ React và React DOM cùng version trong lab; nếu workspace đã có React, kiểm tra lại thay vì để hai app dùng version khác nhau ngoài ý muốn.

npm ls react react-dom --workspace=@shop/shell --workspace=@shop/catalog

Lệnh thứ hai bổ sung JSX transform. ModuleFederationPlugin đã có trong webpack 5, nên không cài thêm package Federation. @babel/preset-react xử lý JSX; bài không cần @babel/preset-env vì chỉ nhắm đến browser hiện đại dùng cho lab.

Các config bên dưới khai báo Babel options trực tiếp trong loader, không cần .babelrc. Mình đặt runtime: 'classic' rõ ràng: JSX được chuyển thành React.createElement, nên mỗi file có JSX đều import React. Cách này giữ ví dụ focused vào các request React đã khai báo shared, chưa phát sinh react/jsx-runtime từ automatic runtime.

Commit manifest và package-lock.json sau khi kiểm tra. Trên máy khác, dùng npm ci từ root với lockfile đó để cài lại đúng bộ dependency.

Tạo remote catalogCopy Anchor Link

import React from 'react';

const products = [
  { sku: 'ao-thun-den', name: 'Áo thun đen', price: 150000 },
  { sku: 'tui-vai', name: 'Túi vải', price: 80000 },
  { sku: 'binh-nuoc', name: 'Bình nước', price: 120000 },
];

const priceFormatter = new Intl.NumberFormat('vi-VN', {
  style: 'currency',
  currency: 'VND',
});

export default function CatalogPage() {
  return (
    <section aria-labelledby="catalog-title">
      <h2 id="catalog-title">Catalog</h2>
      <p>Component này đến từ remote catalog.</p>
      <ul>
        {products.map((product) => (
          <li key={product.sku}>
            {product.name} — {priceFormatter.format(product.price)}
          </li>
        ))}
      </ul>
    </section>
  );
}

import('./bootstrap').catch((error) => {
  console.error('Không khởi động được catalog standalone.', error);
  document.body.textContent = 'Catalog standalone không khởi động được.';
});

import React from 'react';
import { createRoot } from 'react-dom/client';
import CatalogPage from './CatalogPage';

const container = document.createElement('div');
container.id = 'root';
document.body.appendChild(container);

createRoot(container).render(
  <main>
    <h1>Catalog standalone</h1>
    <CatalogPage />
  </main>,
);

const path = require('node:path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
const { ModuleFederationPlugin } = require('webpack').container;
const { dependencies } = require('./package.json');

module.exports = {
  context: __dirname,
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash].js',
    chunkFilename: '[name].[contenthash].js',
    publicPath: 'auto',
    uniqueName: '_shop_catalog',
    clean: true,
  },
  resolve: {
    extensions: ['.jsx', '.js', '.json'],
  },
  module: {
    rules: [
      {
        test: /\.jsx?$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: [
              ['@babel/preset-react', { runtime: 'classic' }],
            ],
          },
        },
      },
    ],
  },
  plugins: [
    new ModuleFederationPlugin({
      name: 'shop_catalog',
      filename: 'remoteEntry.js',
      exposes: {
        './CatalogPage': './src/CatalogPage.jsx',
      },
      shared: {
        react: {
          singleton: true,
          requiredVersion: dependencies.react,
          strictVersion: true,
        },
        'react-dom': {
          singleton: true,
          requiredVersion: dependencies['react-dom'],
          strictVersion: true,
        },
        'react-dom/client': {
          singleton: true,
          packageName: 'react-dom',
          requiredVersion: dependencies['react-dom'],
          strictVersion: true,
        },
      },
    }),
    new HtmlWebpackPlugin({
      title: 'Shop catalog standalone',
    }),
  ],
  devServer: {
    host: 'localhost',
    static: false,
  },
};

Tạo host shellCopy Anchor Link

const path = require('node:path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
const { ModuleFederationPlugin } = require('webpack').container;
const { dependencies } = require('./package.json');

module.exports = {
  context: __dirname,
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash].js',
    chunkFilename: '[name].[contenthash].js',
    publicPath: 'auto',
    uniqueName: '_shop_shell',
    clean: true,
  },
  resolve: {
    extensions: ['.jsx', '.js', '.json'],
  },
  module: {
    rules: [
      {
        test: /\.jsx?$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: [
              ['@babel/preset-react', { runtime: 'classic' }],
            ],
          },
        },
      },
    ],
  },
  plugins: [
    new ModuleFederationPlugin({
      name: 'shop_shell',
      remotes: {
        catalog: 'shop_catalog@http://localhost:3001/remoteEntry.js',
      },
      shared: {
        react: {
          singleton: true,
          requiredVersion: dependencies.react,
          strictVersion: true,
        },
        'react-dom': {
          singleton: true,
          requiredVersion: dependencies['react-dom'],
          strictVersion: true,
        },
        'react-dom/client': {
          singleton: true,
          packageName: 'react-dom',
          requiredVersion: dependencies['react-dom'],
          strictVersion: true,
        },
      },
    }),
    new HtmlWebpackPlugin({
      title: 'Shop shell',
    }),
  ],
  devServer: {
    host: 'localhost',
    static: false,
  },
};

import('./bootstrap').catch((error) => {
  console.error('Không khởi động được shell.', error);
  document.body.textContent = 'Shell không khởi động được. Kiểm tra Console.';
});

import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';

const container = document.createElement('div');
container.id = 'root';
document.body.appendChild(container);

createRoot(container).render(<App />);

import React, { Component, lazy, Suspense } from 'react';

const CatalogPage = lazy(() => import('catalog/CatalogPage'));

class CatalogBoundary extends Component {
  state = { failed: false };

  static getDerivedStateFromError() {
    return { failed: true };
  }

  componentDidCatch(error, info) {
    console.error('Catalog không tải hoặc render được.', error, info);
  }

  render() {
    if (this.state.failed) {
      return (
        <section role="alert">
          <h2>Catalog chưa khả dụng</h2>
          <p>Kiểm tra remote ở port 3001, rồi tải lại trang.</p>
          <button type="button" onClick={() => window.location.reload()}>
            Tải lại trang
          </button>
        </section>
      );
    }

    return this.props.children;
  }
}

export default function App() {
  return (
    <>
      <header>
        <h1>Shop shell</h1>
        <p>Header này thuộc host; danh sách sản phẩm thuộc remote.</p>
      </header>
      <main>
        <CatalogBoundary>
          <Suspense fallback={<p role="status">Đang tải catalog…</p>}>
            <CatalogPage />
          </Suspense>
        </CatalogBoundary>
      </main>
    </>
  );
}

Vì sao cần các cấu hình nàyCopy Anchor Link

Async boundary không phải eager loadingCopy Anchor Link

Có hai điểm async trong ví dụ, với hai mục đích khác nhau:

Nếu đưa import React và createRoot trở lại index.js, bạn có thể gặp Shared module is not available for eager consumption. Giữ entry nhỏ và bootstrap async là lựa chọn mặc định ở bài này.

Không bật eager: true cho mọi dependency để làm lỗi biến mất. eager có thể đưa provided/fallback modules vào initial chunk, thay đổi đường tải và tăng lượng code tải ban đầu. Nó cần một quyết định về bootstrap và hiệu năng, không phải nút sửa lỗi chung.

Shared React không phải shared stateCopy Anchor Link

Vì host render component của remote trong cùng React tree, các build phải thống nhất runtime React. singleton: true yêu cầu dùng một version cho shared key trong share scope tương ứng. requiredVersion lấy từ dependency của mỗi app; strictVersion: true giúp lab báo lỗi thay vì im lặng tiếp tục khi version được chọn không đáp ứng yêu cầu.

Lab ghi dependency bằng --save-exact, nên yêu cầu ở đây chặt: hai app phải dùng cùng version. Đó là cách dễ kiểm soát ở bước đầu, không phải chính sách nâng cấp mặc định cho mọi hệ thống production.

react-dom/client được khai báo riêng vì bootstrap import đúng subpath đó. packageName: 'react-dom' chỉ rõ package dùng để xác định version. Chia sẻ root key react-dom không tự chia sẻ toàn bộ subpath của React DOM.

Sharing thư viện không tạo cart store chung, không đồng bộ state và không cho phép catalog truy cập implementation của cart. Những ranh giới nghiệp vụ đó vẫn cần contract riêng.

Asset của remote phải tải từ remoteCopy Anchor Link

publicPath: 'auto' cho webpack suy ra base URL để tải chunk. Khi container catalog được tải từ http://localhost:3001/remoteEntry.js, runtime của catalog phải tải chunk của nó từ server catalog, không từ port 3000 của shell.

output.uniqueName khác nhau để hai runtime không dùng nhầm cơ chế đăng ký chunk của nhau. Giá trị này khác với name của container: cả hai cần riêng biệt giữa các build cùng chạy trên trang, nhưng giải quyết hai lớp naming khác nhau.

Bài dùng classic script remote, không phải ESM remote, manifest hay API request. Không cần mở CORS đại trà chỉ vì hai app khác port. Khi đổi kiểu tải hoặc thêm API, hãy xét CORS theo request thực tế; CSP cũng có thể chặn script remote nếu policy không cho phép origin của catalog.

Chạy và kiểm chứngCopy Anchor Link

Mở hai dev serverCopy Anchor Link

Dùng hai terminal, đều ở root shop-workspace. Khởi động lại server sau khi đổi webpack config:

npm run dev:catalog

npm run dev:shell

Chờ cả hai build thành công rồi mở catalog standalone trước, sau đó mở shell. Không cần chạy cart cho bài này.

• Trang http://localhost:3001 phải có Catalog standalone, ba sản phẩm và giá VND.
• Trang http://localhost:3000 phải có Shop shell, Catalog và cùng ba sản phẩm; không có heading Catalog standalone.
• Console không có lỗi tải module, shared version mismatch hoặc React Hooks.

Quan sát NetworkCopy Anchor Link

Mở DevTools ở trang shell, chọn Network, bật Disable cache khi DevTools đang mở, rồi reload. Kiểm tra:

1. Document và bundle khởi động của shell đến từ localhost:3000.
2. Có request http://localhost:3001/remoteEntry.js thành công.
3. Có các JavaScript chunk của catalog tải từ localhost:3001.
4. Trang shell vẫn ở origin localhost:3000, không có document navigation sang localhost:3001.

Tên chunk và số lượng request thay đổi theo mode và tối ưu của webpack; không đối chiếu bằng một filename hash cố định. Mở response của remoteEntry.js để chắc đó là JavaScript, không phải HTML fallback có status 200.

Trạng thái loading có thể thoáng qua quá nhanh trên local. Bạn có thể bật Network throttling để quan sát, nhưng không cần thêm delay giả vào component.

Muốn kiểm tra fallback, dừng server catalog rồi reload shell với cache tắt. Header shell phải còn, vùng catalog chuyển sang Catalog chưa khả dụng sau khi việc tải thất bại. Chạy lại catalog rồi bấm Tải lại trang để khôi phục. Dừng remote sau khi UI đã tải không làm component biến mất: code đã có trong runtime của trang.

Đổi catalog mà không rebuild shellCopy Anchor Link

Giữ shell server đang chạy. Trong apps/catalog/src/CatalogPage.jsx, đổi câu:

<p>Component này đến từ remote catalog.</p>

thành:

<p>Catalog đã được cập nhật từ remote.</p>

Chờ catalog compile lại, rồi reload trang shell với cache tắt. Bạn phải thấy câu mới mà không sửa code/config hay chủ động rebuild shell. Không kỳ vọng HMR của catalog tự cập nhật trang host; reload là phép kiểm tra rõ ràng cho bước đầu.

Thử nghiệm này minh họa việc thay implementation ở cùng URL và giữ public contract. Nó chưa kiểm chứng pipeline deploy, CDN cache hoặc khả năng tương thích với mọi consumer đang chạy. Những phần đó thuộc lab Deploy độc lập.

Build từng app độc lậpCopy Anchor Link

Từ root, chạy riêng hai app:

npm run build --workspace=@shop/catalog
npm run build --workspace=@shop/shell

Kết quả cần có:

Shell không cần server catalog đang chạy để compile config remote tĩnh này. Bạn có thể dừng catalog rồi chạy lại build shell để kiểm chứng: webpack ghi tham chiếu remote vào artifact, không tải source catalog qua HTTP để đóng vào bundle shell.

Root npm run build vẫn build cả ba app theo bài workspace; cart chưa có Federation cũng không sao. Dev server phục vụ output trong memory, còn lệnh build ghi vào dist trên disk.

Những lỗi thường gặpCopy Anchor Link

Đi từ lỗi compile đến request entry, request chunk, rồi mới tới runtime React. Thứ tự đó giúp bạn tránh sửa shared trong khi server remote chưa chạy.

Nếu entry trả HTML, đừng sửa CORS trước. Trước hết kiểm tra URL có trỏ nhầm server, file có thực sự được emit và dev server đã nhận config mới chưa. Các bước debug sâu hơn nằm ở Remote không tải và Duplicate React.

Checklist hoàn thànhCopy Anchor Link

• Shell và catalog vẫn là hai workspace package, hai build riêng.
• Catalog standalone render được mà không cần shell chạy.
• Shell dùng import('catalog/CatalogPage'), không import filesystem source của catalog.
• Module catalog expose default React component; DOM mount chỉ nằm trong bootstrap standalone.
• Network ở shell có entry và chunk catalog từ port 3001.
• Shared version khớp, Console không có lỗi runtime React.
• Dừng catalog rồi reload shell cho thấy fallback cục bộ, header vẫn còn.
• Đổi nội dung catalog, compile catalog rồi reload shell thấy bản mới mà không rebuild host.
• Build shell vẫn thành công khi catalog server đã dừng.
• dist của catalog có remoteEntry.js và các chunk đi kèm.

Bước tiếp theoCopy Anchor Link

Giữ ví dụ này làm baseline chạy được trước khi nối cart. Khi thêm routing hoặc contract giỏ hàng, bạn sẽ có một mốc để phân biệt lỗi tải module với lỗi giao tiếp nghiệp vụ.

Tài liệu tham khảoCopy Anchor Link

• webpack — Module Federation — cơ chế container, async boundary và các lỗi tích hợp thường gặp.
• webpack — ModuleFederationPlugin — cú pháp exposes, remotes, shared và các sharing hints.
• webpack — publicPath — cách xác định URL tải asset, gồm chế độ auto.
• React — lazy — yêu cầu default export, caching của lazy loader và lỗi tải module.
• React — Suspense — fallback trong lúc component chờ tài nguyên.