Cấu trúc workspace

Khi shell, catalog và cart cùng nằm trong một repo, rất dễ import thẳng source của nhau để làm cho ứng dụng chạy trước. Cách đó tiện trong vài phút đầu, nhưng khiến bạn khó biết mình đang tích hợp ba frontend hay chỉ chia một ứng dụng thành ba thư mục.

Bài này thiết lập workspace cho shop mẫu: mỗi app có tên package, lệnh chạy và artifact riêng; phần dùng chung có ranh giới rõ ràng. Mình chọn npm workspaces và webpack 5 cho ví dụ, để bước tiếp theo có thể thêm React và Module Federation mà không đổi bundler.

Mục lụcCopy Anchor Link

• Workspace giải quyết việc gì
• Cấu trúc thư mục và quyền sở hữu
  • Apps là các đơn vị chạy và build
  • Packages chỉ chứa phần dùng chung có chủ đích
  • Scripts ở root chỉ điều phối
• Tên package và port local
• Tạo workspace tối thiểu
  • Tạo thư mục và cấu hình root
  • Khai báo ba app
  • Cài tooling vào đúng workspace
  • Tạo entry và cấu hình build cho từng app
• Chạy và kiểm tra cấu trúc
  • Chạy ba dev server
  • Kiểm tra artifact riêng
  • Lockfile và cài đặt lại
• Khi nào thêm shared package
• Những lỗi thường gặp
• Checklist trước khi thêm Federation
• Bước tiếp theo
• Tài liệu tham khảo

Workspace giải quyết việc gìCopy Anchor Link

Nếu đặt ba project độc lập cạnh nhau, bạn sẽ phải vào từng thư mục để cài dependency và chạy lệnh. Workspace giúp package manager nhận diện các package local, quản lý dependency graph bằng một lockfile ở root và chọn app cần chạy bằng tên package.

Nhưng workspace chỉ là cách tổ chức source và tooling. Nó không quyết định browser tải catalog lúc nào, không tạo remoteEntry.js và không đảm bảo các frontend deploy độc lập.

direction: right
npm: npm workspaces
webpack: "webpack của mỗi app"
federation: Module Federation
npm -> packages: "Quản lý"
packages: "Package local và lệnh phát triển"
webpack -> artifacts: "Tạo"
artifacts: "Artifact cho app"
federation -> runtime: "Tích hợp"
runtime: "Module giữa các build ở runtime"

Ví dụ, shell dùng import { CatalogPage } from '@shop/catalog' rồi bundler đóng code catalog vào artifact của shell thì đó vẫn là build-time composition. Việc catalog có một package.json riêng không biến import ấy thành remote loading.

Mình dùng monorepo ở bài thực hành vì bạn có thể nhìn toàn bộ ví dụ và sửa contract trong một chỗ. Khi các team đã có repository và pipeline riêng, không cần gom về một repo chỉ để dùng micro-frontend. Phần lựa chọn repository được tách ở Monorepo và multi-repo.

Cấu trúc thư mục và quyền sở hữuCopy Anchor Link

Đây là cấu trúc đạt được sau các bước bên dưới. Thư mục packages ban đầu để trống; node_modules và dist không được commit.

Apps là các đơn vị chạy và buildCopy Anchor Link

Mỗi app có src, cấu hình bundler và thư mục output riêng. Ở bài này, cả ba đều chạy standalone để bạn kiểm tra được app nào hỏng mà không phải mở shell trước.

Đừng để apps/shell/src import từ ../../catalog/src/.... Đường dẫn đó bỏ qua public boundary và buộc shell biết cấu trúc nội bộ của catalog. Khi thêm Federation, shell sẽ consume module qua public request được khai báo, không qua đường dẫn filesystem của remote.

Packages chỉ chứa phần dùng chung có chủ đíchCopy Anchor Link

packages dành cho code được consume như dependency khi phát triển hoặc build, không phải chỗ chuyển mọi đoạn code lặp lại vào đó. Có thể thêm các package sau khi thật sự có nhu cầu:

Các package này chưa được tạo trong bài. Giữ packages trống cũng được: không cần một shared package chỉ để cây thư mục trông đầy đủ.

Một dependency nằm trong workspace không đồng nghĩa với dependency nằm trong shared của Module Federation. Workspace linking xảy ra ở máy phát triển/build; Federation sharing là cơ chế runtime riêng. Với React, còn phải kiểm tra cách bundler resolve và đóng gói dependency, không chỉ nhìn xem root có mấy thư mục node_modules.

Scripts ở root chỉ điều phốiCopy Anchor Link

Root nên trả lời những câu hỏi như “chạy catalog bằng lệnh nào?” hoặc “build cả ba app ra sao?”. Cấu hình entry, output và plugin vẫn nằm trong từng app, vì đó là phần quyết định artifact của app ấy.

Mình chưa thêm Nx, Turborepo hay shared webpack config ở bước này. Ba app nhỏ chưa cần task cache hoặc task graph phức tạp; cấu hình ngắn, tách riêng giúp bạn nhìn rõ boundary. Khi có package phải build trước consumer hoặc CI bắt đầu tốn thời gian, mới bổ sung cơ chế điều phối phù hợp.

Tên package và port localCopy Anchor Link

Dùng một bảng port cố định ngay từ đầu để shell không tải nhầm remote. Các số dưới đây là quy ước của lab, không phải yêu cầu của webpack hoặc Federation.

Tên package dùng để chọn workspace trong lệnh npm. Tên container Federation, alias mà host dùng và public module key là các tên khác; chúng sẽ được khai báo ở bước tích hợp. Đừng suy ra URL remote từ tên package.

Hai port khác nhau là hai origin khác nhau. Giữ cùng hostname localhost trong cả lệnh chạy lẫn URL cấu hình; đừng trộn tùy tiện với 127.0.0.1. Bài này chưa có request cross-origin giữa các app, nên chưa cần mở CORS. Khi dùng ESM remote, API hoặc manifest, hãy cấu hình CORS theo loại request thực tế, không mặc định thêm Access-Control-Allow-Origin: * cho mọi thứ.

Tạo workspace tối thiểuCopy Anchor Link

Bạn cần Node.js 22 trở lên và npm đi kèm Node. Các lệnh tạo thư mục dùng shell kiểu Bash/Zsh; trên PowerShell, tạo cây thư mục tương đương rồi dùng cùng các lệnh npm.

mkdir shop-workspace
cd shop-workspace
mkdir -p apps/shell/src apps/catalog/src apps/cart/src packages

{
  "name": "shop-workspace",
  "version": "0.1.0",
  "private": true,
  "engines": {
    "node": ">=22"
  },
  "workspaces": [
    "apps/*",
    "packages/*"
  ],
  "scripts": {
    "dev:shell": "npm run dev --workspace=@shop/shell",
    "dev:catalog": "npm run dev --workspace=@shop/catalog",
    "dev:cart": "npm run dev --workspace=@shop/cart",
    "build": "npm run build --workspace=@shop/shell --workspace=@shop/catalog --workspace=@shop/cart"
  }
}

22

node_modules/
dist/
coverage/
*.log

{
  "name": "@shop/shell",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "webpack serve --config webpack.config.cjs --mode development --port 3000",
    "build": "webpack --config webpack.config.cjs --mode production"
  }
}

{
  "name": "@shop/catalog",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "webpack serve --config webpack.config.cjs --mode development --port 3001",
    "build": "webpack --config webpack.config.cjs --mode production"
  }
}

{
  "name": "@shop/cart",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "webpack serve --config webpack.config.cjs --mode development --port 3002",
    "build": "webpack --config webpack.config.cjs --mode production"
  }
}

npm install --save-dev --save-exact webpack@5 webpack-cli@6 webpack-dev-server@5 html-webpack-plugin@5 --workspace=@shop/shell --workspace=@shop/catalog --workspace=@shop/cart

const heading = document.createElement('h1');
heading.textContent = 'Shop shell';

const status = document.createElement('p');
status.textContent = 'Shell đang chạy standalone. Chưa kết nối remote.';

document.body.append(heading, status);

const heading = document.createElement('h1');
heading.textContent = 'Shop catalog';

const status = document.createElement('p');
status.textContent = 'Catalog đang chạy standalone. Chưa expose module.';

document.body.append(heading, status);

const heading = document.createElement('h1');
heading.textContent = 'Shop cart';

const status = document.createElement('p');
status.textContent = 'Cart đang chạy standalone. Chưa expose module.';

document.body.append(heading, status);

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

module.exports = {
  context: __dirname,
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash].js',
    publicPath: 'auto',
    uniqueName: name.replace(/[^a-zA-Z0-9_]/g, '_'),
    clean: true,
  },
  plugins: [
    new HtmlWebpackPlugin({
      title: name,
    }),
  ],
  devServer: {
    host: 'localhost',
    static: false,
  },
};

Chạy và kiểm tra cấu trúcCopy Anchor Link

Chạy ba dev serverCopy Anchor Link

Mở ba terminal, mỗi terminal đều ở root shop-workspace:

npm run dev:shell

npm run dev:catalog

npm run dev:cart

Mở các URL trong bảng port. Kết quả đúng là:

Sửa heading của catalog rồi kiểm tra lại trang catalog. Shell không cần import source catalog để thay đổi ấy xuất hiện trên trang standalone của catalog.

Kiểm tra artifact riêngCopy Anchor Link

Từ root, chạy:

npm run build

Mỗi app phải có dist/index.html và JavaScript do webpack sinh. Tên JavaScript chứa hash nên không nên kiểm tra bằng một tên file cố định. Dev server thường phục vụ output trong memory; việc trang dev mở được không chứng minh thư mục dist đã có trên disk.

Để kiểm tra riêng một app:

npm run build --workspace=@shop/catalog

Lệnh này chỉ chọn script build của catalog, không build shell hay cart. Với cấu hình hiện tại, catalog cũng không cần artifact của hai app còn lại để build.

Root build liệt kê rõ ba app cần build. Nếu sau này thêm package cần compile trước app, phải bổ sung thứ tự hoặc task graph; npm không tự suy ra topological build order từ dependencies. Đừng thêm --if-present để che việc một app quên khai báo script bắt buộc.

dist riêng là điều kiện thuận tiện để deploy riêng, không phải bằng chứng đã có independent deployment. Còn phải kiểm tra public contract, URL artifact và tính tương thích với consumer đã phát hành.

Lockfile và cài đặt lạiCopy Anchor Link

Commit package.json ở root, manifest của từng app, cấu hình, source và một package-lock.json ở root. Không chạy một vòng npm install riêng trong từng app và duy trì nhiều lockfile cho cùng workspace.

Trên checkout mới, chạy từ root:

npm ci
npm run build

npm ci cần lockfile có sẵn và khớp manifest. Nếu bạn chủ động thêm hoặc nâng dependency, dùng npm install với workspace đích, kiểm tra diff manifest/lockfile rồi commit; không xóa lockfile như bước sửa lỗi mặc định.

Các version cụ thể được lưu trong lockfile của lần cài đặt. Nếu bài thực hành cần tái lập ở nhiều máy, dùng chung lockfile đã kiểm tra thay vì mỗi máy resolve lại các major trong lệnh cài tooling.

Khi nào thêm shared packageCopy Anchor Link

Giả sử catalog phát sự kiện yêu cầu thêm một SKU vào giỏ, còn cart cần hiểu payload ấy. Bạn có lý do để thêm packages/contracts với tên @shop/contracts: public type hoặc schema của sự kiện là phần hai bên phải thống nhất, còn store và cách tính tổng vẫn do cart sở hữu.

Khi đã tạo manifest và public entry hợp lệ cho package đó, có thể khai báo dependency cho consumer từ root:

npm install @shop/contracts --workspace=@shop/catalog --workspace=@shop/cart

Lệnh trên dành cho workspace đã có package local @shop/contracts, không phải bước phải chạy của bài hiện tại. npm có thể link workspace local phù hợp thay vì tải từ registry. Kiểm tra manifest, lockfile và public exports để chắc consumer dùng đúng package.

Trong ví dụ npm này, không dùng workspace:* theo thói quen từ pnpm/Yarn: đó không phải dependency protocol được npm workspaces hỗ trợ theo cách ấy. Nếu chuyển package manager, chuyển cả quy ước manifest, lockfile và lệnh CI một cách có chủ đích.

Với TypeScript, một package chỉ chứa types có thể được consume bằng import type, không tạo dependency JavaScript runtime từ import đó. Nếu package export schema dùng để validate dữ liệu, schema là code runtime và phải có entry JavaScript phù hợp. Type không tự validate payload nhận từ remote.

Mình chỉ tách shared package khi có public API nhỏ và owner chịu trách nhiệm về thay đổi. Nếu package bắt đầu re-export mọi store và component của cả catalog lẫn cart, hãy thu hẹp nó thay vì xem đó là lợi ích của monorepo. Đọc thêm Contracts giữa các frontend trước khi chốt payload và versioning.

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

Đừng sửa lỗi port bằng cách cho server chọn port ngẫu nhiên rồi quên URL mà host đang dùng. Với một lab Federation, địa chỉ remote ổn định giúp bạn phân biệt lỗi cấu hình URL với lỗi build hoặc contract.

Checklist trước khi thêm FederationCopy Anchor Link

• Project thực hành nằm riêng với site Next.js + Fumadocs.
• npm nhận diện được @shop/shell, @shop/catalog và @shop/cart.
• Mỗi app khai báo tooling của mình, không chỉ dùng dependency hoist tình cờ.
• Ba trang standalone mở được ở port đã quy ước.
• Build cả workspace tạo ba artifact riêng; build catalog riêng cũng thành công.
• Shell không import source nội bộ của catalog hoặc cart.
• Chỉ có một lockfile workspace, được commit cùng manifests.
• Chưa xem standalone page là remote: remoteEntry.js chưa tồn tại trong cấu hình này.

Bước tiếp theoCopy Anchor Link

Giữ workspace này cho bước thêm React và Federation: bắt đầu với shell và catalog, kiểm tra một public module trước, rồi mới đưa cart vào luồng tích hợp. Không cần tạo mọi shared package hoặc một pipeline production để chứng minh host tải được remote đầu tiên.

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

• npm workspaces — chọn workspace, thêm dependency và thứ tự chạy script.
• npm ci — cài đặt theo lockfile trong checkout sạch hoặc CI.
• webpack dev server — host, port, static content và dev middleware.
• webpack output — path, publicPath, uniqueName và clean.