@modern-js/main-doc 3.0.4 → 3.1.0

package/docs/en/components/rsc-deploy-tip.mdx

@@ -0,0 +1 @@
+

package/docs/en/guides/basic-features/debug/using-storybook.mdx

@@ -43,6 +43,58 @@ const config: StorybookConfig = {
 export default config
 ```
 
+
+## BFF Integrated Calls in Storybook
+
+When you want to call BFF APIs directly in Storybook components (for example `/api/**`), start the BFF service and configure a proxy in Storybook's dev server to avoid CORS issues.
+
+### 1. Add scripts
+
+Add the following scripts to `package.json` to start the BFF server and Storybook separately. The `BFF_PROXY` environment variable ensures the proxy is only enabled during Storybook build:
+
+```json
+{
+  "scripts": {
+    "dev:api": "modern dev --api-only",
+    "storybook": "BFF_PROXY=1 storybook dev -p 6006 --no-open",
+  }
+}
+```
+
+### 2. Configure proxy
+
+Add the following config in `modern.config.ts` to proxy requests to the BFF service only during Storybook build:
+
+```ts
+export default applyBaseConfig({
+  dev: process.env.BFF_PROXY
+    ? {
+        server: {
+          proxy: {
+            '/api': 'http://localhost:8080',
+          },
+        },
+      }
+    : {},
+});
+```
+
+Proxy path and port follow this logic:
+
+- If `dev.server.proxy` is configured, use that configuration
+- If not configured, the proxy path falls back to `bff.prefix`, otherwise `/api`
+- If not configured, the target port falls back to `server.port`, otherwise `8080`
+- The final target is `http://localhost:<port>`
+
+### 3. Start
+
+```bash
+pnpm dev:api
+pnpm storybook
+```
+
+Now you can request the path configured in `bff.prefix`; if not configured, use `/api/**`.
+
 ## Example
 
 You can check out the [example](https://github.com/rspack-contrib/storybook-rsbuild/tree/main/sandboxes/modernjs-react) to learn how to use Storybook in Modern.js.

package/docs/en/guides/basic-features/render/rsc.mdx

@@ -513,6 +513,11 @@ export default function ProfilePage() {
 
 When using React 19, you no longer need to use Helmet. We recommend directly using the [components](https://react.dev/reference/react-dom/components) provided by React.
 
+import DeployTip from '@site-docs/components/rsc-deploy-tip';
+
+
+<DeployTip />
+
 ## Common Issues
 
 ### `This entry point is not yet supported outside of experimental channels`

package/docs/en/guides/basic-features/testing/_meta.json

@@ -1 +1 @@
-["playwright", "vitest", "jest", "cypress"]
+["playwright", "rstest", "vitest", "jest", "cypress"]

package/docs/en/guides/basic-features/testing/rstest.mdx

@@ -1,31 +1,33 @@
 # Rstest
 
-Rstest is a testing framework developed by the Rspack team, built on Rspack with extremely fast test execution.
+[Rstest](https://rstest.rs) is a testing framework developed by the Rspack team and built on top of Rspack for fast test execution.
 
-To use Rstest in Modern.js, you need to install the dependencies first by running the following command:
+This guide explains how to integrate Rstest with Modern.js for web app testing.
+
+## Quick Start
+
+Install the base dependencies first:
 
 import { PackageManagerTabs } from '@theme';
 
-<PackageManagerTabs command={{
-  npm: "npm install -D @rstest/core jsdom @testing-library/react @testing-library/dom",
-  yarn: "yarn add -D @rstest/core jsdom @testing-library/react @testing-library/dom",
-  pnpm: "pnpm install -D @rstest/core jsdom @testing-library/react @testing-library/dom",
-  bun: "bun add -D @rstest/core jsdom @testing-library/react @testing-library/dom"
-}} />
+<PackageManagerTabs command="add @rstest/core @modern-js/adapter-rstest -D" />
 
-Next, you need to create a Rstest configuration file `rstest.config.ts` with the following content:
+Then create `rstest.config.ts`:
 
 ```ts title="rstest.config.ts"
 import { defineConfig } from '@rstest/core';
+import { withModernConfig } from '@modern-js/adapter-rstest';
 
 export default defineConfig({
-  environment: 'jsdom',
+  extends: withModernConfig(),
 });
 ```
 
-For more information about Rstest configuration, refer to the [Rstest configuration documentation](https://rstest.rs/config).
+`@modern-js/adapter-rstest` lets Rstest inherit your existing Modern.js config so your test setup stays aligned with your app.
 
-You can optionally add the `rstest` command to `package.json`:
+For more configuration details, refer to the [Rstest configuration documentation](https://rstest.rs/config).
+
+You can run tests with `npx rstest`, or add a script in `package.json`:
 
 ```json title="package.json"
 {
@@ -35,31 +37,99 @@ You can optionally add the `rstest` command to `package.json`:
 }
 ```
 
-After running this command, Rstest will automatically watch for file changes and re-run the tests.
+## Testing Web UI
+
+For web UI tests in Modern.js, there are two common approaches:
+
+- Use Rstest browser mode, which runs tests in a real browser. This is the recommended option in most cases, although it is currently experimental.
+- Use a simulated DOM environment with `happy-dom` and Testing Library. This matches the default web test environment provided by `@modern-js/adapter-rstest`.
+
+We generally recommend browser mode because it uses real browser APIs and behavior, supports cases that simulated DOM environments cannot fully cover, and offers a better debugging experience when UI behavior does not match expectations.
+
+### Browser mode (experimental)
+
+If you want to test in a real browser instead of a simulated DOM, install the browser mode dependencies:
+
+<PackageManagerTabs command="add @rstest/browser @rstest/browser-react playwright -D" />
+
+Then enable browser mode in `rstest.config.ts`:
+
+```ts title="rstest.config.ts"
+import { defineConfig } from '@rstest/core';
+import { withModernConfig } from '@modern-js/adapter-rstest';
+
+export default defineConfig({
+  extends: withModernConfig(),
+  browser: {
+    enabled: true,
+    provider: 'playwright',
+  },
+});
+```
+
+Example test:
+
+```tsx title="__tests__/page.browser.test.tsx"
+import { BrowserRouter as Router } from '@modern-js/runtime/router';
+import { page } from '@rstest/browser';
+import { render } from '@rstest/browser-react';
+import { expect, test } from '@rstest/core';
+import Page from '../routes/page';
+
+test('Page', async () => {
+  await render(
+    <Router>
+      <Page />
+    </Router>,
+  );
+
+  await expect.element(
+    page.getByRole('heading', { level: 1, name: 'Home' }),
+  ).toBeVisible();
+});
+```
+
+For more browser mode setup, Locator APIs, and assertions, refer to the [Rstest documentation](https://rstest.rs/guide/browser-testing/).
+
+### DOM simulation with `happy-dom`
 
-## Creating Unit Tests
+Install the DOM testing dependencies:
+
+<PackageManagerTabs command="add happy-dom @testing-library/react @testing-library/dom -D" />
+
+Update `rstest.config.ts` to use `happy-dom`:
+
+```ts title="rstest.config.ts"
+import { defineConfig } from '@rstest/core';
+import { withModernConfig } from '@modern-js/adapter-rstest';
+
+export default defineConfig({
+  extends: withModernConfig(),
+  testEnvironment: 'happy-dom',
+});
+```
 
 First, create a simple page for testing:
 
 ```tsx title="routes/page.tsx"
 import { Link } from '@modern-js/runtime/router';
 
-const Index = () => (
+const Page = () => (
   <div>
     <h1>Home</h1>
     <Link to="/about">About</Link>
   </div>
 );
 
-export default Index;
+export default Page;
 ```
 
-Add a test case to check if the page contains the expected text:
+Then add a test case:
 
 ```tsx title="__tests__/page.test.tsx"
+import { BrowserRouter as Router } from '@modern-js/runtime/router';
 import { expect, test } from '@rstest/core';
 import { render, screen } from '@testing-library/react';
-import { BrowserRouter as Router } from '@modern-js/runtime/router';
 import Page from '../routes/page';
 
 test('Page', () => {
@@ -68,27 +138,26 @@ test('Page', () => {
       <Page />
     </Router>,
   );
+
   expect(screen.getByRole('heading', { level: 1, name: 'Home' })).toBeDefined();
 });
 ```
 
-In the above test case, we imported the `<Router>` component from `@modern-js/runtime/router` because React Router requires the corresponding context when rendering route-related components.
-
-:::note
-When running directly in a Modern.js application, the `<Router>` component is automatically injected.
-:::
-
 ## Running Test Cases
 
-Execute the `test` command above to run the test cases:
+Execute the `test` command above to run your tests:
 
 ```bash
-✓ src/__tests__/page.test.tsx (1)
+✓ __tests__/page.test.tsx (1)
   ✓ Page
 
-Test Files  1 passed (1)
-    Tests  1 passed (1)
-  Duration  500ms
-
-PASS  Waiting for file changes...
+ Test Files 1 passed
+      Tests 1 passed
+   Duration 510ms (build 145ms, tests 365ms)
 ```
+
+## Node Mode
+
+If you need node mode tests for server-side logic such as `bff`, refer to the [Rstest documentation](https://rstest.rs) directly.
+
+Modern.js mainly targets web apps, so this guide focuses on web UI testing and browser mode.

package/docs/en/guides/upgrade/other.mdx

@@ -170,6 +170,14 @@ antd v5 uses a CSS-in-JS solution and natively supports on-demand loading, so `s
 For more details, refer to [Rsbuild - source.transformImport](https://v2.rsbuild.rs/config/source/transform-import).
 :::
 
+## `node_modules` Resolution Behavior Removed
+
+In Modern.js v1, there was an internal workaround that redirected `node_modules` module resolution to the project root directory. This behavior has been removed in Modern.js 3.0.
+
+This workaround was not a standard practice and could lead to unpredictable dependency resolution — for example, packages not explicitly declared in a project's `package.json` might still resolve successfully, masking missing dependency declarations.
+
+If your project relied on this behavior, ensure that all required dependencies are explicitly declared in your `package.json` and installed locally.
+
 ## ESLint Rule Sets
 
 Modern.js previously provided complete ESLint rule sets, covering @modern-js (Lint rules for Node.js projects) and @modern-js-app (Lint rules for frontend projects). In [v2.60.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.60.0), we officially removed these rule sets. We encourage developers to choose appropriate code specification tools according to their needs, directly use ESLint combined with community-recommended rules, or use Biome to improve code formatting performance.

package/docs/zh/components/rsc-deploy-tip.mdx

@@ -0,0 +1 @@
+

package/docs/zh/guides/basic-features/debug/using-storybook.mdx

@@ -43,6 +43,50 @@ const config: StorybookConfig = {
 export default config
 ```
 
+## Storybook 中进行 BFF 一体化调用
+
+当你希望在 Storybook 的组件中直接调用 BFF 接口（例如请求 `/api/**`）时，需要同时启动 BFF 服务并在 Storybook 的开发服务器中设置代理，避免跨域问题。
+
+### 1. 增加 scripts
+
+在 `package.json` 中增加以下脚本，用于单独启动 BFF 服务和 Storybook，同时通过 `BFF_PROXY` 环境变量确保代理配置仅在 Storybook 构建时生效：
+
+```json
+{
+  "scripts": {
+    "dev:api": "modern dev --api-only",
+    "storybook": "BFF_PROXY=1 storybook dev -p 6006 --no-open",
+  }
+}
+```
+
+### 2. 配置代理解决跨域
+
+在 `modern.config.ts` 中增加以下配置，仅在 Storybook 构建时将请求代理到 BFF 服务：
+
+```ts
+export default applyBaseConfig({
+  dev: process.env.BFF_PROXY
+    ? {
+        server: {
+          proxy: {
+            `${bff.prefix || '/api'}`: `http://localhost:${server.port || '8080'}`,
+          },
+        },
+      }
+    : {},
+});
+```
+
+### 3. 启动方式
+
+```bash
+pnpm dev:api
+pnpm storybook
+```
+
+此时在组件中直接请求 `bff.prefix` 对应的路径即可完成 BFF 一体化调用；如果未配置，则请求 `/api/**`。
+
 ## 示例
 
 你可以查看 [示例](https://github.com/rspack-contrib/storybook-rsbuild/tree/main/sandboxes/modernjs-react) 了解 Modern.js 中使用 Storybook 的方式。

package/docs/zh/guides/basic-features/render/rsc.mdx

@@ -598,6 +598,11 @@ export default function ProfilePage() {
 
 当使用 react19 时，无需再使用 Helmet，推荐直接使用 react 提供的[组件](https://react.dev/reference/react-dom/components)。
 
+import DeployTip from '@site-docs/components/rsc-deploy-tip';
+
+
+<DeployTip />
+
 ## 常见问题
 
 ### `This entry point is not yet supported outside of experimental channels`

package/docs/zh/guides/basic-features/testing/_meta.json

@@ -1 +1 @@
-["playwright", "vitest", "jest", "cypress"]
+["playwright", "rstest", "vitest", "jest", "cypress"]

package/docs/zh/guides/basic-features/testing/rstest.mdx

@@ -1,31 +1,33 @@
 # Rstest
 
-Rstest 是由 Rspack 团队开发的测试框架，基于 Rspack 构建，具有极快的测试执行速度。
+[Rstest](https://rstest.rs) 是由 Rspack 团队开发的测试框架，基于 Rspack 构建，具备很快的测试执行速度。
 
-在 Modern.js 中使用 Rstest 需要先安装依赖，可以执行以下命令：
+本指南介绍如何在 Modern.js 中集成 Rstest，并用于 web app 测试。
+
+## 快速开始
+
+先安装基础依赖：
 
 import { PackageManagerTabs } from '@theme';
 
-<PackageManagerTabs command={{
-  npm: "npm install -D @rstest/core jsdom @testing-library/react @testing-library/dom",
-  yarn: "yarn add -D @rstest/core jsdom @testing-library/react @testing-library/dom",
-  pnpm: "pnpm install -D @rstest/core jsdom @testing-library/react @testing-library/dom",
-  bun: "bun add -D @rstest/core jsdom @testing-library/react @testing-library/dom"
-}} />
+<PackageManagerTabs command="add @rstest/core @modern-js/adapter-rstest -D" />
 
-接下来，你需要创建一个 Rstest 配置文件 `rstest.config.ts`，内容如下：
+然后创建 `rstest.config.ts`：
 
 ```ts title="rstest.config.ts"
 import { defineConfig } from '@rstest/core';
+import { withModernConfig } from '@modern-js/adapter-rstest';
 
 export default defineConfig({
-  environment: 'jsdom',
+  extends: withModernConfig(),
 });
 ```
 
-更多关于 Rstest 配置的信息，可以参考 [Rstest 配置文档](https://rstest.rs/config)。
+`@modern-js/adapter-rstest` 可以让 Rstest 继承你现有的 Modern.js 配置，使测试环境和应用配置保持一致。
 
-你可以选择性的将 `rstest` 命令添加到 `package.json` 中：
+更多配置项可以参考 [Rstest 配置文档](https://rstest.rs/config)。
+
+你可以通过 `npx rstest` 运行测试，也可以在 `package.json` 中添加脚本：
 
 ```json title="package.json"
 {
@@ -35,31 +37,99 @@ export default defineConfig({
 }
 ```
 
-运行该命令后，Rstest 会自动监听你的文件变化，并重新运行用例。
+## 测试 Web UI
+
+在 Modern.js 中测试 Web UI，通常有两种方案：
+
+- 使用 Rstest 的 browser mode，直接在真实浏览器中运行测试。大多数场景更推荐这种方式，但目前仍处于实验性阶段。
+- 使用 `happy-dom` 和 Testing Library 提供一个模拟 DOM 环境，这种方式也符合 `@modern-js/adapter-rstest` 默认的 web 测试环境。
+
+我们整体更推荐 browser mode，因为它使用的是真实浏览器 API 和行为，能覆盖模拟 DOM 难以完整支持的场景，同时在排查 UI 行为问题时也更容易调试。
+
+### Browser mode（实验性）
+
+如果你希望直接在真实浏览器中测试，而不是使用模拟 DOM，可以安装 browser mode 相关依赖：
+
+<PackageManagerTabs command="add @rstest/browser @rstest/browser-react playwright -D" />
+
+然后在 `rstest.config.ts` 中启用 browser mode：
+
+```ts title="rstest.config.ts"
+import { defineConfig } from '@rstest/core';
+import { withModernConfig } from '@modern-js/adapter-rstest';
+
+export default defineConfig({
+  extends: withModernConfig(),
+  browser: {
+    enabled: true,
+    provider: 'playwright',
+  },
+});
+```
+
+示例测试如下：
+
+```tsx title="__tests__/page.browser.test.tsx"
+import { BrowserRouter as Router } from '@modern-js/runtime/router';
+import { page } from '@rstest/browser';
+import { render } from '@rstest/browser-react';
+import { expect, test } from '@rstest/core';
+import Page from '../routes/page';
+
+test('Page', async () => {
+  await render(
+    <Router>
+      <Page />
+    </Router>,
+  );
+
+  await expect.element(
+    page.getByRole('heading', { level: 1, name: 'Home' }),
+  ).toBeVisible();
+});
+```
+
+关于 browser mode 的更多配置、Locator API 和断言能力，可以直接参考 [Rstest 文档](https://rstest.rs/guide/browser-testing/)。
+
+### 使用 `happy-dom` 模拟 DOM
 
-## 创建单元测试
+先安装 DOM 测试相关依赖：
 
-首先，创建一个简单的页面用于测试：
+<PackageManagerTabs command="add happy-dom @testing-library/react @testing-library/dom -D" />
+
+然后在 `rstest.config.ts` 中启用 `happy-dom`：
+
+```ts title="rstest.config.ts"
+import { defineConfig } from '@rstest/core';
+import { withModernConfig } from '@modern-js/adapter-rstest';
+
+export default defineConfig({
+  extends: withModernConfig(),
+  testEnvironment: 'happy-dom',
+});
+```
+
+先创建一个简单页面用于测试：
 
 ```tsx title="routes/page.tsx"
 import { Link } from '@modern-js/runtime/router';
 
-const Index = () => (
+const Page = () => (
   <div>
     <h1>Home</h1>
     <Link to="/about">About</Link>
   </div>
 );
 
-export default Index;
+export default Page;
 ```
 
-添加测试用例，检测页面中是否有预期的文本：
+然后添加测试用例：
 
 ```tsx title="__tests__/page.test.tsx"
+import { BrowserRouter as Router } from '@modern-js/runtime/router';
 import { expect, test } from '@rstest/core';
 import { render, screen } from '@testing-library/react';
-import { BrowserRouter as Router } from '@modern-js/runtime/router';
 import Page from '../routes/page';
 
 test('Page', () => {
@@ -68,27 +138,26 @@ test('Page', () => {
       <Page />
     </Router>,
   );
+
   expect(screen.getByRole('heading', { level: 1, name: 'Home' })).toBeDefined();
 });
 ```
 
-上述用例中，我们从 `@modern-js/runtime/router` 引入了 `<Router>` 组件，这是因为 React Router 在渲染部分路由相关组件时，必须要有对应的上下文。
-
-:::note
-直接在 Modern.js 应用中运行时，`<Router>` 组件会自动注入。
-:::
-
 ## 运行测试用例
 
-执行上述 `test` 命令，运行测试用例：
+执行上面的 `test` 命令即可运行测试：
 
 ```bash
-✓ src/__tests__/page.test.tsx (1)
+✓ __tests__/page.test.tsx (1)
   ✓ Page
 
-Test Files  1 passed (1)
-    Tests  1 passed (1)
-  Duration  500ms
-
-PASS  Waiting for file changes...
+ Test Files 1 passed
+      Tests 1 passed
+   Duration 510ms (build 145ms, tests 365ms)
 ```
+
+## Node Mode
+
+如果你需要测试 `bff` 等 server-side logic，建议直接参考 [Rstest 文档](https://rstest.rs) 中关于 node mode 的说明。
+
+Modern.js 主要面向 web app，因此这里重点介绍的是 Web UI 测试，以及更贴近真实运行环境的 browser mode。

package/docs/zh/guides/upgrade/other.md

@@ -171,6 +171,14 @@ antd v5 使用了 CSS-in-JS 方案，已原生支持按需加载，无需配置
 更多用法请参考 [Rsbuild - source.transformImport](https://v2.rsbuild.rs/config/source/transform-import)。
 :::
 
+## 移除 `node_modules` 解析重定向行为
+
+在 Modern.js v1 版本中，框架内部存在一个 hack，会将 `node_modules` 的模块解析路径强制指向项目根目录。在 Modern.js 3.0 中，我们移除了这一行为。
+
+这一做法并非标准实践，可能导致不可预期的依赖解析问题——例如，未在 `package.json` 中显式声明的依赖包可能仍能被解析，从而掩盖了缺失的依赖声明。
+
+如果你的项目依赖了这一行为，请确保所有需要的依赖都已在 `package.json` 中显式声明并安装到本地。
+
 ## Eslint 规则集
 
 Modern.js 之前提供了 ESLint 的完整规则集，涵盖了 @modern-js（针对 Node.js 项目的 Lint 规则）和 @modern-js-app（针对前端项目的 Lint 规则）。在 [v2.60.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.60.0) 版本中，我们正式移除了这些规则集。我们鼓励开发者根据自身需求选择合适的代码规范工具，直接使用 ESLint 并结合社区推荐的规则，或使用 Biome 以提升代码格式化的性能。

package/package.json

@@ -16,14 +16,14 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.0.4",
+  "version": "3.1.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.12.3",
-    "@modern-js/sandpack-react": "3.0.4"
+    "@modern-js/sandpack-react": "3.1.0"
   },
   "devDependencies": {
     "@rsbuild/plugin-sass": "1.5.0",