docs: add doc for rsbuild plugin

nyqykk · nyqykk · commit e171f9632495 · 2024-10-16T15:53:14.000+08:00
diff --git a/examples/module-federation/mf-react-component/rslib.config.ts b/examples/module-federation/mf-react-component/rslib.config.ts
@@ -36,12 +36,6 @@ export default defineConfig({
           root: './dist/mf',
         },
         assetPrefix: 'http://localhost:3001/mf',
-        minify: false,
-      },
-      source: {
-        define: {
-          'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
-        },
       },
       plugins: [
         pluginModuleFederation({
@@ -61,11 +55,5 @@ export default defineConfig({
       ],
     },
   ],
-  plugins: [
-    pluginReact({
-      splitChunks: {
-        react: false,
-      },
-    }),
-  ],
+  plugins: [pluginReact()],
 });
diff --git a/packages/core/src/config.ts b/packages/core/src/config.ts
@@ -285,9 +285,9 @@ export const composeAutoExternalConfig = (options: {
     : {};
 };
 
-export function composeMinifyConfig(
-  minify: NonNullable<RsbuildConfig['output']>['minify'],
-): RsbuildConfig {
+export function composeMinifyConfig(config: LibConfig): RsbuildConfig {
+  const minify = config.output?.minify;
+  const format = config.format;
   if (minify !== undefined) {
     // User's minify configuration will be merged afterwards.
     return {};
@@ -308,7 +308,8 @@ export function composeMinifyConfig(
               defaults: false,
               unused: true,
               dead_code: true,
-              toplevel: true,
+              // mf format if use toplevel, remoteEntry's global variable will be tree-shaking
+              toplevel: format !== 'mf',
             },
             format: {
               comments: 'all',
@@ -1033,7 +1034,7 @@ async function composeLibRsbuildConfig(config: LibConfig, configPath: string) {
     autoExternalConfig?.output?.externals,
     externalsConfig?.output?.externals,
   );
-  const minifyConfig = composeMinifyConfig(config.output?.minify);
+  const minifyConfig = composeMinifyConfig(config);
   const bannerFooterConfig = composeBannerFooterConfig(banner, footer);
   const decoratorsConfig = composeDecoratorsConfig(
     compilerOptions,
diff --git a/website/docs/zh/guide/_meta.json b/website/docs/zh/guide/_meta.json
@@ -8,5 +8,10 @@
     "type": "dir",
     "name": "basic",
     "label": "基础"
+  },
+  {
+    "type": "dir",
+    "name": "advanced",
+    "label": "进阶"
   }
 ]
diff --git a/website/docs/zh/guide/advanced/_meta.json b/website/docs/zh/guide/advanced/_meta.json
@@ -0,0 +1 @@
+["module-federation"]
diff --git a/website/docs/zh/guide/advanced/module-federation.mdx b/website/docs/zh/guide/advanced/module-federation.mdx
@@ -0,0 +1,144 @@
+# Module Federation
+
+本章节将介绍如何在 Rslib 中快速构建 Module Federation 产物
+
+## 名词解释
+
+Module Federation 是一种 JavaScript 应用分治的架构模式（类似于服务端的微服务），它允许你在多个 JavaScript 应用程序（或微前端）之间共享代码和资源。
+
+## 使用场景
+
+模块联邦有一些典型的使用场景，包括：
+
+允许独立应用（在微前端架构中称为"微前端"）之间共享模块，无需重新编译整个应用。
+不同的团队在不需要重新编译整个应用的情况下处理同一应用的不同部分。
+应用之间在运行时进行动态代码加载和共享。
+模块联邦可以帮助你：
+
+- 减少代码重复
+- 提高代码可维护性
+- 降低应用程序的整体大小
+- 提高应用程序的性能
+
+## 快速接入
+
+首先安装 Module Federation Rsbuild 插件(Rslib 基于 Rsbuild 构建)
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs
+  command={{
+    npm: 'npm add @module-federation/rsbuild-plugin --save-dev',
+    yarn: 'yarn add @module-federation/rsbuild-plugin --save-dev',
+    pnpm: 'pnpm add @module-federation/rsbuild-plugin --save-dev',
+    bun: 'bun add @module-federation/rsbuild-plugin --save-dev',
+  }}
+/>
+
+将插件添加到 `rslib.config.ts` 中
+
+```ts title='rslib.config.ts'
+import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';
+import { pluginReact } from '@rsbuild/plugin-react';
+import { defineConfig } from '@rslib/core';
+
+export default defineConfig({
+  lib: [
+    // ... other format
+    {
+      format: 'mf',
+      output: {
+        distPath: {
+          root: './dist/mf',
+        },
+        // add your assetPrefix here
+        // assetPrefix: 'http://localhost:3001/mf',
+      },
+      plugins: [
+        pluginModuleFederation({
+          name: 'rslib_provider',
+          exposes: {
+            // add expose here
+          },
+          // can not add 'remote' here, because you may build 'esm' or 'cjs' assets in one build.
+          // if you want the rslib package use remote module, please see below.
+          shared: {
+            react: {
+              singleton: true,
+            },
+            'react-dom': {
+              singleton: true,
+            },
+          },
+        }),
+      ],
+    },
+  ],
+  plugins: [pluginReact()],
+});
+```
+
+这样我们就完成了 Rslib Module 作为生产者的接入，构建完成后可以看到产物中新增了 mf 目录，消费者可以直接消费这个包
+
+在上面的例子中我们增加了一个新的 `format: 'mf'`，这会帮助你新增一份额外的 Module Federation 产物，与此同时还可以配置 `cjs` 和 `esm` 的 format，这并不冲突。
+
+但是如果希望这个 Rslib Module 同时可以消费其他生产者，请不要使用构建配置 `remote` 参数，因为在其他 format 中，这可能会导致错误，请参考下方使用 Module Federation 运行时的例子
+
+## 消费其他 Module Federation 模块
+
+因为 Rslib 中有多种 format，如果在构建时配置 `remote` 参数来消费其他模块可能无法在所有 format 中都能正常工作，推荐通过 [Module Federation Runtime](https://module-federation.io/guide/basic/runtime.html) 进行接入
+
+首先安装运行时依赖
+
+<PackageManagerTabs
+  command={{
+    npm: 'npm add @module-federation/enhanced --save',
+    yarn: 'yarn add @module-federation/enhanced --save',
+    pnpm: 'pnpm add @module-federation/enhanced --save',
+    bun: 'bun add @module-federation/enhanced --save',
+  }}
+/>
+
+然后在运行时消费其他 Module Federation 模块，例如
+
+```ts
+import { init, loadRemote } from '@module-federation/rsbuild-plugin/runtime';
+import { Suspense, createElement, lazy } from 'react';
+
+init({
+  name: 'rslib_provider',
+  remotes: [
+    {
+      name: 'mf_remote',
+      entry: 'http://localhost:3002/mf-manifest.json',
+    },
+  ],
+});
+
+export const Counter: React.FC = () => {
+  return (
+    <div>
+      <Suspense fallback={<div>loading</div>}>
+        {createElement(
+          lazy(
+            () =>
+              loadRemote('mf_remote') as Promise<{
+                default: React.FC;
+              }>,
+          ),
+        )}
+      </Suspense>
+    </div>
+  );
+};
+```
+
+这样可以保证在多种 format 中都能按预期进行加载模块
+
+## 参考例子
+
+[Rslib Module Federation Example](https://github.com/web-infra-dev/rslib/tree/main/examples/module-federation)
+
+- `mf-host`: Rsbuild App 消费者
+- `mf-react-component`: Rslib Module，同时是生产者和消费者，作为生产者提供模块给 `mf-host` 使用，作为消费者通过运行时消费 `mf-remote`
+- `mf-remote`: Rsbuild App 生产者
diff --git a/website/docs/zh/guide/start/index.mdx b/website/docs/zh/guide/start/index.mdx
@@ -52,4 +52,8 @@ import Step from '@components/Step';
     title="查阅配置"
     description="了解如何配置 Rslib"
   />
+  <Step
+    href="/guide/advanced/module-federation"
+    title="构建 Module Federation 产物"
+  />
 </NextSteps>

Original file line number	Diff line number	Diff line change
`@@ -8,5 +8,10 @@`
`8`	`8`	`"type": "dir",`
`9`	`9`	`"name": "basic",`
`10`	`10`	`"label": "基础"`
	`11`	`+ },`
	`12`	`+ {`
	`13`	`+ "type": "dir",`
	`14`	`+ "name": "advanced",`
	`15`	`+ "label": "进阶"`
`11`	`16`	`}`
`12`	`17`	`]`