@modern-js/main-doc 3.9.2 → 3.10.0

package/docs/en/apis/app/hooks/api/lambda.mdx

@@ -2,7 +2,8 @@
 title: lambda/*.ts
 sidebar_position: 3
 ---
-# lambda/*.ts
+
+# lambda/\*.ts
 
 After enabling BFF, the files under the `lambda/` directory will be registered as BFF routes according to conventions.
 

package/docs/en/apis/app/hooks/config/html.mdx

@@ -2,6 +2,7 @@
 title: html/
 sidebar_position: 1
 ---
+
 # html/
 
 You can inject custom HTML fragments at different locations of the default internal HTML template through the `config/html` directory.

package/docs/en/apis/app/hooks/config/mock.mdx

@@ -2,6 +2,7 @@
 title: mock/
 sidebar_position: 5
 ---
+
 # mock/
 
 When there is a `config/mock/index.ts` or `config/mock/index.js` file in the

package/docs/en/apis/app/hooks/config/public.mdx

@@ -2,6 +2,7 @@
 title: public/
 sidebar_position: 3
 ---
+
 # public/
 
 Any static assets can be placed in the `public/` directory, and the files will be deployed to the corresponding application domain by the server.

package/docs/en/apis/app/hooks/config/upload.mdx

@@ -2,6 +2,7 @@
 title: upload/
 sidebar_position: 4
 ---
+
 # upload/
 
 Any static assets can be placed in the `upload/` directory.
@@ -30,9 +31,7 @@ In React components, you can add this prefix through [Environment Variables](/gu
 
 ```tsx
 export default () => {
-  return (
-    <img src={`${process.env.ASSET_PREFIX}/upload/banner.png`}></img>
-  );
+  return <img src={`${process.env.ASSET_PREFIX}/upload/banner.png`}></img>;
 };
 ```
 

package/docs/en/apis/app/hooks/modern-config.mdx

@@ -2,6 +2,7 @@
 title: modern.config.ts
 sidebar_position: 8
 ---
+
 # modern.config.ts
 
 The Modern.js configuration file. Through this file, you can personalize the configuration of various aspects of the current project.

package/docs/en/apis/app/hooks/shared.mdx

@@ -2,6 +2,7 @@
 title: shared/
 sidebar_position: 5
 ---
+
 # shared/
 
 Shared source code directory. When there is common code in `api/`, `server/`, and `src/` in the project, you can put these codes in the `shared` directory instead of directly referencing them.

package/docs/en/apis/app/hooks/src/modern.runtime.mdx

@@ -2,6 +2,7 @@
 title: modern.runtime.ts
 sidebar_position: 4
 ---
+
 # modern.runtime.ts
 
 The Modern.js Runtime configuration file allows for personalized configuration of the Runtime capabilities for the current project.

package/docs/en/apis/app/hooks/src/routes.mdx

@@ -2,6 +2,7 @@
 title: routes/
 sidebar_position: 2
 ---
+
 # routes/
 
 The identifier for the entry point when the application uses [Conventional Routing](/guides/basic-features/routes/routes#conventional-routing).

package/docs/en/apis/app/hooks/src/server.mdx

@@ -2,6 +2,7 @@
 title: '*.[server|node].tsx'
 sidebar_position: 8
 ---
-# *.[server|node].tsx
+
+# \*.[server|node].tsx
 
 Used in the application project to place server-side code. When `*.tsx` and `*.[server|node].tsx` coexist, SSR will prefer to use the `*.[server|node].tsx` file instead of the `*.tsx` file when rendering on the server.

package/docs/en/apis/app/runtime/bff/use-hono-context.mdx

@@ -1,6 +1,7 @@
 ---
 title: useHonoContext
 ---
+
 # useHonoContext
 
 Used to obtain Hono context in an integrated BFF function.

package/docs/en/apis/app/runtime/core/create-root.mdx

@@ -1,6 +1,7 @@
 ---
 title: createRoot
 ---
+
 # createRoot
 
 It is used to create the root component provided by Modern.js, which will automatically register Runtime plugins and complete the initialization of Runtime plugins.
@@ -14,7 +15,9 @@ import { createRoot } from '@modern-js/runtime/react';
 ## Function Signature
 
 ```ts
-export function createRoot(UserApp?: React.ComponentType | null): React.ComponentType<any>;
+export function createRoot(
+  UserApp?: React.ComponentType | null,
+): React.ComponentType<any>;
 ```
 
 ### Parameters

package/docs/en/apis/app/runtime/core/render.mdx

@@ -1,6 +1,7 @@
 ---
 title: render
 ---
+
 # render
 
 It is used to render project components.
@@ -16,7 +17,10 @@ render(<ModernRoot />);
 ## Function Signature
 
 ```ts
-export function render(App: React.ReactElement, id?: HTMLElement | string): Promise<any>;
+export function render(
+  App: React.ReactElement,
+  id?: HTMLElement | string,
+): Promise<any>;
 ```
 
 ### Parameters
@@ -33,7 +37,7 @@ import { render } from '@modern-js/runtime/browser';
 const ModernRoot = createRoot();
 
 async function beforeRender() {
-   // todo
+  // todo
 }
 
 beforeRender().then(() => {

package/docs/en/apis/app/runtime/core/runtime-context.mdx

@@ -1,6 +1,7 @@
 ---
 title: RuntimeContext
 ---
+
 # RuntimeContext
 
 `RuntimeContext` is a React Context used to get Runtime context information in components. This Context can be accessed through React's `use` or `useContext` API.
@@ -19,7 +20,7 @@ import { RuntimeContext } from '@modern-js/runtime';
 
 export function App() {
   const runtimeContext = use(RuntimeContext); // You can also use useContext(RuntimeContext)
-  return <div>Hello World</div>
+  return <div>Hello World</div>;
 }
 ```
 
@@ -53,21 +54,21 @@ type TRuntimeContext = {
 ```ts
 type RequestContext = {
   request: {
-    params: Record<string, string>;      // Route parameters
-    pathname: string;                     // Pathname
-    query: Record<string, string>;        // Query parameters
-    headers: IncomingHttpHeaders;         // Request headers
-    host: string;                         // Hostname
-    url: string;                          // Full URL
-    referer?: string;                     // Referrer page
-    userAgent?: string;                   // User agent
-    cookie?: string;                      // Cookie string
-    cookieMap?: Record<string, string>;   // Cookie map object
+    params: Record<string, string>; // Route parameters
+    pathname: string; // Pathname
+    query: Record<string, string>; // Query parameters
+    headers: IncomingHttpHeaders; // Request headers
+    host: string; // Hostname
+    url: string; // Full URL
+    referer?: string; // Referrer page
+    userAgent?: string; // User agent
+    cookie?: string; // Cookie string
+    cookieMap?: Record<string, string>; // Cookie map object
   };
   response: {
-    setHeader: (key: string, value: string) => void;  // Set response header (server-side only)
-    status: (code: number) => void;                   // Set status code (server-side only)
-    locals: Record<string, any>;                      // Local data
+    setHeader: (key: string, value: string) => void; // Set response header (server-side only)
+    status: (code: number) => void; // Set status code (server-side only)
+    locals: Record<string, any>; // Local data
   };
 };
 ```
@@ -91,11 +92,11 @@ function App() {
 
   if (isBrowser === true) {
     // Browser-side execution logic
-    console.log('browser render')
+    console.log('browser render');
   } else {
     // Server-side execution logic
     // Note: Functions like logger need to be injected into context through Runtime plugins
-    console.log('server render')
+    console.log('server render');
   }
 }
 ```
@@ -157,4 +158,3 @@ export default function MyComponent() {
   return <div>{message}</div>;
 }
 ```
-

package/docs/en/apis/app/runtime/router/router.mdx

@@ -136,8 +136,10 @@ export default ErrorBoundary;
 ```ts
 declare function Link(props: LinkProps): React.ReactElement;
 
-interface LinkProps
-  extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
+interface LinkProps extends Omit<
+  React.AnchorHTMLAttributes<HTMLAnchorElement>,
+  'href'
+> {
   replace?: boolean;
   state?: any;
   to: To;
@@ -158,12 +160,13 @@ A `<Link>` is an element that lets the user navigate to another page by clicking
 ```ts
 declare function NavLink(props: NavLinkProps): React.ReactElement;
 
-interface NavLinkProps
-  extends Omit<LinkProps, 'className' | 'style' | 'children'> {
+interface NavLinkProps extends Omit<
+  LinkProps,
+  'className' | 'style' | 'children'
+> {
   caseSensitive?: boolean;
   children?:
-    | React.ReactNode
-    | ((props: { isActive: boolean }) => React.ReactNode);
+    React.ReactNode | ((props: { isActive: boolean }) => React.ReactNode);
   className?: string | ((props: { isActive: boolean }) => string | undefined);
   end?: boolean;
   style?:

package/docs/en/apis/app/runtime/ssr/no-ssr.mdx

@@ -1,6 +1,7 @@
 ---
 title: NoSSR
 ---
+
 # NoSSR
 
 The content wrapped by NoSSR will not be rendered at the server, nor will it be rendered during the client side hydrate. it will only be rendered immediately after the entire app is rendered.

package/docs/en/apis/app/runtime/utility/head.mdx

@@ -1,6 +1,7 @@
 ---
 title: Head
 ---
+
 # Head
 
 Used to add html elements (such as title, meta, script, etc.) to the `<head>` element, supports SSR.

package/docs/en/apis/app/runtime/utility/loadable.mdx

@@ -1,6 +1,7 @@
 ---
 title: loadable
 ---
+
 # loadable
 
 Used to create Loadable component

package/docs/en/community/blog/v3-release-note.mdx

@@ -2,7 +2,6 @@
 title: Modern.js v3 Release
 ---
 
-
 # Modern.js v3 Release: Focused on web framework, embracing ecosystem development
 
 > Published on 2025.02.06
@@ -45,10 +44,10 @@ Modern.js 3.0 integrates React Server Component, supporting both CSR and SSR pro
 
 React Server Components (RSC) are a new type of component that allows **component logic to execute entirely on the server**, streaming the rendered UI directly to the client. Compared to traditional client components, Server Components offer the following benefits:
 
-| Feature | Description |
-| --- | --- |
-| Zero Client Bundle Size | Component code is not included in the client JS bundle — it only executes on the server, speeding up initial page load and rendering |
-| Higher Cohesion | Components can directly access databases, call internal APIs, and read local files, improving development efficiency |
+| Feature                 | Description                                                                                                                                                                   |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Zero Client Bundle Size | Component code is not included in the client JS bundle — it only executes on the server, speeding up initial page load and rendering                                          |
+| Higher Cohesion         | Components can directly access databases, call internal APIs, and read local files, improving development efficiency                                                          |
 | Progressive Enhancement | Can be seamlessly mixed with client components, selectively offloading interactive logic to the client while maintaining high performance and supporting complex interactions |
 
 It's important to clarify that RSC and SSR are **fundamentally different concepts**:
@@ -68,7 +67,7 @@ In Modern.js 3.0, simply enable RSC in the configuration:
 export default defineConfig({
   server: {
     rsc: true,
-  }
+  },
 });
 ```
 
@@ -76,7 +75,14 @@ export default defineConfig({
 Once enabled, all route components will default to Server Components. Some components in your project may not be able to run on the server — you can add the `'use client'` directive to those components to preserve their original behavior, and then migrate gradually.
 :::
 
-<video src="https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/rsc.mp4" controls autoplay loop muted style={{ width: '100%', borderRadius: 8 }} />
+<video
+  src="https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/rsc.mp4"
+  controls
+  autoplay
+  loop
+  muted
+  style={{ width: '100%', borderRadius: 8 }}
+/>
 
 #### RSC Features in Modern.js 3.0
 
@@ -157,7 +163,7 @@ import('./module').then(({ value }) => {
 });
 
 // Destructuring in function body
-import('./module').then((mod) => {
+import('./module').then(mod => {
   const { value } = mod;
   console.log(value);
 });
@@ -237,7 +243,10 @@ In practice, we found that some projects need to extend the Web Server — for e
 In Modern.js 3.0, we rebuilt the Web Server using [Hono](https://hono.dev) and officially opened up server middleware and plugin capabilities. Developers can use Hono middleware to meet their needs:
 
 ```ts title="server/modern.server.ts"
-import { defineServerConfig, type MiddlewareHandler } from "@modern-js/server-runtime";
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
 
 const timingMiddleware: MiddlewareHandler = async (c, next) => {
   const start = Date.now();
@@ -250,8 +259,8 @@ const htmlMiddleware: MiddlewareHandler = async (c, next) => {
   await next();
   const html = await c.res.text();
   const modified = html.replace(
-    "<head>",
-    '<head><meta name="generator" content="Modern.js">'
+    '<head>',
+    '<head><meta name="generator" content="Modern.js">',
   );
   c.res = c.body(modified, { status: c.res.status, headers: c.res.headers });
 };
@@ -322,13 +331,13 @@ In Modern.js, we recommend using convention-based routing to organize code. Howe
 Therefore, Modern.js 3.0 provides full config-based routing support, which can be used alongside convention-based routing or independently.
 
 ```ts title="src/modern.routes.ts"
-import { defineRoutes } from "@modern-js/runtime/config-routes";
+import { defineRoutes } from '@modern-js/runtime/config-routes';
 
 export default defineRoutes(({ route, layout, page }) => {
   return [
-    route("home.tsx", "/"),
-    route("about.tsx", "about"),
-    route("blog.tsx", "blog/:id"),
+    route('home.tsx', '/'),
+    route('about.tsx', 'about'),
+    route('blog.tsx', 'blog/:id'),
   ];
 });
 ```
@@ -414,19 +423,19 @@ For render cache usage, see the docs: [Render Cache](/guides/basic-features/rend
 The new version provides a `cache` function that offers finer-grained data-level control compared to render cache. When multiple data requests depend on the same data, `cache` can avoid duplicate requests:
 
 ```ts title="server/loader.ts"
-import { cache } from "@modern-js/runtime/cache";
-import { fetchUserData, fetchUserProjects, fetchUserTeam } from "./api";
+import { cache } from '@modern-js/runtime/cache';
+import { fetchUserData, fetchUserProjects, fetchUserTeam } from './api';
 
 // Cache user data to avoid duplicate requests
 const getUser = cache(fetchUserData);
 
 const getProjects = async () => {
-  const user = await getUser("test-user");
+  const user = await getUser('test-user');
   return fetchUserProjects(user.id);
 };
 
 const getTeam = async () => {
-  const user = await getUser("test-user"); // Reuses cache, no duplicate request
+  const user = await getUser('test-user'); // Reuses cache, no duplicate request
   return fetchUserTeam(user.id);
 };
 
@@ -445,14 +454,14 @@ For more on data cache usage, see the docs: [Data Cache](/guides/basic-features/
 
 Through practice, we have developed multi-dimensional fallback strategies:
 
-| Type | Trigger | Fallback Behavior | Use Case |
-| --- | --- | --- | --- |
-| Error Fallback | Data Loader execution error | Triggers ErrorBoundary | Data request error handling |
-| Render Error | Server-side rendering error | Falls back to CSR, reusing existing data for rendering | SSR error handling |
-| Business Fallback | Loader throws `throw Response` | Triggers ErrorBoundary with corresponding HTTP status code | 404, permission checks, and other business scenarios |
-| Client Loader | Configure Client Loader | Bypasses SSR, requests data source directly | Scenarios requiring client-side data fetching |
-| Forced Fallback | Query parameter `?__csr=true` | Skips SSR, returns CSR page | Debugging, temporary fallback |
-| Forced Fallback | Request header `x-modern-ssr-fallback` | Skips SSR, returns CSR page | Gateway-level fallback control |
+| Type              | Trigger                                | Fallback Behavior                                          | Use Case                                             |
+| ----------------- | -------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------- |
+| Error Fallback    | Data Loader execution error            | Triggers ErrorBoundary                                     | Data request error handling                          |
+| Render Error      | Server-side rendering error            | Falls back to CSR, reusing existing data for rendering     | SSR error handling                                   |
+| Business Fallback | Loader throws `throw Response`         | Triggers ErrorBoundary with corresponding HTTP status code | 404, permission checks, and other business scenarios |
+| Client Loader     | Configure Client Loader                | Bypasses SSR, requests data source directly                | Scenarios requiring client-side data fetching        |
+| Forced Fallback   | Query parameter `?__csr=true`          | Skips SSR, returns CSR page                                | Debugging, temporary fallback                        |
+| Forced Fallback   | Request header `x-modern-ssr-fallback` | Skips SSR, returns CSR page                                | Gateway-level fallback control                       |
 
 ---
 

package/docs/en/community/contributing-guide.mdx

@@ -36,13 +36,6 @@ nvm alias default 22
 nvm use 22
 ```
 
-### Install pnpm
-
-```sh
-# Enable pnpm with corepack, only available on Node.js >= `v14.19.0`
-corepack enable
-```
-
 ### Install Dependencies
 
 ```sh
@@ -57,28 +50,6 @@ What this will do:
 
 > A full rebuild of all packages is generally not required after this. If a new feature you are developing requires an updated version of another package, it is usually sufficient to build the changed dependencies.
 
-### Set Git Email
-
-Please make sure you have your email set up in `<https://github.com/settings/emails>`. This will be needed later when you want to submit a pull request.
-
-Check that your git client is already configured the email:
-
-```sh
-git config --list | grep email
-```
-
-Set the email to global config:
-
-```sh
-git config --global user.email "SOME_EMAIL@example.com"
-```
-
-Set the email for local repo:
-
-```sh
-git config user.email "SOME_EMAIL@example.com"
-```
-
 ## Making Changes and Building
 
 Once you have set up the local development environment in your forked repo, we can start development.
@@ -132,7 +103,7 @@ Modern.js uses [Rstest](https://rstest.rs/) for unit tests across the repository
 Before submitting a pull request, it's important to make sure that the changes haven't introduced any regressions or bugs. You can run the unit tests for the project by executing the following command:
 
 ```sh
-pnpm run test
+pnpm run test:ut
 ```
 
 Alternatively, you can run the unit tests of single package using the `--filter` option:
@@ -145,10 +116,11 @@ pnpm run --filter @modern-js/some-package test
 
 In addition to the unit tests, the Modern.js also includes end-to-end (E2E) tests, which checks the functionality of the application as a whole.
 
-You can run the `test:e2e` command to run the E2E tests:
+Run the framework integration tests and Builder E2E tests with the following commands:
 
 ```sh
-pnpm run test:e2e
+pnpm run test:framework
+pnpm run test:builder
 ```
 
 If you need to run a specified test, you can add keywords to filter:
@@ -160,7 +132,7 @@ npx rstest copy-assets
 
 ## Linting
 
-To help maintain consistency and readability of the codebase, we use a ESLint to lint the codes.
+To help maintain consistency and readability across the codebase, we use [Rstack CLI](https://rstack.rs/) for linting and formatting.
 
 You can run the Linter by executing the following command:
 
@@ -168,6 +140,14 @@ You can run the Linter by executing the following command:
 pnpm run lint
 ```
 
+Run the formatter from the repository root:
+
+```sh
+pnpm run format
+```
+
+Append a file or directory path to either command to limit its scope.
+
 ## Benchmarking
 
 You can input `!bench-framework` or `!bench-module` in the comment area of ​​the PR to do benchmarking on `@modern-js/app-tools` and `@modern-js/module-tools` respectively (you need to have Collaborator and above permissions).
@@ -249,6 +229,8 @@ pnpm run prepare
 pnpm run bump
 ```
 
+After Changesets updates the package versions, this command synchronizes internal `peerDependencies` ranges to `workspace:^<dependency version>` to satisfy the changeset validation.
+
 5. Commit the version change.
 
 ```sh

package/docs/en/components/default-browserslist.mdx

@@ -1,4 +1,3 @@
-
 ```yaml title=".browserslistrc"
 chrome >= 87
 edge >= 88

package/docs/en/components/deploy-command.mdx

@@ -11,4 +11,4 @@ Options:
   -h, --help            Display command help
 ```
 
-For more details, refer to [Deploy Application](/guides/basic-features/deploy).
+For more details, refer to [Deploy Application](/guides/basic-features/deploy).

package/docs/en/components/deploy.mdx

@@ -1 +1 @@
-After local develop, you can refer to the [Deployment](/guides/basic-features/deploy.html) section to deploy the project to the server.
+After local develop, you can refer to the [Deployment](/guides/basic-features/deploy.html) section to deploy the project to the server.

package/docs/en/components/entry-scan-logic.mdx

@@ -1,7 +1,7 @@
 :::tip Entry scanning logic
+
 - If `src/` itself meets entry criteria → Single-entry application
 - If `src/` does not meet criteria → Scan subdirectories under `src/` → Multi-entry application
 - In single-entry applications, the default entry name is `index`
 
 :::
-

package/docs/en/components/init-app.mdx

@@ -38,19 +38,18 @@ npx @modern-js/create@latest myapp
 
 ⚡ Start the development server:
 
-  pnpm start
+  pnpm dev
 ```
 
 Now, the project structure is as follows:
 
 ```
 .
-├── biome.json
 ├── modern.config.ts
 ├── package.json
 ├── README.md
+├── rstack.config.mts
 ├── src
-│   ├── modern-app-env.d.ts
 │   ├── modern.runtime.ts
 │   └── routes
 │       ├── index.css
@@ -58,3 +57,10 @@ Now, the project structure is as follows:
 │       └── page.tsx
 └── tsconfig.json
 ```
+
+New standalone projects use [Rstack CLI](https://rstack.rs/) for linting and formatting:
+
+```bash
+pnpm check
+pnpm format
+```

package/docs/en/components/international/custom-instance-code.mdx

@@ -13,4 +13,3 @@ export default defineRuntimeConfig({
   },
 });
 ```
-

package/docs/en/components/micro-runtime-config.mdx

@@ -3,15 +3,18 @@ import { defineRuntimeConfig } from '@modern-js/runtime';
 
 export default defineRuntimeConfig({
   masterApp: {
-    apps: [{
-      name: 'Table',
-      entry: 'http://localhost:8081',
-      // activeWhen: '/table'
-    }, {
-      name: 'Dashboard',
-      entry: 'http://localhost:8082'
-      // activeWhen: '/dashboard'
-    }]
+    apps: [
+      {
+        name: 'Table',
+        entry: 'http://localhost:8081',
+        // activeWhen: '/table'
+      },
+      {
+        name: 'Dashboard',
+        entry: 'http://localhost:8082',
+        // activeWhen: '/dashboard'
+      },
+    ],
   },
 });
 ```

package/docs/en/components/nodeVersion.mdx

@@ -1,4 +1,4 @@
-Before getting started, you will need to install [Node.js](https://nodejs.org/), and ensure that your Node.js version is not lower than v20.19.5. **We recommend using the LTS version of Node.js 22.**
+Before getting started, you will need to install [Node.js](https://nodejs.org/), and ensure that your Node.js version is not lower than v22.18.0. **We recommend using the LTS version of Node.js 22.**
 
 You can check the currently used Node.js version with the following command:
 
@@ -6,7 +6,7 @@ You can check the currently used Node.js version with the following command:
 node -v
 ```
 
-If you do not have Node.js installed in your current environment, or the installed version is lower than v20.19.5, you can use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to install the required version.
+If you do not have Node.js installed in your current environment, or the installed version does not meet this requirement, you can use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to install the required version.
 
 Here is an example of how to install the Node.js 22 LTS version via nvm:
 

package/docs/en/components/rsc-deploy-tip.mdx

@@ -1 +0,0 @@
-

package/docs/en/components/ssr-monitor.mdx

@@ -1,3 +1,3 @@
 :::tip
 SSR monitoring has been integrated into the Monitors module, see [Monitors](/guides/advanced-features/server-monitor/monitors) for details.
-:::
+:::