@modern-js/main-doc 2.69.4 → 3.0.0-alpha.0

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

@@ -1,25 +1,33 @@
 # Server-Side Rendering
 
-Server-Side Rendering (SSR) involves rendering the HTML content of a webpage server-side and then sending the fully-rendered page to the browser. The browser only needs to display the page without additional rendering.
+Server-Side Rendering (SSR) generates complete HTML pages on the server and sends them to the browser for direct display, without requiring additional client-side rendering.
 
-The main advantages are:
+## Core Advantages
 
-- **Improved First-Page Load Speed**: SSR generates a complete webpage on the server-side. The browser only needs to download the page content, avoiding additional rendering, thus improving the first-page load speed.
-- **SEO-Friendly**: SSR can generate complete HTML content that search engines can directly index, thereby improving the website's ranking.
+- **Faster First Screen**: Server-side pre-rendering allows the browser to display content directly without waiting for JavaScript execution
+- **Better SEO**: Search engines can directly index complete HTML content
+- **Out of the Box**: No need to write complex server-side logic or maintain separate services
 
-Developers might consider using SSR to render pages in the following scenarios:
+:::info Default Rendering Mode
+Modern.js SSR **uses streaming rendering (Streaming SSR) by default**, allowing pages to be returned progressively as they render, so users can see initial content faster.
 
-1. Websites that require high first-page load speed, such as e-commerce and news websites.
-2. Websites demanding high user experience, such as social networks and gaming websites.
-3. Websites with high SEO requirements, such as company websites and blogs.
+For detailed usage, refer to the [Streaming SSR](/guides/basic-features/render/streaming-ssr) documentation.
 
-In Modern.js, SSR is also available out of the box. Developers don't need to write complex server-side logic or worry about SSR maintenance or creating separate services.
+To switch to traditional SSR mode (waiting for all data to load before returning at once), you can configure:
 
-Apart from the out-of-the-box SSR service, Modern.js also offers:
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: {
+      mode: 'string', // Traditional SSR mode
+    },
+  },
+});
+```
 
-- Comprehensive SSR fallback strategies to ensure the page can run safely.
-- Automatic segmentation of sub-routes with on-demand loading, reducing first-page resource size.
-- Built-in caching system to address high server load issues.
+:::
 
 ## Enabling SSR
 
@@ -30,20 +38,19 @@ import { defineConfig } from '@modern-js/app-tools';
 
 export default defineConfig({
   server: {
-    ssr: true,
+    ssr: true, // Streaming rendering enabled by default
   },
 });
 ```
 
 ## Data Fetching
 
-:::tip Prerequisite
-If you're unfamiliar with how to use Data Loader or the concept of Client Loader, please read [Data Fetching](/guides/basic-features/data/data-fetch) first.
-:::
+Modern.js provides Data Loader, enabling developers to fetch data isomorphically under both SSR and CSR. Each route module (such as `layout.tsx` and `page.tsx`) can define its own Data Loader:
 
-### Basic Usage
+:::tip Learn More
+The following approach will not have streaming rendering effects. To achieve streaming rendering effects, refer to [Streaming SSR](/guides/basic-features/render/streaming-ssr).
 
-Modern.js provides Data Loader, enabling developers to fetch data isomorphically under both SSR and CSR. Each route module, such as `layout.tsx` and `page.tsx`, can define its own Data Loader:
+:::
 
 ```ts title="src/routes/page.data.ts"
 export const loader = () => {
@@ -53,7 +60,7 @@ export const loader = () => {
 };
 ```
 
-In components, you can use hook APIs to access the data returned by the `loader` function:
+Access data in components through Hooks API:
 
 ```tsx
 import { useLoaderData } from '@modern-js/runtime/router';
@@ -65,10 +72,6 @@ export default () => {
 
 ### Using Client Loader
 
-:::info
-This feature requires version x.36.0 or above. We recommend using the latest version of the framework.
-:::
-
 By default, in SSR applications, the `loader` function only executes on the server. However, in some scenarios, developers might want requests made on the client-side to bypass the SSR service and directly fetch data from the source. For example:
 
 1. Reducing network consumption on the client-side by directly fetching from the data source.
@@ -83,17 +86,14 @@ export async function loader({ params }) {
   if (cache.has(params.id)) {
     return cache.get(params.id);
   }
-  const res = await fetch('URL_ADDRESS?id={params.id}');
+  const res = await fetch(`URL_ADDRESS?id=${params.id}`);
+  const data = await res.json();
   return {
-    message: res.message,
+    message: data.message,
   }
 }
 ```
 
-:::warning
-To use Client Loader, there must be a corresponding Server Loader, and the Server Loader must be in a `.data` file, not a `.loader` file.
-:::
-
 ## SSR Fallback
 
 In Modern.js, if an application encounters an error during SSR, it automatically falls back to CSR mode and re-fetches data, ensuring the page can display correctly. SSR fallback can occur for two main reasons:
@@ -291,7 +291,7 @@ Wrap elements that should not be server-side rendered with the `NoSSR` component
 
 After modifying the code, refresh the page and notice that the previous warning has disappeared. Open the browser's developer tools and check the Network tab. The returned HTML document will not contain the content wrapped by the `NoSSR` component.
 
-In practical scenarios, some UI displays might be affected by the user's device, such as [UA](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) information. Modern.js also provides APIs like [`useRuntimeContext`](/apis/app/runtime/core/use-runtime-context), allowing components to access complete request information and maintaining SSR and CSR rendering consistency.
+In practical scenarios, some UI displays might be affected by the user's device, such as [UA](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) information. Modern.js also provides APIs like `use(RuntimeContext)`, allowing components to access complete request information and maintaining SSR and CSR rendering consistency. For detailed usage, please refer to [Runtime Context](/guides/basic-features/render/before-render#runtime-context).
 
 ### Attention to Memory Leaks
 

package/docs/en/guides/basic-features/render/streaming-ssr.mdx

@@ -1,10 +1,16 @@
-# Streaming SSR
+# Streaming Server-Side Rendering
 
-Streaming SSR is a new rendering method that updates the page content in real-time as users interact with it, enhancing user experience.
+Streaming rendering is an advanced rendering method that progressively returns content during the page rendering process, significantly improving user experience.
 
-In conventional rendering, the page is rendered all at once. In streaming rendering, the page is rendered progressively, loading data step-by-step as users interact with the page instead of loading all data at once.
+In traditional SSR rendering, the page is rendered all at once, requiring all data to be loaded before returning the complete HTML. In streaming rendering, the page is rendered progressively, allowing content to be returned as it renders, so users can see initial content faster.
 
-Compared to traditional rendering:
+:::info Default Mode
+**Streaming SSR is the default rendering mode for Modern.js SSR**. When you enable SSR, streaming rendering is available without additional configuration.
+
+If you need to switch to traditional SSR mode (waiting for all data to load before returning at once), you can configure `server.ssr.mode` to `'string'`. For detailed information, refer to the [Server-Side Rendering (SSR)](/guides/basic-features/render/ssr) documentation.
+:::
+
+Compared to traditional SSR rendering:
 
 - **Faster Perceived Speed**: Streaming rendering can progressively display content, quickly rendering the home page.
 - **Enhanced User Experience**: Users can see page content faster and interact without waiting for the entire page to render.
@@ -13,7 +19,19 @@ Compared to traditional rendering:
 
 ## Enabling Streaming Rendering
 
-Modern.js supports React 18's streaming rendering, which can be enabled as follows:
+Modern.js supports React 18+ streaming rendering. When you enable SSR, streaming rendering is enabled by default:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: true, // Streaming rendering enabled by default
+  },
+});
+```
+
+If you need to explicitly specify streaming rendering mode, you can configure:
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
@@ -21,7 +39,7 @@ import { defineConfig } from '@modern-js/app-tools';
 export default defineConfig({
   server: {
     ssr: {
-      mode: 'stream',
+      mode: 'stream', // Explicitly specify streaming rendering mode
     },
   },
 });
@@ -29,7 +47,6 @@ export default defineConfig({
 
 Modern.js streaming rendering is based on React Router and involves several key APIs:
 
-- [`defer`](https://reactrouter.com/en/main/utils/defer): Used in Data Loader to support asynchronous data fetching.
 - [`Await`](https://reactrouter.com/en/main/components/await): Used to render the asynchronous data returned by the Data Loader.
 - [`useAsyncValue`](https://reactrouter.com/en/main/hooks/use-async-value): Used to fetch data from the nearest parent `Await` component.
 
@@ -226,5 +243,8 @@ import StreamSSRPerformance from '@site-docs-en/components/stream-ssr-performanc
 
 ## Related Documentation
 
-1. [Deferred Data](https://reactrouter.com/en/main/guides/deferred)
-2. [New Suspense SSR Architecture in React 18](https://github.com/reactwg/react-18/discussions/37)
+- [Rendering Mode Overview](/guides/basic-features/render/overview)
+- [Server-Side Rendering (SSR)](/guides/basic-features/render/ssr)
+- [Rendering Cache](/guides/basic-features/render/ssr-cache)
+- [React Server Components (RSC)](/guides/basic-features/render/rsc) - Use with Streaming SSR
+- [New Suspense SSR Architecture in React 18](https://github.com/reactwg/react-18/discussions/37) - React 18 Architecture Overview

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

@@ -0,0 +1 @@
+["routes", "config-routes"]

package/docs/en/guides/basic-features/routes/config-routes.mdx

@@ -0,0 +1,427 @@
+---
+sidebar_position: 3
+---
+
+# Config Routes
+
+By default, Modern.js recommends using [Convention Routes](./routes.mdx) as the way to define routes. At the same time, Modern.js also provides a config-based routing capability that can be used together with convention routes or used separately.
+
+
+## When to Use Config Routes
+
+Config routes are particularly useful in the following scenarios:
+
+- **Need flexible route control**: When the file structure cannot directly map to the desired URL structure
+- **Multiple routes pointing to the same component**: Need to point different URL paths to the same page component
+- **Conditional routes**: Dynamically configure routes based on different conditions
+- **Legacy project migration**: Maintain the original routing structure when migrating from other routing systems
+- **Complex route naming**: Need to customize route paths without being limited by file directory structure
+
+## Basic Usage
+
+In the `src` directory or each entry directory, you can define a `modern.routes.[tj]s` file to configure routes:
+
+```ts
+import { defineRoutes } from '@modern-js/runtime/config-routes'
+
+export default defineRoutes(({ route, layout, page, $ }, fileRoutes) => {
+  return [
+    route("home.tsx", "/"),
+  ]
+})
+```
+
+### Function Signature Description
+
+`defineRoutes` accepts a callback function with two parameters:
+1. `routeFunctions`: An object containing `route`, `layout`, `page`, `$` functions
+2. `fileRoutes`: An array of route configurations generated by convention routes
+
+Basic signature of route functions:
+- First parameter: File path relative to `modern.routes.[tj]s`
+- Second parameter: Route path (optional, must be a string)
+- Third parameter: Array of child routes (optional)
+
+
+## Route Functions
+
+Modern.js provides four main route configuration functions:
+
+:::tip Path Description
+
+The first parameter (path) of all route functions is a **relative path**, which will be concatenated with the parent path to generate the final route path:
+- **Root path**: `"/"` or `""` represents the root path of the current level
+- **Relative path**: Child route paths will be concatenated relative to the parent path
+- **Dynamic path**: Use `:param` syntax to represent dynamic parameters
+- **Wildcard path**: Use `"*"` syntax to match all paths
+
+:::
+
+:::info
+
+- The first parameter (component file path) of functions like `route`, `layout`, `page`, `$` must point to real files in the current project. Files from `node_modules` and other repositories in Monorepo are not currently supported.
+- Path aliases are not supported (such as `@/pages/...`, `~/pages/...`, etc.); please use relative paths relative to `modern.routes.[tj]s`.
+
+:::
+
+### `route` Function
+
+The `route` function is a general-purpose route configuration function that automatically determines whether to generate a page route or layout route based on whether there are child routes. It can replace `layout`, `page`, `$` and other functions.
+
+```ts
+export default defineRoutes(({ route }, fileRoutes) => {
+  return [
+    // When no child routes, automatically generates page route
+    route("home.tsx", "/"),
+    route("about.tsx", "about"),
+
+    // When has child routes, automatically generates layout route
+    // dashboard/layout.tsx needs to contain <Outlet> to render child routes
+    route("dashboard/layout.tsx", "dashboard", [
+      route("dashboard/overview.tsx", "overview"),  // Generated path: /dashboard/overview
+      route("dashboard/settings.tsx", "settings"),  // Generated path: /dashboard/settings
+    ]),
+
+    // Dynamic routes
+    route("products/detail.tsx", "products/:id"),
+
+    // Multiple paths pointing to the same component
+    route("user/profile.tsx", "user"),
+    route("user/profile.tsx", "profile"),
+  ]
+})
+```
+
+**Use cases**:
+- Quick route configuration without explicitly specifying page or layout
+- Simplify the complexity of route configuration
+
+### `layout` Function
+
+The `layout` function is specifically used to configure layout routes, always generates layout components, and must contain child routes:
+
+```ts
+export default defineRoutes(({ layout, page }, fileRoutes) => {
+  return [
+    // Generate layout route with path "/auth", must contain child routes
+    layout("auth/layout.tsx", "auth", [
+      page("auth/login/page.tsx", "login"),      // Generated path: /auth/login
+      page("auth/register/page.tsx", "register"), // Generated path: /auth/register
+    ]),
+  ]
+})
+```
+
+**Use cases**:
+- Need to explicitly specify a component as a layout component
+- Provide common layout structure for multiple pages
+- Need to share navigation, sidebar and other UI components across multiple routes
+
+### `page` Function
+
+The `page` function is specifically used to configure page routes, always generates page components:
+
+```ts
+export default defineRoutes(({ layout, page }, fileRoutes) => {
+  return [
+    layout("dashboard/layout.tsx", "dashboard", [
+      page("dashboard/overview.tsx", "overview"),  // Generated path: /dashboard/overview
+      page("dashboard/settings.tsx", "settings"),  // Generated path: /dashboard/settings
+    ]),
+  ]
+})
+```
+
+**Use cases**:
+- Need to explicitly specify a component as a page component
+- Ensure the component does not contain `<Outlet>` child component rendering
+- Provide clearer semantic expression
+
+### `$` Function
+
+The `$` function is specifically used to configure wildcard routes for handling unmatched routes:
+
+```ts
+export default defineRoutes(({ layout, page, $ }, fileRoutes) => {
+  return [
+    layout("blog/layout.tsx", "blog", [
+      page("blog/page.tsx", ""),                    // Generated path: /blog
+      page("blog/[id]/page.tsx", ":id"),            // Generated path: /blog/:id
+      $("blog/$.tsx", "*"),                         // Wildcard route, matches all unmatched paths under /blog
+    ]),
+  ]
+})
+```
+
+**Use cases**:
+- Custom 404 pages
+- Handle all unmatched requests under specific paths
+
+:::tip
+The `$` function has the same functionality as the `$.tsx` file in convention routes, used to catch unmatched route requests.
+:::
+
+
+## Configuring Routes
+
+### Basic Example
+
+```ts
+export default defineRoutes(({ page }, fileRoutes) => {
+  return [
+    // Use page function to explicitly specify page route
+    page("home.tsx", "/"),
+    page("about.tsx", "about"),
+    page("contact.tsx", "contact"),
+  ]
+})
+```
+
+### Routes Without Path
+
+When no path is specified, routes inherit the parent path:
+
+```ts
+export default defineRoutes(({ layout, page }, fileRoutes) => {
+  return [
+    // Use layout function to explicitly specify layout route
+    // auth/layout.tsx needs to contain <Outlet> to render child routes
+    layout("auth/layout.tsx", [
+      page("login/page.tsx", "login"),
+      page("register/page.tsx", "register"),
+    ]),
+  ]
+})
+```
+
+The above configuration will generate:
+- `/login` → `auth/layout.tsx` + `login/page.tsx`
+- `/register` → `auth/layout.tsx` + `register/page.tsx`
+
+### Multiple Paths Pointing to the Same Component
+
+```ts
+export default defineRoutes(({ page }, fileRoutes) => {
+  return [
+    page("user.tsx", "user"),
+    page("user.tsx", "profile"),
+    page("user.tsx", "account"),
+  ]
+})
+```
+
+
+### Dynamic Routes
+
+Config routes support dynamic route parameters:
+
+```ts
+export default defineRoutes(({ page }, fileRoutes) => {
+  return [
+    // Required parameter
+    page("blog/detail.tsx", "blog/:id"),
+
+    // Optional parameter
+    page("blog/index.tsx", "blog/:slug?"),
+  ]
+})
+```
+
+
+## Automatic Route-Related File Discovery
+
+Config routes automatically discover component-related files without manual configuration. For any component file specified in `modern.routes.[tj]s`, Modern.js will automatically find the following related files:
+
+```ts
+// modern.routes.[tj]s
+export default defineRoutes(({ route }, fileRoutes) => {
+  return [
+    route("pages/profile.tsx", "profile"),
+    route("pages/user/detail.tsx", "user/:id"),
+  ]
+})
+```
+
+Modern.js will automatically find and load:
+
+- `pages/profile.data.ts` → Data loader
+- `pages/profile.config.ts` → Route configuration
+- `pages/profile.error.tsx` → Error boundary
+- `pages/profile.loading.tsx` → Loading component
+
+### Discovery Rules
+
+- **File location**: Related files must be in the same directory as the component file
+- **File naming**: Related file names are the same as the component file name (excluding extension)
+- **Auto-discovery**: Modern.js automatically discovers and loads these files
+
+:::tip
+
+For more detailed information about data fetching, please refer to the [Data Fetching](../data/data-fetch.mdx) documentation. For Loading component usage, please refer to [Convention Routes - Loading](./routes.mdx#loading-experimental).
+
+:::
+
+## Route Merging
+
+Config routes can be used together with convention routes. You can merge routes by modifying the `fileRoutes` parameter:
+
+1. **Override routes**: You can actively remove convention routes and replace them with config routes
+2. **Supplement routes**: You can add new config routes based on convention routes
+3. **Mixed usage**: You can add config child routes under convention layout routes
+
+:::info
+
+Current route structure can be viewed through the [`modern routes`](#debugging-routes) command
+
+:::
+
+### Merging Examples
+
+The following examples demonstrate how to merge config routes with convention routes:
+
+```ts
+// modern.routes.ts
+import { defineRoutes } from '@modern-js/runtime/config-routes';
+
+export default defineRoutes(({ page }, fileRoutes) => {
+  // Scenario 1: Override convention routes
+  // Remove the original shop route and replace with custom component
+  const shopPageIndex = fileRoutes[0].children?.findIndex(
+    route => route.id === 'three_shop/page',
+  );
+  fileRoutes[0].children?.splice(shopPageIndex!, 1);
+  fileRoutes[0].children?.push(page('routes/CustomShop.tsx', 'shop'));
+
+  // Scenario 2: Supplement convention routes
+  // Add config routes without corresponding convention routes
+  fileRoutes[0].children?.push(page('routes/Settings.tsx', 'settings'));
+
+  // Scenario 3: Mixed nested routes
+  // Add config child routes under convention layout routes
+  const userRoute = fileRoutes[0].children?.find(
+    (route: any) => route.path === 'user',
+  );
+  if (userRoute?.children) {
+    userRoute.children.push(page('routes/user/CustomTab.tsx', 'custom-tab'));
+  }
+
+  // Scenario 4: Automatic discovery of related files
+  // Product.tsx will automatically discover Product.data.ts and Product.error.tsx
+  fileRoutes[0].children?.push(page('routes/Product.tsx', 'product/:id'));
+
+  return fileRoutes;
+});
+```
+
+## Debugging Routes
+
+Since the final structure after route merging may not be intuitive, Modern.js provides debugging commands to help you view complete route information:
+
+```bash
+# Generate route structure analysis report
+npx modern routes
+```
+
+This command will generate the final route structure in the `dist/routes-inspect.json` file, helping you understand the complete route information after merging.
+
+### Report File Examples
+
+#### Single Entry Scenario
+
+```json title="dist/routes-inspect.json"
+{
+  "routes": [
+    {
+      "path": "/",
+      "component": "@_modern_js_src/routes/page",
+      "data": "@_modern_js_src/routes/page.data",
+      "clientData": "@_modern_js_src/routes/page.data.client",
+      "error": "@_modern_js_src/routes/page.error",
+      "loading": "@_modern_js_src/routes/page.loading"
+    },
+    {
+      "path": "/dashboard",
+      "component": "pages/admin",
+      "config": "pages/admin.config",
+      "error": "pages/admin.error"
+    },
+    {
+      "path": "/user",
+      "component": "layouts/user",
+      "children": [
+        {
+          "path": "/user/profile",
+          "component": "@_modern_js_src/routes/user/profile",
+          "data": "@_modern_js_src/routes/user/profile.data"
+        }
+      ]
+    },
+    {
+      "path": "@_modern_js_src/routes/blog/:id",
+      "component": "blog/detail",
+      "params": ["id"],
+      "data": "blog/detail.data",
+      "loading": "blog/detail.loading"
+    },
+    {
+      "path": "/files/*",
+      "component": "@_modern_js_src/routes/files/list"
+    }
+  ]
+}
+```
+
+#### Multi-entry Scenario
+
+In multi-entry projects, the report file will be grouped by entry name, where the key is entryName:
+
+```json title="dist/routes-inspect.json"
+{
+  "main": {
+    "routes": [
+      {
+        "path": "/",
+        "component": "@_modern_js_src/routes/page",
+        "data": "@_modern_js_src/routes/page.data",
+        "error": "@_modern_js_src/routes/page.error",
+        "loading": "@_modern_js_src/routes/page.loading"
+      },
+      {
+        "path": "/dashboard",
+        "component": "@_modern_js_src/routes/dashboard",
+        "config": "@_modern_js_src/routes/dashboard.config"
+      }
+    ]
+  },
+  "admin": {
+    "routes": [
+      {
+        "path": "/",
+        "component": "@_modern_js_src/routes/dashboard",
+        "data": "@_modern_js_src/routes/dashboard.data",
+        "clientData": "@_modern_js_src/routes/dashboard.data.client",
+        "config": "@_modern_js_src/routes/dashboard.config"
+      },
+      {
+        "path": "/users",
+        "component": "@_modern_js_src/routes/users",
+        "data": "@_modern_js_src/routes/users.data",
+        "error": "@_modern_js_src/routes/users.error",
+        "loading": "@_modern_js_src/routes/users.loading"
+      }
+    ]
+  }
+}
+```
+
+#### Route-Related File Field Descriptions
+
+In addition to basic route information, the report also displays related files found for each route:
+
+- **`data`**: Server-side data loading file (`.data.ts`), used to fetch data on the server
+- **`clientData`**: Client-side data loading file (`.data.client.ts`), used to refetch data on the client
+- **`error`**: Error boundary file (`.error.tsx`), used to handle route rendering errors
+- **`loading`**: Loading state component file (`.loading.tsx`), used to display data loading state
+- **`config`**: Route configuration file (`.config.ts`), used to configure route metadata
+
+These fields are optional and will only be displayed in the report when corresponding files are found. By viewing these fields, you can quickly understand the complete file structure for each route.