> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# Modern.js

该 addon 会从你的 Modern.js 配置文件中加载一份可复用的 Rsbuild config，使 `storybook-builder-rsbuild` 复用你的应用已经信赖的同一套配置。

## 快速开始

查看 [Modern.js React 示例](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/modernjs-react)，了解该集成在真实项目中的用法。

### 安装


```sh [npm]
npm install @rsbuild/core storybook-react-rsbuild storybook-addon-modernjs -D
```

```sh [yarn]
yarn add @rsbuild/core storybook-react-rsbuild storybook-addon-modernjs -D
```

```sh [pnpm]
pnpm add @rsbuild/core storybook-react-rsbuild storybook-addon-modernjs -D
```

```sh [bun]
bun add @rsbuild/core storybook-react-rsbuild storybook-addon-modernjs -D
```

```sh [deno]
deno add npm:@rsbuild/core npm:storybook-react-rsbuild npm:storybook-addon-modernjs -D
```

请在同一个 workspace 中安装 React framework 包和 `@rsbuild/core`。下面的配置以 `storybook-react-rsbuild` 作为 framework，addon 则需要 `@rsbuild/core` 才能读取你的 Modern.js 配置。

请尽量与 `@modern-js/app-tools` 所使用的版本保持一致。如果你安装了不同的版本，`storybook-addon-modernjs` 会打印一条警告并给出推荐版本。

### 配置 `.storybook/main.ts`

```ts twoslash title=".storybook/main.ts"
// @noErrors
import type { StorybookConfig } from 'storybook-react-rsbuild'

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['storybook-addon-modernjs'],
  framework: 'storybook-react-rsbuild',
}
export default config
```

解析后的 Modern.js config 在合并到 Storybook 之前，会经过 [Builder 选项](/zh/guide/configuration.md#builder-选项) 中记录的 inherited-config 边界。如果确实需要恢复某个已剥离的字段，请在 Storybook 的 `rsbuildFinal` 中显式添加；显式配置会在继承字段被剥离后执行。Modern.js 的 `environments` 配置中只有浏览器 environment（v3 为 `client`，v2 为 `web`）会应用到 preview，其他 environment 会被忽略。

## 结合 Module Federation

完整流程请参阅 [Module Federation 示例](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/modernjs-react-mf)。

### 安装

如果你的 Modern.js 应用使用了 Module Federation，请安装 `@module-federation/storybook-addon`。


```sh [npm]
npm install @module-federation/storybook-addon -D
```

```sh [yarn]
yarn add @module-federation/storybook-addon -D
```

```sh [pnpm]
pnpm add @module-federation/storybook-addon -D
```

```sh [bun]
bun add @module-federation/storybook-addon -D
```

```sh [deno]
deno add npm:@module-federation/storybook-addon -D
```

### 配置 `.storybook/main.ts`

添加该 addon 并手动传入 `remotes` 选项。Storybook 无法自动推断它。

```ts twoslash title=".storybook/main.ts"
// @noErrors
import type { StorybookConfig } from 'storybook-react-rsbuild'
// import moduleFederationConfig from '../module-federation.config'
const moduleFederationConfig = { remotes: {} }

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    'storybook-addon-modernjs',
    {
      name: '@module-federation/storybook-addon',
      options: {
        remotes: moduleFederationConfig.remotes,
      },
    },
  ],
  framework: 'storybook-react-rsbuild',
}
export default config
```

### 配置 `modern.config.ts`

使用 `@module-federation/storybook-addon` 时，请在 Storybook 运行期间于 `modern.config.ts` 中禁用 `moduleFederationPlugin`。

一种做法是检查由你的 Storybook 脚本设置的环境变量。

```json title="package.json"
{
  "scripts": {
    "storybook": "STORYBOOK=true storybook dev -p 6006"
  }
}
```

```ts title="modern.config.ts"
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',
    }),
    ...(process.env.STORYBOOK === 'true' ? [] : [moduleFederationPlugin()]),
  ],
})
```

## 局限性

Modern.js 拥有自己的 plugin 系统，会在将配置交给 Rsbuild 之前对其进行转换。

Modern.js 还会在内部处理用户配置，在 Rsbuild 看到结果之前执行复杂的改动。

:::tip
因此，该 addon 在 Modern.js 中存在一些局限性。
:::

### 🎗 支持的用法

- Modern.js 配置文件
- 用于修改配置的 Modern.js plugin
- Rsbuild plugin

### 😪 不支持的用法

- 不能使用 webpack，仅支持 Rspack
- SSR 配置在 Storybook 中不会生效
- 运行时能力，例如 `<Link>` 导航
- [Modern.js plugin](https://modernjs.dev/plugin/cli-plugins/api.html) 只会调用 `config` 和 `resolveConfig` 这两个 hook

### ☎️ 联系我们

我们目前是通过 Storybook addon（而非 Storybook framework）来支持 Storybook 的。因此，Modern.js 的部分功能在 Storybook 中不可用。

如果你对 Modern.js 与 Storybook 有任何疑问或建议，欢迎随时联系我们。

- [GitHub](https://github.com/web-infra-dev/modern.js)
- [Modern.js Discord](https://discord.gg/qPCqYg38De)