@sbee/vite-federation 0.0.1

package/README.md

@@ -0,0 +1,168 @@
+# @sbee/vite-federation
+
+Plugin Module Federation cho **Vite 8** (rolldown), tương thích với [Webpack Module Federation](https://webpack.js.org/concepts/module-federation/).
+
+- **Zero runtime dependencies** — dùng `RolldownMagicString` và AST walker built-in của Vite/rolldown, không kéo theo `magic-string`, `oxc-parser`, hay `estree-walker`.
+- **Runtime API** — host có thể tải remote động khi chạy mà **không cần** khai báo trước trong `vite.config.ts`.
+- Hỗ trợ định dạng `esm`, `systemjs`, `var`; tương thích remote build bằng cả Vite lẫn Webpack.
+
+## Cài đặt
+
+```bash
+npm install @sbee/vite-federation --save-dev
+```
+
+`vite >= 7` là peer dependency (khuyến nghị Vite 8).
+
+## Sử dụng qua config
+
+Module Federation thường cần ít nhất 2 project: một `remote` (bên expose module) và một `host` (bên tiêu thụ module).
+
+### Bước 1: Cấu hình remote
+
+```js
+// vite.config.js — remote
+import federation from '@sbee/vite-federation'
+
+export default {
+  plugins: [
+    federation({
+      name: 'remote-app',
+      filename: 'remoteEntry.js',
+      // Các module được expose
+      exposes: {
+        './Button': './src/Button.vue'
+      },
+      shared: ['vue']
+    })
+  ],
+  build: {
+    // Module Federation yêu cầu target >= es2020
+    target: 'esnext'
+  }
+}
+```
+
+### Bước 2: Cấu hình host
+
+```js
+// vite.config.js — host
+import federation from '@sbee/vite-federation'
+
+export default {
+  plugins: [
+    federation({
+      name: 'host-app',
+      remotes: {
+        remote_app: 'http://localhost:5001/assets/remoteEntry.js'
+      },
+      shared: ['vue']
+    })
+  ],
+  build: {
+    target: 'esnext'
+  }
+}
+```
+
+### Bước 3: Dùng remote module trên host
+
+```js
+import { defineAsyncComponent } from 'vue'
+
+const RemoteButton = defineAsyncComponent(() => import('remote_app/Button'))
+```
+
+```vue
+<template>
+  <RemoteButton />
+</template>
+```
+
+## Runtime API — tải remote động không cần config
+
+Khi host **không biết trước** danh sách remote (ví dụ URL đến từ backend, plugin marketplace, cấu hình động), dùng entry `@sbee/vite-federation/runtime`. Không cần khai báo `remotes` trong `vite.config.ts`.
+
+```ts
+import { loadRemote } from '@sbee/vite-federation/runtime'
+
+// Tải thẳng từ URL, không cần đăng ký trước
+const Button = await loadRemote('https://remote.example.com/remoteEntry.js', './Button')
+```
+
+### Đăng ký trước rồi dùng theo tên
+
+```ts
+import { registerRemote, loadRemote } from '@sbee/vite-federation/runtime'
+
+registerRemote('design-system', {
+  url: 'https://cdn.example.com/remoteEntry.js',
+  format: 'esm',
+  from: 'vite'
+})
+
+const Modal = await loadRemote('design-system', './Modal')
+```
+
+### Preload & tải nhiều module cùng lúc
+
+```ts
+import { preloadRemote, loadRemoteModules } from '@sbee/vite-federation/runtime'
+
+// Init sẵn remote, trả về handle để gọi .get() nhiều lần
+const remote = await preloadRemote('design-system')
+const Button = await remote.get('./Button')
+
+// Tải nhiều module một lần
+const { Header, Footer } = await loadRemoteModules(
+  'https://remote.example.com/remoteEntry.js',
+  { Header: './Header', Footer: './Footer' }
+)
+```
+
+Gọi `loadRemote` / `preloadRemote` đồng thời với cùng một remote chỉ tải và init **đúng một lần** (promise được dedup), tránh trùng `<script>` hoặc double init.
+
+### API reference
+
+| Hàm | Mô tả |
+| --- | --- |
+| `loadRemote<T>(urlOrName, moduleName, config?)` | Tải một module từ remote. `urlOrName` là URL trực tiếp hoặc tên đã đăng ký. |
+| `loadRemoteModules(urlOrName, { key: moduleName }, config?)` | Tải nhiều module cùng lúc, trả về object theo key. |
+| `registerRemote(name, config)` | Đăng ký remote để dùng lại theo tên. Đồng bộ, chỉ lưu config. |
+| `preloadRemote(name, config?)` | Tải & init remote, trả về `RemoteHandle` có `.get()`, `.init()`, `.inited`. |
+| `provideShared(scope, packages)` | Đăng ký shared packages vào global share scope (dùng bởi host). |
+| `getShareScope(scope?)` | Lấy global share scope hiện tại. |
+
+`RemoteConfig`:
+
+```ts
+interface RemoteConfig {
+  url: string | (() => Promise<string>)
+  format?: 'esm' | 'var'        // mặc định 'esm'
+  from?: 'vite' | 'webpack'     // mặc định 'vite'
+  shareScope?: string           // mặc định 'default'
+}
+```
+
+## Tùy chọn plugin
+
+| Option | Kiểu | Mô tả |
+| --- | --- | --- |
+| `name` | `string` | Tên container. |
+| `filename` | `string` | Tên file remote entry, mặc định `remoteEntry.js`. |
+| `exposes` | `object` | Các module remote expose ra ngoài. |
+| `remotes` | `object` | Các remote mà host tiêu thụ. |
+| `shared` | `string[] \| object` | Các dependency dùng chung giữa host và remote. |
+| `shareScope` | `string` | Tên share scope, mặc định `default`. |
+
+## Build
+
+```bash
+npm run build
+```
+
+Sinh ra bundle `esm` + `cjs` trong `dist/` kèm khai báo type cho entry `runtime`. Chạy test:
+
+```bash
+npx vitest run
+```