@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.97 → 3.5.0-ultramodern.99

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

@@ -0,0 +1,267 @@
+# Streaming Server-Side Rendering
+
+Streaming rendering is an advanced rendering method that progressively returns content during the page rendering process, significantly improving user experience.
+
+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.
+
+:::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.
+- **Better Performance Control**: Developers can better control the loading priority and order, optimizing performance and user experience.
+- **Better Adaptability**: Streaming rendering adapts better to various network speeds and device performance, ensuring good performance across different environments.
+
+## Enabling Streaming Rendering
+
+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';
+
+export default defineConfig({
+  server: {
+    ssr: {
+      mode: 'stream', // Explicitly specify streaming rendering mode
+    },
+  },
+});
+```
+
+Modern.js streaming rendering is based on React Router and involves several key APIs:
+
+- [`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.
+
+## Fetching Data
+
+```ts title="user/[id]/page.data.ts"
+import { defer, type LoaderFunctionArgs } from '@modern-js/runtime/router';
+
+interface User {
+  name: string;
+  age: number;
+}
+
+export interface Data {
+  data: User;
+}
+
+export const loader = ({ params }: LoaderFunctionArgs) => {
+  const userId = params.id;
+
+  const user = new Promise<User>(resolve => {
+    setTimeout(() => {
+      resolve({
+        name: `user-${userId}`,
+        age: 18,
+      });
+    }, 200);
+  });
+
+  return defer({ data: user });
+};
+```
+
+Here, `user` is a Promise object representing asynchronously fetched data, processed using `defer`. Notice that `defer` must receive an object parameter; a direct Promise cannot be passed.
+
+Additionally, `defer` can receive both asynchronous and synchronous data. In the example below, short-duration requests are returned using object data, while longer-duration requests are returned using a Promise:
+
+```ts title="user/[id]/page.data.ts"
+export const loader = async ({ params }: LoaderFunctionArgs) => {
+  const userId = params.id;
+
+  const user = new Promise<User>(resolve => {
+    setTimeout(() => {
+      resolve({
+        name: `user-${userId}`,
+        age: 18,
+      });
+    }, 2000);
+  });
+
+  const otherData = new Promise<string>(resolve => {
+    setTimeout(() => {
+      resolve('some sync data');
+    }, 200);
+  });
+
+  return defer({
+    data: user,
+    other: await otherData,
+  });
+};
+```
+
+This way, the application can prioritize displaying partially available content without waiting for the most time-consuming data requests.
+
+## Rendering Data
+
+To render the asynchronous data returned by the Data Loader, use the `Await` component. For example:
+
+```tsx title="user/[id]/page.tsx"
+import { Await, useLoaderData } from '@modern-js/runtime/router';
+import { Suspense } from 'react';
+import type { Data } from './page.data';
+
+const Page = () => {
+  const data = useLoaderData() as Data;
+
+  return (
+    <div>
+      User info:
+      <Suspense fallback={<div id="loading">loading user data ...</div>}>
+        <Await resolve={data.data}>
+          {user => {
+            return (
+              <div id="data">
+                name: {user.name}, age: {user.age}
+              </div>
+            );
+          }}
+        </Await>
+      </Suspense>
+    </div>
+  );
+};
+
+export default Page;
+```
+
+The `Await` component needs to be wrapped inside a `Suspense` component. The `resolve` prop of `Await` should be the asynchronously fetched data from the Data Loader. When the data is fetched, it will be rendered using the [Render Props](https://zh-hans.react.dev/reference/react/cloneElement#passing-data-with-a-render-prop) pattern. During data fetching, the content set by the `fallback` prop of `Suspense` is displayed.
+
+:::warning Warning
+When importing types from the `page.data.ts` file, use `import type` to ensure only type information is imported, preventing Data Loader code from being bundled into the frontend.
+:::
+
+In the component, you can also fetch asynchronous data returned by the Data Loader using `useAsyncValue`. For example:
+
+```tsx title='page.tsx'
+import { useAsyncValue } from '@modern-js/runtime/router';
+
+const UserInfo = () => {
+  const user = useAsyncValue();
+  return (
+    <div>
+      name: {user.name}, age: {user.age}
+    </div>
+  );
+};
+
+const Page = () => {
+  const data = useLoaderData() as Data;
+  return (
+    <div>
+      User info:
+      <Suspense fallback={<div id="loading">loading user data ...</div>}>
+        <Await resolve={data.data}>
+          <UserInfo />
+        </Await>
+      </Suspense>
+    </div>
+  );
+};
+
+export default Page;
+```
+
+## Error Handling
+
+The `errorElement` prop of the `Await` component handles errors in Data Loader or sub-component rendering. For example, intentionally throwing an error in the Data Loader function:
+
+```ts title="page.loader.ts"
+import { defer } from '@modern-js/runtime/router';
+
+export default () => {
+  const data = new Promise((resolve, reject) => {
+    setTimeout(() => {
+      reject(new Error('error occurs'));
+    }, 200);
+  });
+
+  return defer({ data });
+};
+```
+
+Then, fetch the error using `useAsyncError` and set a component to render the error message for the `errorElement` prop of the `Await` component:
+
+```tsx title="page.ts"
+import { Await, useAsyncError, useLoaderData } from '@modern-js/runtime/router';
+import { Suspense } from 'react';
+
+export default function Page() {
+  const data = useLoaderData();
+
+  return (
+    <div>
+      Error page
+      <Suspense fallback={<div>loading ...</div>}>
+        <Await resolve={data.data} errorElement={<ErrorElement />}>
+          {(data: any) => {
+            return <div>never displayed</div>;
+          }}
+        </Await>
+      </Suspense>
+    </div>
+  );
+}
+
+function ErrorElement() {
+  const error = useAsyncError() as Error;
+  return <p>Something went wrong! {error.message}</p>;
+}
+```
+
+## Controlling When to Wait for Full HTML
+
+Streaming improves perceived speed, but in some cases (SEO crawlers, A/B buckets, compliance pages) you may want to wait for all content before sending the response.
+
+Modern.js decides the streaming mode with this priority:
+
+1. Request header `x-should-stream-all` (set per-request in middleware).
+2. Env `MODERN_JS_STREAM_TO_STRING` (forces full HTML).
+3. [isbot](https://www.npmjs.com/package/isbot) check on `user-agent` (bots get full HTML).
+4. Default: stream shell first.
+
+Set the header in your middleware to choose the behavior dynamically:
+
+```ts title="middleware example"
+export const middleware = async (ctx, next) => {
+  const ua = ctx.req.header('user-agent') || '';
+  const shouldWaitAll = /Lighthouse|Googlebot/i.test(ua) || ctx.req.path === '/marketing';
+
+  // Write a boolean string: true -> onAllReady, false -> onShellReady
+  ctx.req.headers.set('x-should-stream-all', String(shouldWaitAll));
+
+  await next();
+};
+```
+
+import StreamSSRPerformance from '@site-docs-en/components/stream-ssr-performance';
+
+<StreamSSRPerformance />
+
+## Related Documentation
+
+- [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/guides/basic-features/routes/_meta.json

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

package/docs/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.ts` 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.ts`
+- 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.ts`.
+
+:::
+
+### `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.ts`, Modern.js will automatically find the following related files:
+
+```ts
+// modern.routes.ts
+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.