@modern-js/main-doc 3.9.2 → 3.10.0

package/docs/en/guides/advanced-features/server-monitor/metrics.mdx

@@ -8,15 +8,15 @@ When SSR is enabled, we need to monitor server-side phase durations and have the
 
 Based on server-side runtime logic, Modern.js provides the following metric events:
 
-| Key                      | Description              |
-| ------------------------ | ------------------------ |
-| server-handle-request    | Modern.js Server request handling duration                          |
+| Key                      | Description                                                                                                           |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| server-handle-request    | Modern.js Server request handling duration                                                                            |
 | ssr-render-shell         | [SSR] When using Streaming SSR, React renders a shell for early streaming. This marks shell rendering completion time |
-| ssr-render-html          | [SSR] Time taken by React to render component tree to HTML (typically under 50ms) |
-| server-middleware        | Total execution time of Modern.js custom server middlewares         |
-| server-loader            | Server-side Data Loader total duration                          |
-| server-loader-#id        | Individual Data Loader durations on server-side                 |
-| server-loader-navigation | Server-side Data Loader duration during client navigation       |
+| ssr-render-html          | [SSR] Time taken by React to render component tree to HTML (typically under 50ms)                                     |
+| server-middleware        | Total execution time of Modern.js custom server middlewares                                                           |
+| server-loader            | Server-side Data Loader total duration                                                                                |
+| server-loader-#id        | Individual Data Loader durations on server-side                                                                       |
+| server-loader-navigation | Server-side Data Loader duration during client navigation                                                             |
 
 Modern.js server workflow diagram:
 

package/docs/en/guides/advanced-features/server-monitor/monitors.mdx

@@ -129,9 +129,7 @@ const myMonitorPlugin = (): ServerPlugin => ({
           console.log(`[${event.payload.level}] ${event.payload.message}`);
         } else if (event.type === 'timing') {
           // Handle timing events
-          console.log(
-            `Timing: ${event.payload.name} = ${event.payload.dur}ms`,
-          );
+          console.log(`Timing: ${event.payload.name} = ${event.payload.dur}ms`);
         } else if (event.type === 'counter') {
           // Handle counter events
           console.log(`Counter: ${event.payload.name}`);

package/docs/en/guides/advanced-features/source-build.mdx

@@ -142,7 +142,7 @@ At the same time, we need to set `composite` to `true` in the lib project's `tsc
 {
   "compilerOptions": {
     "composite": true
-  },
+  }
 }
 ```
 

package/docs/en/guides/advanced-features/web-server.mdx

@@ -50,13 +50,13 @@ After creating the file, you can write custom logic in this file.
 
 3. Include `server` directory in `tsconfig.json`
 
-```json5
+```jsonc
 {
   // ...
   "include": [
     // ...
-    "server"
-  ]
+    "server",
+  ],
 }
 ```
 

package/docs/en/guides/basic-features/data/data-fetch.mdx

@@ -24,9 +24,7 @@ Modern.js recommends managing routes using [conventional routing](/guides/basic-
 In the `routes/user/page.data.ts` file, you can export a Data Loader function:
 
 ```ts title="routes/user/page.data.ts"
-export type ProfileData = {
-  /*  some types */
-};
+export type ProfileData = {/*  some types */};
 
 export const loader = async (): Promise<ProfileData> => {
   const res = await fetch('https://api/user/profile');

package/docs/en/guides/basic-features/data/data-write.mdx

@@ -42,7 +42,7 @@ import {
   useFetcher,
   useLoaderData,
   useParams,
-  Outlet
+  Outlet,
 } from '@modern-js/runtime/router';
 
 export default () => {
@@ -50,23 +50,21 @@ export default () => {
   const { submit } = useFetcher();
   const editUser = () => {
     const newUser = {
-      name: 'Modern.js'
-    }
+      name: 'Modern.js',
+    };
     return submit(newUser, {
       method: 'post',
       encType: 'application/json',
-    })
-  }
+    });
+  };
   return (
     <div>
       <button onClick={editUser}>edit user</button>
-      <div className="user-profile">
-        {userInfo}
-      </div>
+      <div className="user-profile">{userInfo}</div>
       <Outlet context={userInfo}></Outlet>
     </div>
-  )
-}
+  );
+};
 ```
 
 After executing `submit`, the defined `action` function will be triggered. You can get the submitted data from the [parameters](/guides/basic-features/data/data-write.html#parameters) in the `action` function and ultimately send the data to the server.
@@ -123,17 +121,18 @@ useSubmit:
 
 ```ts
 const submit = useSubmit();
-submit(null, { method: "post", action: "/logout" });
+submit(null, { method: 'post', action: '/logout' });
 ```
 
 useFetcher:
 
 ```ts
 const { submit } = useFetcher();
-submit(null, { method: "post", action: "/logout" });
+submit(null, { method: 'post', action: '/logout' });
 ```
 
 The `submit` function takes two parameters. The first parameter is the `formData` passed to the server. The second parameter is an optional object where:
+
 - `method` corresponds to the form submission method. In most data writing scenarios, you can set the `method` to `post`.
 - `action` specifies the route component to trigger the Data Action. If not provided, it defaults to the current route component's action. For example, executing submit in `user/page.tsx` or its sub-components will trigger the action defined in `user/page.data.ts`.
 
@@ -151,7 +150,7 @@ For example, `FormData`:
 
 ```ts
 let formData = new FormData();
-formData.append("cheese", "gouda");
+formData.append('cheese', 'gouda');
 submit(formData);
 // In the action, you can get the data by request.json
 ```
@@ -160,7 +159,7 @@ or `URLSearchParams`:
 
 ```ts
 let searchParams = new URLSearchParams();
-searchParams.append("cheese", "gouda");
+searchParams.append('cheese', 'gouda');
 submit(searchParams);
 // In the action, you can get the data by request.json
 ```
@@ -168,10 +167,10 @@ submit(searchParams);
 or any value that the `URLSearchParams` constructor accepts:
 
 ```ts
-submit("cheese=gouda&toasted=yes");
+submit('cheese=gouda&toasted=yes');
 submit([
-  ["cheese", "gouda"],
-  ["toasted", "yes"],
+  ['cheese', 'gouda'],
+  ['toasted', 'yes'],
 ]);
 // In the action, you can get the data by request.json
 ```
@@ -180,11 +179,11 @@ By default, if the first parameter of the `submit` function is an object, the co
 
 ```ts
 submit(
-  { key: "value" },
+  { key: 'value' },
   {
-    method: "post",
-    encType: "application/x-www-form-urlencoded",
-  }
+    method: 'post',
+    encType: 'application/x-www-form-urlencoded',
+  },
 );
 
 // In the action, you can get the data by request.formData
@@ -193,14 +192,11 @@ submit(
 You can also specify the encoding type via the second parameter:
 
 ```tsx
-submit(
-  { key: "value" },
-  { method: "post", encType: "application/json" }
-);
+submit({ key: 'value' }, { method: 'post', encType: 'application/json' });
 
 submit('{"key":"value"}', {
-  method: "post",
-  encType: "application/json",
+  method: 'post',
+  encType: 'application/json',
 });
 
 // In the action, you can get the data by request.json
@@ -209,7 +205,7 @@ submit('{"key":"value"}', {
 or submit plain text:
 
 ```ts
-submit("value", { method: "post", encType: "text/plain" });
+submit('value', { method: 'post', encType: 'text/plain' });
 // In the action, you can get the data by request.text
 ```
 

package/docs/en/guides/basic-features/debug/mock.mdx

@@ -102,8 +102,8 @@ type MockConfig = {
 };
 
 export const config = {
-  enable: false
-}
+  enable: false,
+};
 ```
 
 Currently only the `enable` configuration is supported, which allows developers to control whether to execute mock.

package/docs/en/guides/basic-features/debug/using-storybook.mdx

@@ -2,7 +2,7 @@
 sidebar_position: 15
 ---
 
-import { PackageManagerTabs } from '@theme'
+import { PackageManagerTabs } from '@theme';
 
 # Using Storybook
 
@@ -33,17 +33,16 @@ You need to install `@rsbuild/core` in your project, otherwise the plugin may no
 ## Configure `.storybook/main.ts`
 
 ```ts
-import type { StorybookConfig } from 'storybook-react-rsbuild'
+import type { StorybookConfig } from 'storybook-react-rsbuild';
 
 const config: StorybookConfig = {
   stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
   addons: ['storybook-addon-modernjs'],
   framework: 'storybook-react-rsbuild',
-}
-export default config
+};
+export default config;
 ```
 
-
 ## BFF Integrated Calls in Storybook
 
 When you want to call BFF APIs directly in Storybook components (for example `/api/**`), start the BFF service and configure a proxy in Storybook's dev server to avoid CORS issues.
@@ -56,7 +55,7 @@ Add the following scripts to `package.json` to start the BFF server and Storyboo
 {
   "scripts": {
     "dev:api": "modern dev --api-only",
-    "storybook": "BFF_PROXY=1 storybook dev -p 6006 --no-open",
+    "storybook": "BFF_PROXY=1 storybook dev -p 6006 --no-open"
   }
 }
 ```

package/docs/en/guides/basic-features/html.mdx

@@ -19,9 +19,8 @@ For example, consider the following directory structure:
     ├── entry-a
     │   ├── Document.tsx
     │   └── routes
-    ├── entry-b
-    │    └── routes
-    └── modern-app-env.d.ts
+    └── entry-b
+         └── routes
 ```
 
 `entry-a` will use the `Document.tsx` file under the current entry as the template. If there is no `Document.tsx` file under the current entry, like `entry-b`, it will look for the `Document.tsx` file under the root directory.

package/docs/en/guides/basic-features/output-files.mdx

@@ -113,7 +113,7 @@ export default {
   },
   html: {
     outputStructure: 'flat',
-  }
+  },
 };
 ```
 

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

@@ -8,21 +8,21 @@ Modern.js supports multiple rendering modes, and different rendering modes are s
 
 ## Rendering Mode Quick Reference
 
-| Rendering Mode | Characteristics | Use Cases |
-|----------------|-----------------|-----------|
-| **CSR** | Executes JavaScript in the browser to render pages | Applications with strong interactivity and low SEO requirements |
-| **SSR** | Pre-renders complete HTML pages on the server | Websites with high requirements for first-screen performance and SEO |
-| **Streaming SSR** | Renders and returns progressively, displaying initial UI faster | Applications requiring faster first-screen perception speed (**Default SSR mode**) |
-| **RSC** | Components render on the server, reducing client JS size; high cohesion between data and component logic, reducing state passing | Projects pursuing optimal performance and needing to reduce client-side code |
-| **SSG** | Generates static pages at build time, can be cached by CDN | Websites with relatively static content, such as blogs and documentation sites |
+| Rendering Mode    | Characteristics                                                                                                                  | Use Cases                                                                          |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| **CSR**           | Executes JavaScript in the browser to render pages                                                                               | Applications with strong interactivity and low SEO requirements                    |
+| **SSR**           | Pre-renders complete HTML pages on the server                                                                                    | Websites with high requirements for first-screen performance and SEO               |
+| **Streaming SSR** | Renders and returns progressively, displaying initial UI faster                                                                  | Applications requiring faster first-screen perception speed (**Default SSR mode**) |
+| **RSC**           | Components render on the server, reducing client JS size; high cohesion between data and component logic, reducing state passing | Projects pursuing optimal performance and needing to reduce client-side code       |
+| **SSG**           | Generates static pages at build time, can be cached by CDN                                                                       | Websites with relatively static content, such as blogs and documentation sites     |
 
 ## Performance Comparison
 
-| Rendering Technology | Core Advantages | Main Bottlenecks |
-|---------------------|-----------------|------------------|
-| **SSR** | Server-side pre-rendering, beneficial for SEO | Must wait for all data to load before responding |
-| **Streaming SSR** | Renders and returns progressively, faster first screen | JS bundle size is still large |
-| **Streaming SSR + RSC** | Reduces client JS size | - |
+| Rendering Technology    | Core Advantages                                        | Main Bottlenecks                                 |
+| ----------------------- | ------------------------------------------------------ | ------------------------------------------------ |
+| **SSR**                 | Server-side pre-rendering, beneficial for SEO          | Must wait for all data to load before responding |
+| **Streaming SSR**       | Renders and returns progressively, faster first screen | JS bundle size is still large                    |
+| **Streaming SSR + RSC** | Reduces client JS size                                 | -                                                |
 
 ## How to Choose
 

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

@@ -239,12 +239,12 @@ In RSC projects, you have two ways to fetch data: directly in Server Components,
 
 ### Comparison of Two Data Fetching Approaches
 
-| Feature | Fetching in Server Component | Fetching in Data Loader |
-| --- | --- | --- |
-| Avoid Request Waterfall | Requires manual optimization | ✅ Automatically parallel execution |
-| Component Cohesion | ✅ Data and UI in the same place | Data logic separated into separate files |
-| Maintainability | ✅ Easier to understand and maintain | Requires maintaining additional files |
-| Type Safety | ✅ Natural type inference | Requires manual type management |
+| Feature                 | Fetching in Server Component         | Fetching in Data Loader                  |
+| ----------------------- | ------------------------------------ | ---------------------------------------- |
+| Avoid Request Waterfall | Requires manual optimization         | ✅ Automatically parallel execution      |
+| Component Cohesion      | ✅ Data and UI in the same place     | Data logic separated into separate files |
+| Maintainability         | ✅ Easier to understand and maintain | Requires maintaining additional files    |
+| Type Safety             | ✅ Natural type inference            | Requires manual type management          |
 
 **Generally, we recommend fetching data in Server Components**, because waterfall requests have less performance impact on the server, and this approach makes components more cohesive, with data fetching logic and UI rendering in the same place, making it easier to understand and maintain. However, if your page has multiple independent data sources and you want to completely avoid request waterfall issues, Data Loader's parallel execution feature will be more advantageous.
 
@@ -268,7 +268,11 @@ In Modern.js RSC projects, Server Components can receive data returned by Data L
 
 ```tsx title="routes/user/page.tsx"
 // Server Component receives loaderData through props
-export default function UserPage({ loaderData }: { loaderData: { name: string } }) {
+export default function UserPage({
+  loaderData,
+}: {
+  loaderData: { name: string };
+}) {
   return <div>Welcome, {loaderData.name}</div>;
 }
 ```
@@ -276,7 +280,11 @@ export default function UserPage({ loaderData }: { loaderData: { name: string }
 ```tsx title="routes/user/page.tsx"
 'use client';
 // Client Component can also receive loaderData through props
-export default function UserPage({ loaderData }: { loaderData: { name: string } }) {
+export default function UserPage({
+  loaderData,
+}: {
+  loaderData: { name: string };
+}) {
   return <div>Welcome, {loaderData.name}</div>;
 }
 ```
@@ -515,7 +523,6 @@ When using React 19, you no longer need to use Helmet. We recommend directly usi
 
 import DeployTip from '@site-docs/components/rsc-deploy-tip';
 
-
 <DeployTip />
 
 ## Common Issues

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

@@ -193,9 +193,9 @@ When rendering cache is enabled, Modern.js identifies the cache status of the cu
 
 The `x-render-cache` header can have the following values:
 
-| Name    | Description                                      |
-| ------- | ------------------------------------------------ |
-| hit     | Cache hit, returned cache content                |
+| Name    | Description                                                                         |
+| ------- | ----------------------------------------------------------------------------------- |
+| hit     | Cache hit, returned cache content                                                   |
 | stale   | Cache hit, but data is stale, returned cache content and re-rendered asynchronously |
-| expired | Cache expired, re-rendered and returned new content |
-| miss    | Cache missed                                     |
+| expired | Cache expired, re-rendered and returned new content                                 |
+| miss    | Cache missed                                                                        |

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

@@ -90,7 +90,7 @@ export async function loader({ params }) {
   const data = await res.json();
   return {
     message: data.message,
-  }
+  };
 }
 ```
 
@@ -125,11 +125,7 @@ const Page = () => {
   const undefinedVars = data.unDefined;
   const definedVars = data.defined;
 
-  return (
-    <div>
-      {isNode ? undefinedVars.msg : definedVars.msg}
-    </div>
-  );
+  return <div>{isNode ? undefinedVars.msg : definedVars.msg}</div>;
 };
 
 export default Page;
@@ -214,7 +210,7 @@ document.addEventListener('load', () => {
   console.log('document load');
 });
 
-export const doSomething = () => {}
+export const doSomething = () => {};
 ```
 
 Directly referencing this in a component will cause SSR to throw errors, even if you use environment variables to conditionally load the code. The side effects in the dependency will still execute.
@@ -226,8 +222,8 @@ export const Page = () => {
   if (process.env.MODERN_TARGET === 'browser') {
     doSomething();
   }
-  return <div>Hello World</div>
-}
+  return <div>Hello World</div>;
+};
 ```
 
 Modern.js supports distinguishing between SSR and CSR bundles by using `.server.` suffix files. You can create `.ts` and `.server.ts` files with the same name to create a proxy:
@@ -243,12 +239,12 @@ export const doSomething: any = () => {};
 Import `./a` in the file, and the SSR bundle will prioritize the `.server.ts` files, while the CSR bundle will prioritize the `.ts` files.
 
 ```tsx title="routes/page.tsx"
-import { doSomething } from './a'
+import { doSomething } from './a';
 
 export const Page = () => {
   doSomething();
-  return <div>Hello World</div>
-}
+  return <div>Hello World</div>;
+};
 ```
 
 ## Common Issues

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

@@ -245,7 +245,8 @@ 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';
+  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));