diff --git a/apps/website-new/docs/en/guide/start/quick-start.mdx b/apps/website-new/docs/en/guide/start/quick-start.mdx index 0721955470e..00ae54f83c3 100644 --- a/apps/website-new/docs/en/guide/start/quick-start.mdx +++ b/apps/website-new/docs/en/guide/start/quick-start.mdx @@ -1,4 +1,4 @@ -import { Badge } from "@theme"; +import { Badge, PackageManagerTabs } from "@theme"; # Quick Start Guide @@ -6,14 +6,169 @@ Before reading this guide, please first read the [Setting Up Environment](./sett _ You can also use [Nx](https://nx.dev) to rapidly scaffold Module Federation projects for [React](../../practice/frameworks/react/using-nx-for-react) and [Angular](../../practice/frameworks/angular/using-nx-for-angular)._ -## Creating a Producer +## Creating a New Project -### 1. Initializing the Project +Module Federation provides the `create-module-federation` tool to create projects. You don't need to install it globally; you can directly use `npx` to run it on-demand. -Use [Rsbuild](https://rsbuild.dev/) to create a producer and call the following command: +You can use `create-module-federation` to create a Module Federation project by running the following command: + + +Just follow the prompts step by step. During the creation process, you can select the project type, role type, etc. + +### Templates + +When creating a project, you can choose from the following templates provided by `create-module-federation`: + +| Template | Description | +| --------------------- | ------------------------------------------------------------ | +| provider-modern | A provider using [Modern.js](https://modernjs.dev/) | +| provider-rsbuild | A provider using [Rsbuild](https://rsbuild.dev/) | +| rslib | A provider using [Rslib](https://lib.rsbuild.dev/) | +| rslib-storybook | A provider using [Rslib](https://lib.rsbuild.dev/) with the storybook feature enabled | +| consumer-modern | A consumer using [Modern.js](https://modernjs.dev/) | +| consumer-rsbuild | A consumer using [Rsbuild](https://rsbuild.dev/) | + +### Quick Creation + +[create-module-federation](https://www.npmjs.com/package/create-module-federation) provides some CLI options. By setting these CLI options, you can skip the interactive selection steps and create a project with one click. + +For example, to create a Modern.js provider project named `provider` in the `my-project` directory with one click: + +```bash +npx create-module-federation --dir my-project --template provider-modern --name provider + +# Use abbreviations +npx create-module-federation -d my-project -t provider-modern -n provider +``` + +The complete CLI options for `create-module-federation` are as follows: + +```text +Usage: create-module-federation [options] + +Options: + + -h, --help display help for command + -d, --dir create project in specified directory + -t, --template specify the template to use + -n, --name specify the mf name + -r, --role specify the mf role type: provider or consumer + --override override files in target directory + +Templates: + + provider-modern, provider-rsbuild, rslib, rslib-storybook, consumer-modern, consumer-rsbuild +``` + +### Create a provider + +Execute the `create-module-federation` command, select the required framework and type according to your needs, and select the role type as provider to create a project. + +Here we take creating an rsbuild provider project as an example: + +```bash +➜ ~ ✗ npm create module-federation@latest + +> npx +> create-module-federation + +◆ Create Module Federation Project +│ +◇ Please input Module Federation name: +│ mf_provider +│ +◇ Please select the type of project you want to create: +│ Application +│ +◇ Select template +│ Rsbuild +│ +◇ Please select the role of project you want to create: +│ Provider +│ +◇ Next steps ─────╮ +│ │ +│ cd mf_provider │ +│ npm install │ +│ npm run dev │ +│ │ +├──────────────────╯ +│ +└ Done. +``` + +### Create a consumer + +Execute the `create-module-federation` command, select the required framework and type according to your needs, and select the role type as consumer to create a project. + +Here is an example of creating an rsbuild consumer project: + +```bash +➜ ~ ✗ npm create module-federation@latest + +> npx +> create-module-federation + +◆ Create Module Federation Project +│ +◇ Please input Module Federation name: +│ mf_consumer +│ +◇ Please select the type of project you want to create: +│ Application +│ +◇ Select template +│ Rsbuild +│ +◇ Please select the role of project you want to create: +│ Consumer +│ +◇ Next steps ─────╮ +│ │ +│ cd mf_provider │ +│ npm install │ +│ npm run dev │ +│ │ +├──────────────────╯ +│ +└ Done. +``` + +#### Replace provider + +The default consumer project created will consume a published provider. If you want to replace the provider, you need to modify the `remotes` configuration in `module-federation.config.js`. + +```diff title="module-federation.config.ts" +import { createModuleFederationConfig } from '@module-federation/rsbuild-plugin'; + +export default createModuleFederationConfig({ + name: 'mf_consumer', + remotes: { +- 'provider': 'rslib_provider@https://unpkg.com/module-federation-rslib-provider@latest/dist/mf/mf-manifest.json', ++ 'provider': 'rslib_provider@http://localhost:3000/mf-manifest.json', + }, + shared: { + react: { singleton: true }, + 'react-dom': { singleton: true }, + }, +}); + +``` + +## Create from existing project + +### Creating a Producer + +#### 1. Initializing the Project -import { PackageManagerTabs } from '@theme'; +Use [Rsbuild](https://rsbuild.dev/) to create a provider and call the following command: TypeScript ``` -### 2. Installing Module Federation Build Plugin +#### 2. Installing Module Federation Build Plugin Following the steps above for initializing the project, we created a `React` project named `federation_provider`. Execute the following commands in sequence: @@ -62,7 +217,7 @@ bun add @module-federation/rsbuild-plugin --save-dev }} /> -### 3. Exporting Modules by the Producer +#### 3. Exporting Modules by the Producer > Change the entry file to asynchronous @@ -118,7 +273,7 @@ export default defineConfig({ }); ``` -### 4. Starting the Producer +#### 4. Starting the Producer TypeScript ``` -### 2. Installing Module Federation Build Plugin +#### 2. Installing Module Federation Build Plugin Following the steps above for initializing the project, we created a `React` project named `federation_consumer`. Execute the following commands in sequence: @@ -201,7 +356,7 @@ bun add @module-federation/rsbuild-plugin --save-dev /> -### 3. Consuming the Producer +#### 3. Consuming the Producer > Declare the `Module Federation` type path in `tsconfig.json` @@ -285,7 +440,7 @@ export default App; ## Summary -Through the above process, you have completed the export of a component from a 'producer' for use by a 'consumer' based on Module Federation. Along the way, you have preliminarily used and understood the configurations of remotes, exposes, and shared in the Module Federation plugin. +Through the above process, you have completed the export of a component from a 'provider' for use by a 'consumer' based on Module Federation. Along the way, you have preliminarily used and understood the configurations of remotes, exposes, and shared in the Module Federation plugin. If you wish to learn how to directly export and consume remote modules on Webpack and Rspack build tools, you can refer to: [Rspack Plugin](../basic/rspack), [Webpack Plugin](../basic/webpack) diff --git a/apps/website-new/docs/zh/guide/start/quick-start.mdx b/apps/website-new/docs/zh/guide/start/quick-start.mdx index a56370b78fb..e3c184176b4 100644 --- a/apps/website-new/docs/zh/guide/start/quick-start.mdx +++ b/apps/website-new/docs/zh/guide/start/quick-start.mdx @@ -2,14 +2,173 @@ 在阅读本指南前，请先阅读 [设置环境](./setting-up-env)。本指南将引导你逐步学习使用 Module Federation。我们将构建两个独立的单页面应用程序 (SPA)，它们会使用 Module Federation 共享组件，下文中遇到不熟的名词请查看[名词解释](./glossary)。 -## 创建一个生产者 +## 新项目创建 -### 1. 初始化项目 +Module Federation 提供了 `create-module-federation` 工具来创建项目，不需要全局安装，直接使用 npx 按需运行即可。 -使用 [Rsbuild](https://rsbuild.dev/) 来创建一个生产者，调用以下命令： +你可以使用 `create-module-federation` 来创建一个 Module Federation 项目，调用以下命令： import { PackageManagerTabs } from '@theme'; + + +按照提示一步步操作即可。在创建过程中，你可以选择项目类型、角色类型等。 + +### 模板 + +在创建项目时，你可以选择 `create-module-federation` 提供的下列模板： + +| 模板 | 描述 | +| ------------------------- | ------------------------------------------------------------ | +| provider-modern | 使用 [Modern.js](https://modernjs.dev/) 的生产者 | +| provider-rsbuild | 使用 [Rsbuild](https://rsbuild.dev/) 的生产者 | +| rslib | 使用 [Rslib](https://lib.rsbuild.dev/) 的生产者 | +| rslib-storybook | 使用 [Rslib](https://lib.rsbuild.dev/) 的生产者，并且开启了 storybook 功能 | +| consumer-modern | 使用 [Modern.js](https://modernjs.dev/) 的消费者 | +| consumer-rsbuild | 使用 [Rsbuild](https://rsbuild.dev/) 的消费者 | + + +### 快速创建 + +[create-module-federation](https://www.npmjs.com/package/create-module-federation) 提供了一些 CLI 选项。通过设置这些 CLI 选项，你可以跳过交互式的选择步骤，一键创建项目。 + +比如，一键创建名称为 provider 的 Modern.js 生产者项目到 `my-project` 目录： + +```bash +npx create-module-federation --dir my-project --template provider-modern --name provider + +# 使用缩写 +npx create-module-federation -d my-project -t provider-modern -n provider +``` + +`create-module-federation` 完整的 CLI 选项如下： + +```text +Usage: create-module-federation [options] + +Options: + + -h, --help display help for command + -d, --dir create project in specified directory + -t, --template specify the template to use + -n, --name specify the mf name + -r, --role specify the mf role type: provider or consumer + --override override files in target directory + +Templates: + + provider-modern, provider-rsbuild, rslib, rslib-storybook, consumer-modern, consumer-rsbuild +``` + +### 创建一个生产者 + +执行 `create-module-federation` 命令，按照需求选择需要的框架和类型，并选择角色类型为生产者即可创建项目。 + +此处以创建一个 rsbuild 生产者项目为例： + +```bash +➜ ~ ✗ npm create module-federation@latest + +> npx +> create-module-federation + +◆ Create Module Federation Project +│ +◇ Please input Module Federation name: +│ mf_provider +│ +◇ Please select the type of project you want to create: +│ Application +│ +◇ Select template +│ Rsbuild +│ +◇ Please select the role of project you want to create: +│ Provider +│ +◇ Next steps ─────╮ +│ │ +│ cd mf_provider │ +│ npm install │ +│ npm run dev │ +│ │ +├──────────────────╯ +│ +└ Done. +``` + +### 创建一个消费者 + +执行 `create-module-federation` 命令，按照需求选择需要的框架和类型，并选择角色类型为消费者即可创建项目。 + +此处以创建一个 rsbuild 消费者项目为例： + +```bash +➜ ~ ✗ npm create module-federation@latest + +> npx +> create-module-federation + +◆ Create Module Federation Project +│ +◇ Please input Module Federation name: +│ mf_consumer +│ +◇ Please select the type of project you want to create: +│ Application +│ +◇ Select template +│ Rsbuild +│ +◇ Please select the role of project you want to create: +│ Consumer +│ +◇ Next steps ─────╮ +│ │ +│ cd mf_provider │ +│ npm install │ +│ npm run dev │ +│ │ +├──────────────────╯ +│ +└ Done. +``` + +#### 替换生产者 + +默认创建的消费者项目会消费一个已发布的生产者，如果你想替换生产者，需要在 `module-federation.config.js` 中修改 `remotes` 配置。 + +```diff title="module-federation.config.ts" +import { createModuleFederationConfig } from '@module-federation/rsbuild-plugin'; + +export default createModuleFederationConfig({ + name: 'mf_consumer', + remotes: { +- 'provider': 'rslib_provider@https://unpkg.com/module-federation-rslib-provider@latest/dist/mf/mf-manifest.json', ++ 'provider': 'rslib_provider@http://localhost:3000/mf-manifest.json', + }, + shared: { + react: { singleton: true }, + 'react-dom': { singleton: true }, + }, +}); + +``` + +## 已有项目创建 + +### 创建一个生产者 + +#### 1. 初始化项目 + +使用 [Rsbuild](https://rsbuild.dev/) 来创建一个生产者，调用以下命令： + TypeScript ``` -### 2. 安装 Module Federation 构建插件 +#### 2. 安装 Module Federation 构建插件 根据上面初始化项目的步骤，我们创建了名为 `federation_provider` 的 `React` 项目，依次执行以下命令 @@ -56,7 +215,7 @@ bun add @module-federation/rsbuild-plugin --save-dev }} /> -### 3. 生产者导出模块 +#### 3. 生产者导出模块 > 将入口改为异步 @@ -111,7 +270,7 @@ export default defineConfig({ }); ``` -### 4. 启动生产者 +#### 4. 启动生产者 TypeScript ``` -### 2. 安装 Module Federation 构建插件 +#### 2. 安装 Module Federation 构建插件 根据上面初始化项目的步骤，我们创建了名为 `federation_consumer` 的 `React` 项目，依次执行以下命令 @@ -192,7 +351,7 @@ bun add @module-federation/rsbuild-plugin --save-dev }} /> -### 3. 消费生产者 +#### 3. 消费生产者 > 增加 Module Federation 插件消费远程模块 diff --git a/packages/create-module-federation/README.md b/packages/create-module-federation/README.md index b1d45d330a2..9e8eab0b2e8 100644 --- a/packages/create-module-federation/README.md +++ b/packages/create-module-federation/README.md @@ -1 +1,40 @@ -# `create-module-federation` +

+ Module Federation 2.0 +

+ +# create-module-federation + +Create a new Module Federation project. + +

+ + npm version + + license + downloads +

+ +## Usage + +Using `npm create`: + +```bash +npm create module-federation@latest +``` + +Using CLI flags: + +```bash +npx create-module-federation --dir my-project --template provider-modern --name provider + +# Using abbreviations +npx create-module-federation -d my-project -t provider-modern -n provider +``` + +## Documentation + +See [Documentation](https://module-federation.io/guide/start/quick-start). + +## License + +[MIT](https://github.com/module-federation/core/blob/main/LICENSE). diff --git a/packages/create-module-federation/src/index.ts b/packages/create-module-federation/src/index.ts index 687ece0690b..c7a5ae33f43 100644 --- a/packages/create-module-federation/src/index.ts +++ b/packages/create-module-federation/src/index.ts @@ -8,11 +8,11 @@ interface Template { export const TEMPLATES = [ 'provider-modern', - 'consumer-modern', 'provider-rsbuild', - 'consumer-rsbuild', 'rslib', 'rslib-storybook', + 'consumer-modern', + 'consumer-rsbuild', // other 'create-zephyr', diff --git a/packages/create-module-federation/templates/modern-common/modern.config.ts b/packages/create-module-federation/templates/consumer-modern-ts/modern.config.ts similarity index 100% rename from packages/create-module-federation/templates/modern-common/modern.config.ts rename to packages/create-module-federation/templates/consumer-modern-ts/modern.config.ts diff --git a/packages/create-module-federation/templates/rsbuild-common/rsbuild.config.ts b/packages/create-module-federation/templates/consumer-rsbuild-ts/rsbuild.config.ts similarity index 100% rename from packages/create-module-federation/templates/rsbuild-common/rsbuild.config.ts rename to packages/create-module-federation/templates/consumer-rsbuild-ts/rsbuild.config.ts diff --git a/packages/create-module-federation/templates/provider-modern-ts/modern.config.ts b/packages/create-module-federation/templates/provider-modern-ts/modern.config.ts new file mode 100644 index 00000000000..616290711f3 --- /dev/null +++ b/packages/create-module-federation/templates/provider-modern-ts/modern.config.ts @@ -0,0 +1,18 @@ +import { appTools, defineConfig } from '@modern-js/app-tools'; +import { moduleFederationPlugin } from '@module-federation/modern-js'; + +// https://modernjs.dev/en/configure/app/usage +export default defineConfig({ + runtime: { + router: true, + }, + plugins: [ + appTools({ + bundler: 'rspack', // Set to 'webpack' to enable webpack + }), + moduleFederationPlugin(), + ], + server: { + port: 3001, + }, +}); diff --git a/packages/create-module-federation/templates/provider-rsbuild-ts/rsbuild.config.ts b/packages/create-module-federation/templates/provider-rsbuild-ts/rsbuild.config.ts new file mode 100644 index 00000000000..aec11f21d02 --- /dev/null +++ b/packages/create-module-federation/templates/provider-rsbuild-ts/rsbuild.config.ts @@ -0,0 +1,11 @@ +import { defineConfig } from '@rsbuild/core'; +import { pluginReact } from '@rsbuild/plugin-react'; +import { pluginModuleFederation } from '@module-federation/rsbuild-plugin'; +import moduleFederationConfig from './module-federation.config'; + +export default defineConfig({ + plugins: [pluginReact(), pluginModuleFederation(moduleFederationConfig)], + server: { + port: 3001, + }, +});