@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.12 → 3.2.0-ultramodern.121

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

@@ -1,226 +0,0 @@
----
-title: TanStack Router RSC
----
-
-# TanStack Router RSC
-
-Modern.js 支持在 TanStack Router 项目中使用 React Server Components（RSC）。这套集成会将 RSC 输出作为路由数据处理：Loader 返回序列化后的 Flight stream，由 TanStack Router 管理数据生命周期，Modern.js 负责提供 Flight 渲染、解码与序列化适配器。
-
-这套集成遵循 TanStack Router 的数据模型，不会使用 React Router 的 RSC 渲染器或 `RSCStaticRouter`。
-
-## 适用场景
-
-当你希望实现以下能力时，可以使用 TanStack Router RSC：
-
-- 在服务端渲染数据密集型 UI，同时继续由 TanStack Router 管理路由与缓存。
-- 从路由 Loader 返回服务端渲染的 UI，并通过 `Route.useLoaderData()` 消费。
-- 将交互 UI 保留在 Client Component 中，将复杂的数据访问、格式化与标记生成放在服务端。
-- 在数据写入后，通过 TanStack Router 的 invalidation 刷新服务端渲染的 UI。
-
-如果路由组件本身可以直接作为普通 Server Component 使用，请先阅读通用的 [React Server Components（RSC）](/guides/basic-features/render/rsc) 文档。当服务端 UI 需要通过 TanStack Router Loader 数据传递时，再使用本文介绍的能力。
-
-## 前置条件
-
-使用 TanStack Router RSC 前，请确保项目满足以下条件：
-
-1. React 与 React DOM 已升级到 19 或更高版本。
-2. 通过 [`server.rsc`](/configure/app/server/rsc) 开启 RSC。
-3. 已选择 TanStack Router 作为 Modern.js 路由运行时。
-4. 已完成 [React Server Components（RSC）](/guides/basic-features/render/rsc) 中的基础配置，包括必要的 RSC 运行时依赖。
-
-:::tip
-如果项目通过 `--router tanstack` 创建，请在路由代码中使用 `@modern-js/plugin-tanstack/runtime`，这样可以让路由代码与生成它的 TanStack 插件保持一致。
-:::
-
-## 开启 RSC
-
-设置 `server.rsc` 为 `true`，并开启 TanStack Router 运行时：
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  runtime: {
-    router: true,
-  },
-  server: {
-    rsc: true,
-  },
-});
-```
-
-## 导入路径
-
-在应用代码中使用 TanStack 插件的运行时导出：
-
-- 运行时 API：`@modern-js/plugin-tanstack/runtime`
-- 仅服务端 RSC 辅助函数：`@modern-js/plugin-tanstack/runtime/rsc/server`
-- 客户端 RSC 辅助函数：`@modern-js/plugin-tanstack/runtime/rsc/client`
-
-下面的示例都使用这些路径。
-
-## Payload Router 行为
-
-开启 `server.rsc` 后，TanStack RSC 导航会使用原生的 payload-router 路径，而不是 React Router 的 `RSCStaticRouter` 路径：
-
-- 需要服务端 Loader 数据的浏览器导航会携带 `x-rsc-tree: true` 请求当前 URL。
-- 服务端会执行匹配到的 TanStack 路由 Loader，并序列化包含匹配路由 id、params、loader data、errors、location 与路由元信息的 `ServerPayload`，再通过 Modern.js RSC renderer 以流式方式返回。
-- Loader 重定向会以 `X-Modernjs-Redirect` 与 `X-Modernjs-BaseUrl` 响应头返回，让客户端继续交给 TanStack Router 完成导航。
-- `404` 响应和 TanStack `notFound()` 结果会作为路由错误保留，从而渲染最近的 TanStack not-found boundary。
-- 标记了 client loader 的路由会在 RSC 导航期间继续执行自己的 client loader。对应的服务端 loader data 会从 RSC payload 中有意省略，避免用服务端数据覆盖 client-loader 结果。
-
-首次 SSR hydration 仍然使用 TanStack Router 现有的 SSR bootstrap scripts。payload-router 请求路径只用于后续 RSC 导航和 invalidation，因此同一套路由树可以同时使用普通 TanStack SSR loader data 与 RSC loader data。
-
-## 从 Loader 渲染服务端 UI
-
-当服务端输出不需要客户端提供插槽时，使用 `renderServerComponent`。Loader 在服务端执行，将 Server Component 渲染成 Flight stream，并返回可以被客户端路由组件渲染的值。
-
-```tsx title="src/routes/products/page.data.tsx"
-import { renderServerComponent } from '@modern-js/plugin-tanstack/runtime/rsc/server';
-import { ProductGrid } from './ProductGrid';
-
-export async function loader() {
-  const products = await fetchProducts();
-
-  return {
-    ProductGrid: await renderServerComponent(
-      <ProductGrid products={products} />,
-    ),
-  };
-}
-```
-
-```tsx title="src/routes/products/page.tsx"
-import { createFileRoute } from '@modern-js/plugin-tanstack/runtime';
-
-export const Route = createFileRoute('/products')({
-  component: ProductsPage,
-});
-
-function ProductsPage() {
-  const { ProductGrid } = Route.useLoaderData();
-
-  return <main>{ProductGrid}</main>;
-}
-```
-
-:::warning
-当客户端路由会消费 Loader 返回值时，不要从 TanStack Router Loader 直接返回原始 JSX。请使用 `renderServerComponent` 或 `createCompositeComponent` 包装服务端渲染的 UI，使其能够通过 TanStack Router 的 SSR 数据管线序列化。
-:::
-
-## 渲染带客户端插槽的服务端 UI
-
-当服务端渲染的标记需要接收客户端内容、render props 或交互组件时，使用 `createCompositeComponent`。服务端组件会接收插槽占位符，客户端路由通过 `<CompositeComponent>` 提供插槽实现。
-
-```tsx title="src/routes/products/page.data.tsx"
-import { createCompositeComponent } from '@modern-js/plugin-tanstack/runtime/rsc/server';
-import type React from 'react';
-
-export async function loader() {
-  return {
-    ProductCard: await createCompositeComponent<{
-      AddToCart?: (id: string) => React.ReactNode;
-      children?: React.ReactNode;
-    }>(async props => {
-      const product = await fetchFeaturedProduct();
-
-      return (
-        <article>
-          <h2>{product.name}</h2>
-          {props.children}
-          {props.AddToCart?.(product.id)}
-        </article>
-      );
-    }),
-  };
-}
-```
-
-```tsx title="src/routes/products/page.tsx"
-import {
-  CompositeComponent,
-  createFileRoute,
-} from '@modern-js/plugin-tanstack/runtime';
-import { AddToCartButton } from '../../components/AddToCartButton';
-
-export const Route = createFileRoute('/products')({
-  component: ProductsPage,
-});
-
-function ProductsPage() {
-  const { ProductCard } = Route.useLoaderData();
-
-  return (
-    <CompositeComponent
-      src={ProductCard}
-      AddToCart={id => <AddToCartButton productId={id} />}
-    >
-      <p>Ships today.</p>
-    </CompositeComponent>
-  );
-}
-```
-
-如果希望缺失的插槽实现在开发阶段尽早报错，可以使用 `strict`：
-
-```tsx
-<CompositeComponent src={ProductCard} strict />
-```
-
-## 刷新 RSC 数据
-
-由于 RSC 值属于 TanStack Router 数据，应通过 TanStack Router invalidation 刷新：
-
-```tsx
-import { useRouter } from '@modern-js/plugin-tanstack/runtime';
-
-function SaveButton() {
-  const router = useRouter();
-
-  return (
-    <button
-      onClick={async () => {
-        await saveProduct();
-        await router.invalidate();
-      }}
-    >
-      Save
-    </button>
-  );
-}
-```
-
-如果将 RSC 值存入 TanStack Query，请为对应 query 关闭 structural sharing。RSC 值是 Flight stream 外层的代理对象，对其进行深度结构比较没有实际意义。
-
-## 注意事项
-
-- `*/rsc/server` 中的服务端辅助函数只能被 Loader 或服务端模块导入。
-- 客户端路由可以将 `renderServerComponent` 的返回值直接作为 React node 渲染。
-- `<CompositeComponent>` 只应接收 `createCompositeComponent` 返回的值。
-- 插槽函数应返回 React node，并只接收可序列化参数。不可序列化对象、请求对象、数据库句柄等应保留在服务端代码中。
-- TanStack Router invalidation 是刷新边界。除非应用有明确的缓存策略，否则不要在 Router 之外再构建一套并行的 RSC 缓存。
-
-## 最佳实践
-
-### 优先由 Router 管理数据
-
-将 RSC 值保存在 Loader 数据中，并让 TanStack Router 管理缓存、水合、失效与导航。这样可以保持实现与 TanStack Router 对齐，避免引入并行的 RSC 路由层。
-
-### 使用能满足需求的最小辅助函数
-
-没有客户端插槽的 UI 使用 `renderServerComponent`。只有当服务端渲染的标记需要客户端插槽或 render props 时，才使用 `createCompositeComponent`。
-
-### 保持服务端与客户端边界清晰
-
-不要在客户端组件中导入服务端辅助函数。`CompositeComponent` 应从运行时导出或 `*/rsc/client` 导入；`renderServerComponent` 与 `createCompositeComponent` 只应从 `*/rsc/server` 导入。
-
-### 自动化修改
-
-使用 coding agent 或 codemod 修改相关代码时，应将 TanStack RSC 的改动限制在 TanStack Router 插件及其 RSC 辅助导出内。不要为了该能力修改 Modern.js 核心路由，也不要替换 TanStack Router 的 SSR 管线。
-
-## 相关链接
-
-- [React Server Components（RSC）](/guides/basic-features/render/rsc)
-- [路由基础](/guides/basic-features/routes/routes)
-- [数据缓存](/guides/basic-features/data/data-cache)
-- [TanStack Router 文档](https://tanstack.com/router)

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

@@ -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

@@ -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

@@ -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...
-```