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

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

@@ -1,226 +0,0 @@
----
-title: TanStack Router RSC
----
-
-# TanStack Router RSC
-
-Modern.js supports React Server Components (RSC) in TanStack Router projects by treating RSC output as router data. Loaders return serialized Flight streams, TanStack Router owns the data lifecycle, and Modern.js supplies the Flight renderer, decoder, and serialization adapter.
-
-This integration is designed for TanStack Router's data model. It does not use the React Router RSC renderer or `RSCStaticRouter`.
-
-## When to Use It
-
-Use TanStack Router RSC when you want to:
-
-- Render data-heavy UI on the server while keeping TanStack Router as the routing and cache owner.
-- Return server-rendered UI from route loaders and consume it with `Route.useLoaderData()`.
-- Keep interactive UI in Client Components while expensive data access, formatting, and markup generation stay on the server.
-- Refresh server-rendered UI with TanStack Router invalidation after mutations.
-
-For route components that can be ordinary Server Components, use the general [React Server Components (RSC)](/guides/basic-features/render/rsc) guide first. Use this page when server UI needs to flow through TanStack Router loader data.
-
-## Prerequisites
-
-Before using TanStack Router RSC, make sure the project has:
-
-1. React and React DOM 19 or later.
-2. RSC enabled with [`server.rsc`](/configure/app/server/rsc).
-3. TanStack Router selected as the Modern.js routing runtime.
-4. The base RSC setup from [React Server Components (RSC)](/guides/basic-features/render/rsc), including the required RSC runtime dependency.
-
-:::tip
-If your project was created with `--router tanstack`, use `@modern-js/plugin-tanstack/runtime` in route code. This keeps route code aligned with the TanStack plugin that generated it.
-:::
-
-## Enable RSC
-
-Set `server.rsc` to `true` and enable the TanStack Router runtime:
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  runtime: {
-    router: true,
-  },
-  server: {
-    rsc: true,
-  },
-});
-```
-
-## Import Paths
-
-Use the TanStack plugin runtime exports in application code:
-
-- Runtime APIs: `@modern-js/plugin-tanstack/runtime`
-- Server-only RSC helpers: `@modern-js/plugin-tanstack/runtime/rsc/server`
-- Client RSC helpers: `@modern-js/plugin-tanstack/runtime/rsc/client`
-
-The examples below use these paths.
-
-## Payload Router Behavior
-
-When `server.rsc` is enabled, TanStack RSC navigation uses a native payload-router path instead of the React Router `RSCStaticRouter` path:
-
-- Browser navigations that need server loader data request the current URL with `x-rsc-tree: true`.
-- The server runs the matched TanStack route loaders, serializes a `ServerPayload` with matched route ids, params, loader data, errors, location, and route metadata, then streams that payload through the Modern.js RSC renderer.
-- Loader redirects are returned with `X-Modernjs-Redirect` and `X-Modernjs-BaseUrl` headers so the client can continue the navigation through TanStack Router.
-- `404` responses and TanStack `notFound()` results are preserved as route errors so the nearest TanStack not-found boundary can render.
-- Routes marked with a client loader keep running their client loader during RSC navigation. Their server loader data is intentionally omitted from the RSC payload to avoid hydrating stale server data over the client-loader result.
-
-Initial SSR hydration still uses TanStack Router's existing SSR bootstrap scripts. The payload-router request path is only used for subsequent RSC navigations and invalidations, so apps can mix ordinary TanStack SSR loader data and RSC loader data in the same route tree.
-
-## Render Server UI From a Loader
-
-Use `renderServerComponent` when the server output does not need client-provided slots. The loader runs on the server, renders the Server Component to a Flight stream, and returns a value that can be rendered by the client route component.
-
-```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
-Do not return raw JSX from a TanStack Router loader when a client route will consume it. Wrap server-rendered UI with `renderServerComponent` or `createCompositeComponent` so the value can be serialized through TanStack Router's SSR data pipeline.
-:::
-
-## Render Server UI With Client Slots
-
-Use `createCompositeComponent` when server-rendered markup must accept client content, render props, or interactive components. The server component receives slot placeholders, and the client route provides slot implementations through `<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>
-  );
-}
-```
-
-Use `strict` when missing slot implementations should fail fast during development:
-
-```tsx
-<CompositeComponent src={ProductCard} strict />
-```
-
-## Refreshing RSC Data
-
-Because RSC values are TanStack Router data, refresh them with 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>
-  );
-}
-```
-
-If you store RSC values in TanStack Query, disable structural sharing for that query. RSC values are proxies around Flight streams, so deep structural comparison is not meaningful for them.
-
-## Notes
-
-- Server helpers from `*/rsc/server` must only be imported by server code such as loaders or server-only modules.
-- Client routes can render `renderServerComponent` output directly as React nodes.
-- Use `<CompositeComponent>` only for values returned by `createCompositeComponent`.
-- Slot functions should return React nodes and receive serializable arguments. Keep non-serializable objects, request objects, and database handles inside server code.
-- TanStack Router invalidation is the refresh boundary. Avoid building a separate RSC cache outside the router unless the application has a dedicated cache strategy.
-
-## Best Practices
-
-### Prefer Router Data Ownership
-
-Keep RSC values in loader data and let TanStack Router manage cache, hydration, invalidation, and navigation. This keeps the implementation aligned with TanStack Router and avoids a parallel RSC routing layer.
-
-### Use the Smallest Helper That Fits
-
-Use `renderServerComponent` for slotless UI. Use `createCompositeComponent` only when server-rendered markup needs client slots or render props.
-
-### Keep Server and Client Boundaries Clear
-
-Do not import server helpers into client components. Import `CompositeComponent` from the runtime export or from `*/rsc/client`, and import `renderServerComponent` / `createCompositeComponent` only from `*/rsc/server`.
-
-### Automating Changes
-
-When using coding agents or codemods, keep TanStack RSC changes inside the TanStack Router plugin and its RSC helper exports. Do not modify Modern.js core routing or replace the TanStack Router SSR pipeline for this feature.
-
-## Related Links
-
-- [React Server Components (RSC)](/guides/basic-features/render/rsc)
-- [Routing](/guides/basic-features/routes/routes)
-- [Data Cache](/guides/basic-features/data/data-cache)
-- [TanStack Router Documentation](https://tanstack.com/router)

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

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

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

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