npm - @bleedingdev/modern-js-main-doc - Versions diffs - 3.2.0-ultramodern.5 → 3.2.0-ultramodern.51 - Mend

@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.5 → 3.2.0-ultramodern.51

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

package/docs/en/community/contributing-guide.mdx CHANGED Viewed

@@ -39,8 +39,7 @@ nvm use 22
 ### Install pnpm
 ```sh
-# Enable pnpm with corepack, only available on Node.js >= `v14.19.0`
-corepack enable
+mise install
 ```
 ### Install Dependencies
@@ -125,7 +124,7 @@ pnpm run reset
 If you've fixed a bug or added code that should be tested, then add some tests.
-You can add unit test cases in the `<PACKAGE_DIR>/tests` folder. The test syntax is based on [Rstest](https://rstest.rs/).
+Modern.js uses [Rstest](https://rstest.rs/) for unit tests across the repository. You can add test cases in the `<PACKAGE_DIR>/tests` folder, using Rstest syntax.
 ### Run Unit Tests

package/docs/en/components/init-app.mdx CHANGED Viewed

@@ -19,16 +19,16 @@ To initialize a TanStack Router template:
 npx @modern-js/create@latest myapp --router tanstack
 ```
-To initialize with Tailwind CSS v4 scaffold:
+Tailwind CSS v4 is scaffolded by default. To opt out:
 ```bash
-npx @modern-js/create@latest myapp --tailwind
+npx @modern-js/create@latest myapp --no-tailwind
 ```
-To initialize TanStack Router with Tailwind CSS v4:
+To initialize TanStack Router with the default Tailwind CSS v4 scaffold:
 ```bash
-npx @modern-js/create@latest myapp --router tanstack --tailwind
+npx @modern-js/create@latest myapp --router tanstack
 ```
 To initialize BFF scaffold with the current default runtime:
@@ -101,7 +101,7 @@ Now, the project structure is as follows:
 └── tsconfig.json
 ```
-When `--tailwind` is enabled, `postcss.config.mjs` and `tailwind.config.ts` are generated in the project root.
+Tailwind CSS v4 is generated by default; pass `--no-tailwind` to omit `postcss.config.mjs`, `tailwind.config.ts`, and the Tailwind import.
 When `--bff` or `--bff-runtime effect` is enabled, `modern.config.ts` enables `@modern-js/plugin-bff`, generates `api/effect/index.ts` + `shared/effect/api.ts`, and sets `bff.runtimeFramework` to `effect`.
 When `--bff-runtime hono` is enabled, `modern.config.ts` enables `@modern-js/plugin-bff`, generates `api/lambda/hello.ts`, and sets `bff.runtimeFramework` to `hono`.

package/docs/en/components/prerequisites.mdx CHANGED Viewed

@@ -9,7 +9,7 @@ import NodeVersion from '@site-docs-en/components/nodeVersion.mdx';
 It is recommended to use [pnpm](https://pnpm.io/installation) to manage dependencies:
 ```bash
-npm install -g pnpm@10
+mise use pnpm@11.4.0
 ```
 :::note

package/docs/en/guides/advanced-features/international/api.mdx CHANGED Viewed

@@ -15,10 +15,13 @@ title: API Reference
 | `language` | `string` | Current language code |
 | `changeLanguage` | `(lang: string) => Promise<void>` | Switches language |
 | `supportedLanguages` | `string[]` | Supported language list, from `localeDetection.languages` |
+| `localisedUrls` | `boolean \| Record<string, Record<string, string>>` | Localised URL mapping from `localeDetection.localisedUrls` |
 | `isLanguageSupported` | `(lang: string) => boolean` | Checks whether a language is in the supported list |
 | `isResourcesReady` | `boolean` | Whether translation resources for the current language have finished loading |
 | `i18nInstance` | `I18nInstance` | i18next instance for advanced scenarios |
+When `localePathRedirect` is enabled and `localisedUrls` is omitted, Modern.js treats localised URL paths as enabled. Route generation still requires every localisable path to define every configured language unless you set `localisedUrls: false`.
 ### Basic Usage
 ```tsx
@@ -91,7 +94,7 @@ A route link component with a locale prefix.
 | `children` | `React.ReactNode` | Yes | Link content |
 | `replace` | `boolean` | No | Uses `history.replace` instead of `push` |
 | `state` | `any` | No | State passed to the target route |
-| Other Link props | - | No | Inherited from the `Link` component in `@modern-js/runtime/router` |
+| Other Link props | - | No | Passed to the active router link when a router is available |
 ### Usage

package/docs/en/guides/advanced-features/international/configuration.mdx CHANGED Viewed

@@ -49,6 +49,7 @@ export default defineConfig({
 | `languages` | `string[]` | `[]` | Supported language list |
 | `fallbackLanguage` | `string` | `''` | Fallback language when detection fails |
 | `localePathRedirect` | `boolean` | `false` | Handles URL locale prefix recognition, redirects, and switching. See [Routing Integration](./routing.md#enable-locale-path-prefixes) |
+| `localisedUrls` | `boolean \| Record<string, Record<string, string>>` | `true` when `localePathRedirect` is enabled | Localised route path map. Every localisable route must define every configured language. Set `false` to keep locale prefixes without translating path segments. |
 | `i18nextDetector` | `boolean` | `false` | Enables the i18next detector (Cookie / Header, etc.) |
 | `detection` | `LanguageDetectorOptions` | - | Detailed i18next detector configuration. See [Locale Detection](./locale-detection.md) |
 | `ignoreRedirectRoutes` | `string[] \| Function` | - | Routes that skip redirects. See [Locale Detection](./locale-detection.md#ignoreredirectroutes) |

package/docs/en/guides/advanced-features/international/locale-detection.mdx CHANGED Viewed

@@ -113,7 +113,7 @@ i18nPlugin({
 ## ignoreRedirectRoutes
-Specify which paths should skip locale path redirects. This is useful for API routes, static assets, and other paths that do not need a locale prefix.
+Specify which additional paths should skip locale path redirects. Modern.js automatically skips server API routes and BFF prefixes, including configured `bff.prefix` values. Use `ignoreRedirectRoutes` for non-API application paths that also do not need a locale prefix.
 **Syntax 1: string array** (supports exact match and prefix match)

package/docs/en/guides/advanced-features/international/routing.mdx CHANGED Viewed

@@ -32,7 +32,48 @@ i18nPlugin({
 | `/en/about` | Visits normally, language is `en` |
 | `/zh/about` | Visits normally, language is `zh` |
-Some paths, such as API routes and static assets, do not need locale prefixes. Use `ignoreRedirectRoutes` to skip redirects. See [Locale Detection -> ignoreRedirectRoutes](./locale-detection.md#ignoreredirectroutes).
+API and BFF prefixes are skipped automatically, so server API routes do not need locale prefixes or `localisedUrls` entries. For additional application paths that should not redirect, use `ignoreRedirectRoutes`. See [Locale Detection -> ignoreRedirectRoutes](./locale-detection.md#ignoreredirectroutes).
+## Localised URL Paths
+When `localePathRedirect` is enabled, `localisedUrls` is enabled by default. This means every localisable route path must define a URL for every configured language. If you add a new language to `languages`, Modern.js will fail route generation until each localised URL entry includes that language too.
+`localisedUrls` applies to file-system routes generated for both React Router and TanStack Router projects. Do not configure localised URL entries for API routes, BFF prefixes, or configured `bff.prefix` values; those paths are excluded from locale redirects automatically.
+```ts
+// modern.config.ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    languages: ['en', 'cs'],
+    fallbackLanguage: 'en',
+    localisedUrls: {
+      '/terms-of-service': {
+        en: '/terms-of-service',
+        cs: '/podminky-pouzivani',
+      },
+      '/products': {
+        en: '/products',
+        cs: '/produkty',
+      },
+      '/products/:slug': {
+        en: '/products/:slug',
+        cs: '/produkty/:slug',
+      },
+    },
+  },
+});
+```
+**Result:**
+| Visited path | Result |
+| --- | --- |
+| `/terms-of-service` | Redirects to `/en/terms-of-service` |
+| `/cs/terms-of-service` | Redirects to `/cs/podminky-pouzivani` |
+| `/cs/podminky-pouzivani` | Visits normally, language is `cs` |
+Set `localisedUrls: false` only when you want locale prefixes without translated path segments.
 ## Route Configuration
@@ -131,4 +172,4 @@ function Navigation() {
 <I18nLink to="/en/about">About</I18nLink>
 ```
-`I18nLink` extends the `Link` component from `@modern-js/runtime/router` and supports all standard Link props such as `replace`, `state`, and `className`. For the full Props type, see [API Reference](./api.md#i18nlink-component).
+`I18nLink` uses the active Modern.js router. In React Router projects it renders the React Router `Link`; in TanStack Router projects it navigates through TanStack Router. For the full Props type, see [API Reference](./api.md#i18nlink-component).

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

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

package/docs/en/guides/get-started/tech-stack.mdx CHANGED Viewed

@@ -84,6 +84,12 @@ Modern.js can be used with any React UI component library from the community, su
 Modern.js supports the use of [Storybook](https://storybook.js.org/) for developing UI components. This feature is optional. Please refer to ["Using Storybook"](/guides/basic-features/debug/using-storybook) to enable it.
+## Testing Framework
+Modern.js recommends [Rstest](https://rstest.rs/) for unit tests and component tests. Rstest is built on Rspack for fast startup and execution, and it can reuse your Modern.js app configuration through [`@modern-js/adapter-rstest`](/guides/basic-features/testing/rstest).
+For end-to-end (E2E) tests, you can use [Playwright](/guides/basic-features/testing/playwright).
 ## Node.js Framework
 import TechStackNodeFramework from '@site-docs-en/components/tech-stack-node-framework';

package/docs/en/guides/get-started/ultramodern.mdx CHANGED Viewed

@@ -76,6 +76,90 @@ In this repo, the reference examples are:
 - `bff-runtime-parity` for generated-client build/serve parity,
 - `bff-hono` for the compatibility lane.
+## Tractor Reference Workspace
+The BleedingDev create entrypoint now scaffolds the real Tractor reference workspace instead of the earlier visual boundary demo:
+```bash
+pnpm dlx @bleedingdev/modern-js-create tractor-super-app
+cd tractor-super-app
+mise install
+mise exec -- pnpm install
+mise exec -- pnpm ultramodern:check
+```
+The generated workspace has one shell and three full-stack vertical remotes:
+| Package | Owner role | Port | Owns |
+| --- | --- | --- | --- |
+| `apps/shell-super-app` | platform shell | `3020` | route assembly, topology selection, MF host config, shell CSS overlays, global fallback policy |
+| `apps/remotes/remote-explore` | Explore vertical | `3021` | tractor discovery routes, header/footer/recommendations/store picker exposes, `/explore-api/effect/explore/*` |
+| `apps/remotes/remote-decide` | Decide vertical | `3022` | product selection and configuration routes, `ProductPage`, `/decide-api/effect/decide/*` |
+| `apps/remotes/remote-checkout` | Checkout vertical | `3023` | cart, checkout, thanks routes, cart exposes, `/checkout-api/effect/checkout/*` |
+The shell consumes remotes through Module Federation references in topology metadata and `zephyr:dependencies`; it should not hardcode deployed remote URLs in source. Each vertical owns its UI route subtree, browser-safe MF exposes, Effect BFF contract, generated client export, locale JSON, CSS entrypoint, Cloudflare Worker metadata, and build marker.
+### Route-Owned I18n
+Each app emits `src/routes/ultramodern-route-metadata` with `ultramodernLocalisedUrls`. The i18n plugin reads that map in `localeDetection.localisedUrls`, serves dynamic backend JSON from `/locales/{{lng}}/{{ns}}.json`, and keeps `reactI18next` disabled for the generated shell and remotes.
+Examples:
+| Vertical | Canonical route | English | Czech |
+| --- | --- | --- | --- |
+| Explore | `/tractors` | `/tractors` | `/traktory` |
+| Explore | `/stores` | `/stores` | `/prodejci` |
+| Decide | `/tractors/:slug` | `/tractors/:slug` | `/traktory/:slug` |
+| Checkout | `/cart` | `/cart` | `/kosik` |
+| Checkout | `/checkout/thank-you/:orderId?` | `/checkout/thank-you/:orderId?` | `/pokladna/dekujeme/:orderId?` |
+The route owner changes localized paths and locale resource JSON together. Shell-owned URL rewrites are not part of the contract.
+### Federated CSS Contract
+The generated contract writes `.modernjs/ultramodern-generated-contract.json` with a `cssFederation` section:
+- `packages/shared-design-tokens` owns the shared token layer and exports `./tokens.css`.
+- Shell CSS owns only shell base and overlay layers under `[data-app-id="shell-super-app"]`.
+- Remote CSS owns one vertical layer, for example `[data-app-id="remote-explore"]` with `explore-` class prefixes.
+- Tailwind CSS v4 is local to each generated app through `@tailwindcss/postcss`; shared base styles must not be duplicated by remotes.
+- SSR first paint requires shared token CSS and app-owned CSS to be emitted by Modern/Rspack assets. Remote CSS is loaded through remote manifest ownership, not copied into shell source.
+Version switching must select UI, Effect API, CSS, i18n JSON, and MF manifest evidence from the same vertical build marker. A shell render that only changes the UI marker is not enough.
+### Validation And Proof
+Local gates:
+```bash
+mise exec -- pnpm ultramodern:check
+mise exec -- pnpm build
+mise exec -- pnpm cloudflare:build
+```
+Local Cloudflare artifact validation can run without public credentials:
+```bash
+node scripts/ultramodern-cloudflare-ssr-validation/validate-cloudflare-ssr.js \
+  --root-dir apps/remotes/remote-explore \
+  --bff /explore-api/effect/explore/readiness \
+  --expect-en "Explore Remote" \
+  --match-build-marker \
+  --out .codex/reports/cloudflare-ssr/remote-explore-local.json
+```
+Generated workspaces also include `scripts/proof-cloudflare-version.mjs`:
+```bash
+ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP=https://shell-super-app.example.workers.dev \
+ULTRAMODERN_PUBLIC_URL_REMOTE_EXPLORE=https://remote-explore.example.workers.dev \
+ULTRAMODERN_PUBLIC_URL_REMOTE_DECIDE=https://remote-decide.example.workers.dev \
+ULTRAMODERN_PUBLIC_URL_REMOTE_CHECKOUT=https://remote-checkout.example.workers.dev \
+mise exec -- pnpm cloudflare:proof -- --require-public-urls
+```
+Live Cloudflare and Zephyr proof requires public Worker URLs and Zephyr credentials. Without those, the repo can validate generated contracts, local builds, local Cloudflare output, dry-run Zephyr evidence plans, and local evidence schemas, but it cannot prove shell-driven live version selection.
 ## Baseline Switches (Opt-out)
 The generated `presetUltramodern(...)` starter enables strict platform contracts. Use these env switches to opt out per app or per environment:

package/docs/zh/community/contributing-guide.mdx CHANGED Viewed

@@ -38,8 +38,7 @@ nvm use 22
 ### 安装 pnpm
 ```bash
-# 使用 corepack 启用 pnpm，仅在 Node.js >= `v14.19.0` 上可用
-corepack enable
+mise install
 ```
 ### 安装依赖
@@ -124,7 +123,7 @@ pnpm run reset
 如果你进行了 bugfix，或者添加了需要测试的代码，请添加一些测试代码。
-你可以在 `<PACKAGE_DIR>/tests` 文件夹中添加单元测试用例。测试语法基于 [Rstest](https://rstest.rs/)。
+Modern.js 仓库的单元测试统一使用 [Rstest](https://rstest.rs/)。你可以在 `<PACKAGE_DIR>/tests` 文件夹中添加测试用例，测试语法基于 Rstest。
 ### 运行单元测试

package/docs/zh/components/init-app.mdx CHANGED Viewed

@@ -19,16 +19,16 @@ npx @modern-js/create@latest myapp
 npx @modern-js/create@latest myapp --router tanstack
 ```
-初始化 Tailwind CSS v4 模板：
+默认会初始化 Tailwind CSS v4 模板。如需关闭：
 ```bash
-npx @modern-js/create@latest myapp --tailwind
+npx @modern-js/create@latest myapp --no-tailwind
 ```
-同时初始化 TanStack Router + Tailwind CSS v4：
+初始化 TanStack Router，并使用默认 Tailwind CSS v4 模板：
 ```bash
-npx @modern-js/create@latest myapp --router tanstack --tailwind
+npx @modern-js/create@latest myapp --router tanstack
 ```
 初始化当前默认运行时的 BFF 模板：
@@ -101,7 +101,7 @@ npx @modern-js/create@latest myapp --router tanstack --bff-runtime effect --work
 └── tsconfig.json
 ```
-当启用 `--tailwind` 时，项目根目录会额外生成 `postcss.config.mjs` 和 `tailwind.config.ts`。
+默认会生成 Tailwind CSS v4；传入 `--no-tailwind` 时会省略 `postcss.config.mjs`、`tailwind.config.ts` 和 Tailwind 导入。
 当启用 `--bff` 或 `--bff-runtime effect` 时，会在 `modern.config.ts` 中启用 `@modern-js/plugin-bff`，生成 `api/effect/index.ts` 与 `shared/effect/api.ts`，并将 `bff.runtimeFramework` 设置为 `effect`。
 当启用 `--bff-runtime hono` 时，会在 `modern.config.ts` 中启用 `@modern-js/plugin-bff`，生成 `api/lambda/hello.ts`，并将 `bff.runtimeFramework` 设置为 `hono`。

package/docs/zh/components/prerequisites.mdx CHANGED Viewed

@@ -9,7 +9,7 @@ import NodeVersion from '@site-docs/components/nodeVersion.mdx';
 推荐使用 [pnpm](https://pnpm.io/installation) 来管理依赖：
 ```bash
-npm install -g pnpm@10
+mise use pnpm@11.4.0
 ```
 :::note

package/docs/zh/guides/advanced-features/international/api.mdx CHANGED Viewed

@@ -15,10 +15,13 @@ title: API 参考
 | `language` | `string` | 当前语言代码 |
 | `changeLanguage` | `(lang: string) => Promise<void>` | 切换语言 |
 | `supportedLanguages` | `string[]` | 支持的语言列表（来自 `localeDetection.languages`） |
+| `localisedUrls` | `boolean \| Record<string, Record<string, string>>` | 来自 `localeDetection.localisedUrls` 的本地化 URL 映射 |
 | `isLanguageSupported` | `(lang: string) => boolean` | 检查语言是否在支持列表中 |
 | `isResourcesReady` | `boolean` | 当前语言的翻译资源是否已加载完成 |
 | `i18nInstance` | `I18nInstance` | i18next 实例（用于高级场景） |
+启用 `localePathRedirect` 且省略 `localisedUrls` 时，Modern.js 会将本地化 URL 路径视为已启用。除非设置 `localisedUrls: false`，否则路由生成仍要求每个可本地化路径都为所有已配置语言提供路径。
 ### 基本用法
 ```tsx
@@ -91,7 +94,7 @@ function MyComponent() {
 | `children` | `React.ReactNode` | 是 | 链接内容 |
 | `replace` | `boolean` | 否 | 使用 `history.replace` 而非 `push` |
 | `state` | `any` | 否 | 传递给目标路由的状态 |
-| 其他 Link props | — | 否 | 继承自 `@modern-js/runtime/router` 的 `Link` 组件 |
+| 其他 Link props | — | 否 | 有可用路由时会传递给当前路由的 Link 组件 |
 ### 用法

package/docs/zh/guides/advanced-features/international/configuration.mdx CHANGED Viewed

@@ -48,6 +48,7 @@ export default defineConfig({
 | `languages` | `string[]` | `[]` | 支持的语言列表 |
 | `fallbackLanguage` | `string` | `''` | 语言检测失败时的兜底语言 |
 | `localePathRedirect` | `boolean` | `false` | 接管 URL 语言前缀的识别、重定向和切换，详见[路由集成](./routing.md#启用语言路径前缀) |
+| `localisedUrls` | `boolean \| Record<string, Record<string, string>>` | 启用 `localePathRedirect` 时为 `true` | 本地化路由路径映射。每个可本地化路由都必须为所有已配置语言提供路径。设置为 `false` 时只保留语言前缀，不翻译路径片段。 |
 | `i18nextDetector` | `boolean` | `false` | 启用 i18next 检测器（Cookie / Header 等） |
 | `detection` | `LanguageDetectorOptions` | — | i18next 检测器详细配置，见[语言检测](./locale-detection.md) |
 | `ignoreRedirectRoutes` | `string[] \| Function` | — | 跳过重定向的路由，见[语言检测](./locale-detection.md#ignoreredirectroutes) |

package/docs/zh/guides/advanced-features/international/locale-detection.mdx CHANGED Viewed

@@ -113,7 +113,7 @@ i18nPlugin({
 ## ignoreRedirectRoutes
-指定哪些路径跳过语言路径重定向，适用于 API 路由、静态资源等不需要语言前缀的路径。
+指定哪些额外路径跳过语言路径重定向。Modern.js 会自动跳过服务端 API 路由和 BFF 前缀，包括配置的 `bff.prefix`。`ignoreRedirectRoutes` 适用于其他不需要语言前缀的非 API 业务路径。
 **写法一：字符串数组**（支持精确匹配和前缀匹配）

package/docs/zh/guides/advanced-features/international/routing.mdx CHANGED Viewed

@@ -32,7 +32,48 @@ i18nPlugin({
 | `/en/about` | 正常访问，语言为 `en` |
 | `/zh/about` | 正常访问，语言为 `zh` |
-某些路径（如 API 路由、静态资源）不需要语言前缀，可以通过 `ignoreRedirectRoutes` 跳过重定向，详见[语言检测 → ignoreRedirectRoutes](./locale-detection.md#ignoreredirectroutes)。
+API 和 BFF 前缀会自动跳过，因此服务端 API 路由不需要语言前缀，也不需要配置 `localisedUrls`。如果还有其他业务路径不应该重定向，可以使用 `ignoreRedirectRoutes`，详见[语言检测 → ignoreRedirectRoutes](./locale-detection.md#ignoreredirectroutes)。
+## 本地化 URL 路径
+启用 `localePathRedirect` 后，`localisedUrls` 默认启用。每个可本地化的路由路径都必须为所有已配置语言提供 URL。如果向 `languages` 中新增语言，Modern.js 会在路由生成阶段失败，直到每个 `localisedUrls` 条目都补齐该语言。
+`localisedUrls` 同时适用于 React Router 和 TanStack Router 项目的约定式路由。不要为 API 路由、BFF 前缀或配置的 `bff.prefix` 添加本地化 URL 条目；这些路径会自动排除在语言重定向之外。
+```ts
+// modern.config.ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    languages: ['en', 'cs'],
+    fallbackLanguage: 'en',
+    localisedUrls: {
+      '/terms-of-service': {
+        en: '/terms-of-service',
+        cs: '/podminky-pouzivani',
+      },
+      '/products': {
+        en: '/products',
+        cs: '/produkty',
+      },
+      '/products/:slug': {
+        en: '/products/:slug',
+        cs: '/produkty/:slug',
+      },
+    },
+  },
+});
+```
+**效果：**
+| 访问路径 | 结果 |
+| --- | --- |
+| `/terms-of-service` | 重定向到 `/en/terms-of-service` |
+| `/cs/terms-of-service` | 重定向到 `/cs/podminky-pouzivani` |
+| `/cs/podminky-pouzivani` | 正常访问，语言为 `cs` |
+只有在希望保留语言前缀、但不翻译路径片段时，才设置 `localisedUrls: false`。
 ## 路由配置
@@ -131,4 +172,4 @@ function Navigation() {
 <I18nLink to="/en/about">关于</I18nLink>
 ```
-`I18nLink` 继承自 `@modern-js/runtime/router` 的 `Link` 组件，支持 `replace`、`state`、`className` 等所有标准 Link props，完整 Props 类型见 [API 参考](./api.md#i18nlink-组件)。
+`I18nLink` 会使用当前启用的 Modern.js 路由。在 React Router 项目中渲染 React Router 的 `Link`；在 TanStack Router 项目中通过 TanStack Router 导航。完整 Props 类型见 [API 参考](./api.md#i18nlink-组件)。

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

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

package/docs/zh/guides/get-started/tech-stack.mdx CHANGED Viewed

@@ -84,6 +84,12 @@ Modern.js 可以与社区中任意的 React 组件库搭配使用，比如 [MUI]
 Modern.js 支持使用 [Storybook](https://storybook.js.org/) 来开发 UI 组件。该功能为可选功能，请参考 [使用 Storybook](/guides/basic-features/debug/using-storybook) 启用。
+## 测试框架
+Modern.js 推荐使用 [Rstest](https://rstest.rs/) 编写单元测试和组件测试。Rstest 基于 Rspack 构建，启动和执行速度快，并且可以通过 [`@modern-js/adapter-rstest`](/guides/basic-features/testing/rstest) 复用 Modern.js 的应用配置。
+如果需要编写端到端（E2E）测试，可以使用 [Playwright](/guides/basic-features/testing/playwright)。
 ## Node.js 框架
 import TechStackNodeFramework from '@site-docs/components/tech-stack-node-framework';

package/package.json CHANGED Viewed

@@ -18,24 +18,24 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.2.0-ultramodern.5",
+  "version": "3.2.0-ultramodern.51",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.15.0",
-    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.2.0-ultramodern.5"
+    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.2.0-ultramodern.51"
   },
   "devDependencies": {
     "@rsbuild/plugin-sass": "1.5.2",
-    "@rspress/core": "2.0.11",
-    "@rspress/plugin-llms": "2.0.11",
-    "@rspress/shared": "2.0.11",
-    "@shikijs/transformers": "^4.0.2",
+    "@rspress/core": "2.0.12",
+    "@rspress/plugin-llms": "2.0.12",
+    "@rspress/shared": "2.0.12",
+    "@shikijs/transformers": "^4.1.0",
     "@types/fs-extra": "11.0.4",
-    "@types/node": "^25.8.0",
-    "@typescript/native-preview": "7.0.0-dev.20260516.1",
+    "@types/node": "^25.9.1",
+    "@typescript/native-preview": "7.0.0-dev.20260527.2",
     "classnames": "^2.5.1",
     "clsx": "^2.1.1",
     "fs-extra": "^11.3.5",

package/docs/en/guides/basic-features/testing/cypress.mdx DELETED Viewed

@@ -1,95 +0,0 @@
-# Cypress
-Cypress is a framework for E2E testing and component testing.
-To use Cypress in Modern.js, you need to install the dependencies first. You can run the following commands:
-import { PackageManagerTabs } from '@theme';
-<PackageManagerTabs command={{ npm: "npm install -D cypress", yarn: "yarn add -D cypress", pnpm: "pnpm install -D cypress" }} />
-Next, create a `cypress.config.ts` file and add the following content:
-```ts
-import { defineConfig } from 'cypress'
-export default defineConfig({
-  e2e: {
-    setupNodeEvents(on, config) {},
-  },
-})
-```
-## Writing Test Cases
-Now, use Cypress to write an E2E test case by first creating two Modern.js pages.
-```tsx title="routes/page.tsx"
-import { Link } from '@modern-js/runtime/router';
-const Index = () => (
-  <div>
-    <h1>Home</h1>
-    <Link to="/about">About</Link>
-  </div>
-);
-export default Index;
-```
-```tsx title="routes/about/page.tsx"
-import { Link } from '@modern-js/runtime/router';
-const Index = () => (
-  <div>
-    <h1>About</h1>
-    <Link to="/">Home</Link>
-  </div>
-);
-export default Index;
-```
-Next, create the test case file:
-```ts title="cypress/e2e/app.cy.ts"
-describe('Navigation', () => {
-  it('should navigate to the about page', () => {
-    // Start from the index page
-    cy.visit('http://localhost:8080/')
-    // Find a link with an href attribute containing "about" and click it
-    cy.get('a[href*="about"]').click()
-    // The new url should include "/about"
-    cy.url().should('include', '/about')
-    // The new page should contain an h1 with "About"
-    cy.get('h1').contains('About')
-  })
-})
-```
-The test file may lack type definitions for the API. You can refer to the [Cypress - Typescript](https://docs.cypress.io/guides/tooling/typescript-support#Configure-tsconfigjson) documentation to resolve this.
-You can add the command to your `package.json`:
-```json title="package.json"
-{
-  "scripts": {
-    "test": "cypress open"
-  }
-}
-```
-## Run Test Cases
-Execute the above `test` command to run the test cases:
-```bash
-DevTools listening on ws://127.0.0.1:55203/devtools/browser/xxxxx
-```
-Cypress will open a headless browser. Following the prompts, you can find the corresponding test files and automatically run the E2E tests:
-![cypress](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/cypress.jpg)

package/docs/en/guides/basic-features/testing/jest.mdx DELETED Viewed

@@ -1,148 +0,0 @@
-# Jest
-Jest is a JavaScript testing framework that is primarily used with React Testing Library for unit testing and Snapshot testing.
-To use Jest in Modern.js, you need to install the dependencies first. You can run the following commands:
-import { PackageManagerTabs } from '@theme';
-<PackageManagerTabs command={{
-  npm: "npm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom",
-  yarn: "yarn add -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom",
-  pnpm: "pnpm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom"
-}} />
-Next, you can run the following commands to automatically initialize Jest in your project and generate a basic `jest.config.ts` configuration:
-<PackageManagerTabs command={{
-  npm: "npm init jest@latest",
-  yarn: "yarn create jest@latest",
-  pnpm: "pnpm create jest@latest"
-}} />
-## Configuration File
-:::note
-This section will use `.ts` files for Jest testing.
-:::
-Compared to other testing frameworks, Jest requires more configuration at the build level, such as handling JSX and ESM syntax. Therefore, you need to install some additional dependencies:
-<PackageManagerTabs command={{
-  npm: "npm install -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript",
-  yarn: "yarn add -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript",
-  pnpm: "pnpm install -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript"
-}} />
-### Configure Jest
-You need to further configure the `jest.config.ts` file to allow Jest to correctly compile and run test cases. Here is a basic configuration:
-```ts title="jest.config.ts"
-import type { Config } from 'jest';
-const config: Config = {
-  coverageProvider: 'babel',
-  setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
-  testEnvironment: 'jsdom',
-  transform: {
-    '^.+\\.(js|jsx|ts|tsx)$': 'babel-jest',
-  },
-  transformIgnorePatterns: [],
-};
-export default config;
-```
-In the configuration, the `transformIgnorePatterns` is set to an empty array, meaning that all files will be compiled. If you want to speed up the test run, you can configure it as needed.
-The `setupFilesAfterEnv` will be executed at startup. In `jest.setup.ts`, you can import `@testing-library/jest-dom`, which includes a set of convenient custom matchers, such as `.toBeInTheDocument()`, to make writing tests easier:
-```ts title="jest.setup.ts"
-import '@testing-library/jest-dom';
-```
-### Configure Babel
-You need to configure Babel to allow Jest to automatically compile JSX and other syntax. Here is a basic configuration:
-```js title="babel.config.js"
-module.exports = {
-  presets: [
-    ['@babel/preset-env', { targets: { node: 'current' } }],
-    ['@babel/preset-react', { runtime: 'automatic' }],
-    '@babel/preset-typescript',
-  ],
-};
-```
-## Writing Test Cases
-Now, you can start writing tests. First, add a `test` command in `package.json`:
-```json title="package.json"
-{
-  "scripts": {
-    "test": "jest"
-  }
-}
-```
-Create a simple page for testing:
-```tsx title="routes/page.tsx"
-import { Link } from '@modern-js/runtime/router';
-const Index = () => (
-  <div>
-    <h1>Home</h1>
-    <Link to="/about">About</Link>
-  </div>
-);
-export default Index;
-```
-Add a test case to check if the page has the expected text:
-```tsx title="__tests__/page.test.tsx"
-import '@testing-library/jest-dom';
-import { render, screen } from '@testing-library/react';
-import { BrowserRouter as Router } from '@modern-js/runtime/router';
-import Page from '../routes/page';
-describe('Page', () => {
-  it('renders a heading', () => {
-    render(
-      <Router>
-        <Page />
-      </Router>,
-    );
-    const heading = screen.getByRole('heading', { level: 1 });
-    expect(heading).toBeInTheDocument();
-  });
-});
-```
-In the above test case, we imported the `<Router>` component from `@modern-js/runtime/router` because React Router requires the corresponding context when rendering some route-related components.
-:::note
-When running directly in the Modern.js application, the `<Router>` component will be automatically injected.
-:::
-## Run Test Cases
-Execute the above `test` command to run the test cases:
-```bash
- PASS  src/__tests__/page.test.tsx
-  Page
-    ✓ renders a heading (31 ms)
-Test Suites: 1 passed, 1 total
-Tests:       1 passed, 1 total
-Snapshots:   0 total
-Time:        0.959 s, estimated 1 s
-```

package/docs/en/guides/basic-features/testing/vitest.mdx DELETED Viewed

@@ -1,100 +0,0 @@
-# Vitest
-Vitest is a testing framework driven by Vite, which can be used for unit testing in combination with React Testing Library.
-To use Vitest in Modern.js, you need to install the dependencies first. You can run the following commands:
-import { PackageManagerTabs } from '@theme';
-<PackageManagerTabs command={{
-  npm: "npm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom",
-  yarn: "yarn add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom",
-  pnpm: "pnpm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom",
-  bun: "bun add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom"
-}} />
-Next, you need to create a Vitest configuration file `vitest.config.ts` with the following content:
-```ts title="vitest.config.ts"
-import { defineConfig } from 'vitest/config'
-import react from '@vitejs/plugin-react'
-export default defineConfig({
-  plugins: [react()],
-  test: {
-    environment: 'jsdom',
-  },
-})
-```
-For more information about Vitest configuration, you can refer to the [Vitest configuration documentation](https://vitest.dev/config/#configuration).
-You can optionally add the `vitest` command to `package.json`:
-```json title="package.json"
-{
-  "scripts": {
-    "test": "vitest"
-  }
-}
-```
-After running this command, Vitest will automatically watch your file changes and rerun the test cases.
-## Create Unit Tests
-First, create a simple page for testing:
-```tsx title="routes/page.tsx"
-import { Link } from '@modern-js/runtime/router';
-const Index = () => (
-  <div>
-    <h1>Home</h1>
-    <Link to="/about">About</Link>
-  </div>
-);
-export default Index;
-```
-Add a test case to check if the page has the expected text:
-```tsx title="__tests__/page.test.tsx"
-import { expect, test } from 'vitest';
-import { render, screen } from '@testing-library/react';
-import { BrowserRouter as Router } from '@modern-js/runtime/router';
-import Page from '../routes/page';
-test('Page', () => {
-  render(
-    <Router>
-      <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 some route-related components.
-:::note
-When running directly in the Modern.js application, the `<Router>` component will be automatically injected.
-:::
-## Run Test Cases
-Execute the above `test` command to run the test cases:
-```bash
-✓ src/__tests__/page.test.tsx (1)
-  ✓ Page
-Test Files  1 passed (1)
-    Tests  1 passed (1)
-  Start at  15:37:12
-  Duration  999ms (transform 119ms, setup 0ms, collect 365ms, tests 33ms, environment 421ms, prepare 44ms)
-PASS  Waiting for file changes...
-```

package/docs/zh/guides/basic-features/testing/cypress.mdx DELETED Viewed

@@ -1,95 +0,0 @@
-# Cypress
-Cypress 是一个用于 E2E 测试和组件测试的框架。
-在 Modern.js 中使用 Cypress 需要先安装依赖，可以执行以下命令：
-import { PackageManagerTabs } from '@theme';
-<PackageManagerTabs command={{ npm: "npm install -D cypress", yarn: "yarn add -D cypress", pnpm: "pnpm install -D cypress" }} />
-接下来，创建 `cypress.config.ts` 文件，并添加以下内容：
-```ts
-import { defineConfig } from 'cypress'
-export default defineConfig({
-  e2e: {
-    setupNodeEvents(on, config) {},
-  },
-})
-```
-## 编写测试用例
-现在，使用 Cypress 来编写一个 E2E 用例，首先创建两张 Modern.js 的页面。
-```tsx title="routes/page.tsx"
-import { Link } from '@modern-js/runtime/router';
-const Index = () => (
-  <div>
-    <h1>Home</h1>
-    <Link to="/about">About</Link>
-  </div>
-);
-export default Index;
-```
-```tsx title="routes/about/page.tsx"
-import { Link } from '@modern-js/runtime/router';
-const Index = () => (
-  <div>
-    <h1>About</h1>
-    <Link to="/">Home</Link>
-  </div>
-);
-export default Index;
-```
-接下来，创建测试用例文件：
-```ts title="cypress/e2e/app.cy.ts"
-describe('Navigation', () => {
-  it('should navigate to the about page', () => {
-    // Start from the index page
-    cy.visit('http://localhost:8080/')
-    // Find a link with an href attribute containing "about" and click it
-    cy.get('a[href*="about"]').click()
-    // The new url should include "/about"
-    cy.url().should('include', '/about')
-    // The new page should contain an h1 with "About"
-    cy.get('h1').contains('About')
-  })
-})
-```
-测试文件可能会缺少 API 的类型，你可以参考 [Cypress - Typescript](https://docs.cypress.io/guides/tooling/typescript-support#Configure-tsconfigjson) 文档解决。
-你可以将命令添加到 `package.json` 中：
-```json title="package.json"
-{
-  "scripts": {
-    "test": "cypress open"
-  }
-}
-```
-## 运行测试用例
-执行上述 `test` 命令，运行测试用例：
-```bash
-DevTools listening on ws://127.0.0.1:55203/devtools/browser/xxxxx
-```
-Cypress 会打开一个无头浏览器，按照提示你可以找到对应的测试文件，并自动运行 E2E 测试：
-![cypress](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/cypress.jpg)

package/docs/zh/guides/basic-features/testing/jest.mdx DELETED Viewed

@@ -1,148 +0,0 @@
-# Jest
-Jest 是一个 JavaScript 测试框架，它主要和 React Testing Library 一起用于单元测试和 Snapshot 测试。
-在 Modern.js 中使用 Jest 需要先安装依赖，可以执行以下命令：
-import { PackageManagerTabs } from '@theme';
-<PackageManagerTabs command={{
-  npm: "npm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom",
-  yarn: "yarn add -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom",
-  pnpm: "pnpm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom"
-}} />
-随后，你可以运行以下命令，这将自动在项目中初始化 Jest，并生成一个基础的 `jest.config.ts` 配置：
-<PackageManagerTabs command={{
-  npm: "npm init jest@latest",
-  yarn: "yarn create jest@latest",
-  pnpm: "pnpm create jest@latest"
-}} />
-## 配置文件
-:::note
-本章节会使用 `.ts` 文件来完成 Jest 测试。
-:::
-相比于其他的测试框架，Jest 在构建层面需要更多的配置，例如处理 JSX 和 ESM 语法，因此首先需要安装一些额外的依赖：
-<PackageManagerTabs command={{
-  npm: "npm install -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript",
-  yarn: "yarn add -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript",
-  pnpm: "pnpm install -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript"
-}} />
-### 配置 Jest
-你需要进一步配置 `jest.config.ts` 文件，以便让 Jest 能够正确地编译和运行测试用例。下面是一个最基本的配置：
-```ts title="jest.config.ts"
-import type { Config } from 'jest';
-const config: Config = {
-  coverageProvider: 'babel',
-  setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
-  testEnvironment: 'jsdom',
-  transform: {
-    '^.+\\.(js|jsx|ts|tsx)$': 'babel-jest',
-  },
-  transformIgnorePatterns: [],
-};
-export default config;
-```
-配置中，将 `transformIgnorePatterns` 设置为了空数组，意味着所有的文件都会经过编译，如果你希望提升测试运行的速度，可以按需配置。
-`setupFilesAfterEnv` 会在启动时执行，在 `jest.setup.ts` 中，可以引入 `@testing-library/jest-dom`。它包含了一组便捷的自定义匹配器，例如 `.toBeInTheDocument()`，使编写测试变得更容易：
-```ts title="jest.setup.ts"
-import '@testing-library/jest-dom';
-```
-### 配置 Babel
-你需要配置 Babel 让 Jest 能够自动编译 JSX 等语法，下面是一个基本的配置：
-```js title="babel.config.js"
-module.exports = {
-  presets: [
-    ['@babel/preset-env', { targets: { node: 'current' } }],
-    ['@babel/preset-react', { runtime: 'automatic' }],
-    '@babel/preset-typescript',
-  ],
-};
-```
-## 编写测试用例
-现在，你可以开始编写测试用例了，首先在 `package.json` 中添加一个 `test` 命令：
-```json title="package.json"
-{
-  "scripts": {
-    "test": "jest"
-  }
-}
-```
-创建一个简单的页面用于测试：
-```tsx title="routes/page.tsx"
-import { Link } from '@modern-js/runtime/router';
-const Index = () => (
-  <div>
-    <h1>Home</h1>
-    <Link to="/about">About</Link>
-  </div>
-);
-export default Index;
-```
-添加测试用例，检测页面中是否有预期的文本：
-```tsx title="__tests__/page.test.tsx"
-import '@testing-library/jest-dom';
-import { render, screen } from '@testing-library/react';
-import { BrowserRouter as Router } from '@modern-js/runtime/router';
-import Page from '../routes/page';
-describe('Page', () => {
-  it('renders a heading', () => {
-    render(
-      <Router>
-        <Page />
-      </Router>,
-    );
-    const heading = screen.getByRole('heading', { level: 1 });
-    expect(heading).toBeInTheDocument();
-  });
-});
-```
-上述用例中，我们从 `@modern-js/runtime/router` 引入了 `<Router>` 组件，这是因为 React Router 在渲染部分路由相关组件时，必须要有对应的上下文。
-:::note
-直接在 Modern.js 应用中运行时，`<Router>` 组件会自动注入。
-:::
-## 运行测试用例
-执行上述 `test` 命令，运行测试用例：
-```bash
- PASS  src/__tests__/page.test.tsx
-  Page
-    ✓ renders a heading (31 ms)
-Test Suites: 1 passed, 1 total
-Tests:       1 passed, 1 total
-Snapshots:   0 total
-Time:        0.959 s, estimated 1 s
-```

package/docs/zh/guides/basic-features/testing/vitest.mdx DELETED Viewed

@@ -1,100 +0,0 @@
-# Vitest
-Vitest 是由 Vite 驱动的测试框架，和 React Testing Library 配合可以用于单元测试。
-在 Modern.js 中使用 Vitest 需要先安装依赖，可以执行以下命令：
-import { PackageManagerTabs } from '@theme';
-<PackageManagerTabs command={{
-  npm: "npm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom",
-  yarn: "yarn add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom",
-  pnpm: "pnpm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom",
-  bun: "bun add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom"
-}} />
-接下来，你需要创建一个 Vitest 配置文件 `vitest.config.ts`，内容如下：
-```ts title="vitest.config.ts"
-import { defineConfig } from 'vitest/config'
-import react from '@vitejs/plugin-react'
-export default defineConfig({
-  plugins: [react()],
-  test: {
-    environment: 'jsdom',
-  },
-})
-```
-更多关于 Vitest 配置的信息，可以参考 [Vitest 配置文档](https://vitest.dev/config/#configuration)。
-你可以选择性的将 `vitest` 命令添加到 `package.json` 中：
-```json title="package.json"
-{
-  "scripts": {
-    "test": "vitest"
-  }
-}
-```
-运行该命令后，Vitest 会自动监听你的文件变化，并重新运行用例。
-## 创建单元测试
-首先，创建一个简单的页面用于测试：
-```tsx title="routes/page.tsx"
-import { Link } from '@modern-js/runtime/router';
-const Index = () => (
-  <div>
-    <h1>Home</h1>
-    <Link to="/about">About</Link>
-  </div>
-);
-export default Index;
-```
-添加测试用例，检测页面中是否有预期的文本：
-```tsx title="__tests__/page.test.tsx"
-import { expect, test } from 'vitest';
-import { render, screen } from '@testing-library/react';
-import { BrowserRouter as Router } from '@modern-js/runtime/router';
-import Page from '../routes/page';
-test('Page', () => {
-  render(
-    <Router>
-      <Page />
-    </Router>,
-  );
-  expect(screen.getByRole('heading', { level: 1, name: 'Home' })).toBeDefined();
-});
-```
-上述用例中，我们从 `@modern-js/runtime/router` 引入了 `<Router>` 组件，这是因为 React Router 在渲染部分路由相关组件时，必须要有对应的上下文。
-:::note
-直接在 Modern.js 应用中运行时，`<Router>` 组件会自动注入。
-:::
-## 运行测试用例
-执行上述 `test` 命令，运行测试用例：
-```bash
-✓ src/__tests__/page.test.tsx (1)
-  ✓ Page
-Test Files  1 passed (1)
-    Tests  1 passed (1)
-  Start at  15:37:12
-  Duration  999ms (transform 119ms, setup 0ms, collect 365ms, tests 33ms, environment 421ms, prepare 44ms)
-PASS  Waiting for file changes...
-```