@modern-js/main-doc 3.9.2 → 3.10.0

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

@@ -6,7 +6,6 @@ sidebar_position: 3
 
 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:
@@ -22,27 +21,26 @@ Config routes are particularly useful in the following scenarios:
 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'
+import { defineRoutes } from '@modern-js/runtime/config-routes';
 
 export default defineRoutes(({ route, layout, page, $ }, fileRoutes) => {
-  return [
-    route("home.tsx", "/"),
-  ]
-})
+  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:
@@ -50,6 +48,7 @@ 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
@@ -72,27 +71,28 @@ The `route` function is a general-purpose route configuration function that auto
 export default defineRoutes(({ route }, fileRoutes) => {
   return [
     // When no child routes, automatically generates page route
-    route("home.tsx", "/"),
-    route("about.tsx", "about"),
+    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
+    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"),
+    route('products/detail.tsx', 'products/:id'),
 
     // Multiple paths pointing to the same component
-    route("user/profile.tsx", "user"),
-    route("user/profile.tsx", "profile"),
-  ]
-})
+    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
 
@@ -104,15 +104,16 @@ The `layout` function is specifically used to configure layout routes, always ge
 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
+    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
@@ -124,15 +125,16 @@ The `page` function is specifically used to configure page routes, always genera
 ```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
+    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
@@ -144,16 +146,17 @@ The `$` function is specifically used to configure wildcard routes for handling
 ```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
+    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
 
@@ -161,7 +164,6 @@ export default defineRoutes(({ layout, page, $ }, fileRoutes) => {
 The `$` function has the same functionality as the `$.tsx` file in convention routes, used to catch unmatched route requests.
 :::
 
-
 ## Configuring Routes
 
 ### Basic Example
@@ -170,11 +172,11 @@ The `$` function has the same functionality as the `$.tsx` file in convention ro
 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"),
-  ]
-})
+    page('home.tsx', '/'),
+    page('about.tsx', 'about'),
+    page('contact.tsx', 'contact'),
+  ];
+});
 ```
 
 ### Routes Without Path
@@ -186,15 +188,16 @@ 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"),
+    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`
 
@@ -203,14 +206,13 @@ The above configuration will generate:
 ```ts
 export default defineRoutes(({ page }, fileRoutes) => {
   return [
-    page("user.tsx", "user"),
-    page("user.tsx", "profile"),
-    page("user.tsx", "account"),
-  ]
-})
+    page('user.tsx', 'user'),
+    page('user.tsx', 'profile'),
+    page('user.tsx', 'account'),
+  ];
+});
 ```
 
-
 ### Dynamic Routes
 
 Config routes support dynamic route parameters:
@@ -219,15 +221,14 @@ Config routes support dynamic route parameters:
 export default defineRoutes(({ page }, fileRoutes) => {
   return [
     // Required parameter
-    page("blog/detail.tsx", "blog/:id"),
+    page('blog/detail.tsx', 'blog/:id'),
 
     // Optional parameter
-    page("blog/index.tsx", "blog/:slug?"),
-  ]
-})
+    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:
@@ -236,10 +237,10 @@ Config routes automatically discover component-related files without manual conf
 // modern.routes.ts
 export default defineRoutes(({ route }, fileRoutes) => {
   return [
-    route("pages/profile.tsx", "profile"),
-    route("pages/user/detail.tsx", "user/:id"),
-  ]
-})
+    route('pages/profile.tsx', 'profile'),
+    route('pages/user/detail.tsx', 'user/:id'),
+  ];
+});
 ```
 
 Modern.js will automatically find and load:

package/docs/en/guides/basic-features/static-assets/svg-assets.mdx

@@ -42,16 +42,22 @@ export default () => <Logo />;
 
 ## Modify the Default Export
 
-You can modify the default export of SVG files through the [output.svgDefaultExport](/configure/app/output/svg-default-export) config. For example, set the default export as a React component:
+You can modify the default export of SVG files through `svgrOptions.exportType` of [tools.svgr](/configure/app/tools/svgr). For example, set the default export as a React component:
 
 ```ts
 export default {
-  output: {
-    svgDefaultExport: 'component',
+  tools: {
+    svgr: {
+      svgrOptions: {
+        exportType: 'default',
+      },
+    },
   },
 };
 ```
 
+The legacy [output.svgDefaultExport](/configure/app/output/svg-default-export) config still works but is deprecated.
+
 Then import the SVG, you'll get a React component instead of a URL:
 
 ```tsx title="src/component/Logo.tsx"
@@ -78,12 +84,12 @@ Please read the [Import Static Assets](/guides/basic-features/static-assets) sec
 
 ## Disable SVGR Processing
 
-By default, when an SVG resource is referenced in a JS file, Modern.js will call SVGR to convert the SVG into a React component. If you are sure that all SVG resources in your project are not being used as React components, you can turn off this conversion by setting [disableSvgr](/configure/app/output/disable-svgr) to true to improve build performance.
+By default, when an SVG resource is referenced in a JS file, Modern.js will call SVGR to convert the SVG into a React component. If you are sure that all SVG resources in your project are not being used as React components, you can turn off this conversion by setting [tools.svgr](/configure/app/tools/svgr) to `false` to improve build performance.
 
 ```js
 export default {
-  output: {
-    disableSvgr: true,
+  tools: {
+    svgr: false,
   },
 };
 ```
@@ -151,21 +157,27 @@ When SVGR is enabled, its default configuration is as follows:
 }
 ```
 
-If you need to modify the SVGR configuration, you can do the following:
+To modify the SVGR configuration, use `svgrOptions` of [tools.svgr](/configure/app/tools/svgr). The `svgoConfig.plugins` you pass are deep merged with the defaults by plugin name, so only the changed part needs to be written:
 
 ```js
 export default {
   tools: {
-    bundlerChain: (chain, { CHAIN_ID }) => {
-      chain.module
-        .rule(CHAIN_ID.RULE.SVG)
-        .oneOf(CHAIN_ID.ONE_OF.SVG)
-        .use(CHAIN_ID.USE.SVGR)
-        .tap(options => {
-          // modify svgoConfig
-          options.svgoConfig.plugins[0].params.overrides.removeUselessDefs = false;
-          return options;
-        });
+    svgr: {
+      svgrOptions: {
+        svgoConfig: {
+          plugins: [
+            {
+              name: 'preset-default',
+              params: {
+                overrides: {
+                  // add one more override on top of the default preset-default
+                  removeUselessDefs: false,
+                },
+              },
+            },
+          ],
+        },
+      },
     },
   },
 };

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

@@ -6,7 +6,13 @@ To use Playwright in Modern.js, you need to install the dependencies first. You
 
 import { PackageManagerTabs } from '@theme';
 
-<PackageManagerTabs command={{ npm: "npm init playwright", yarn: "yarn create playwright", pnpm: "pnpm create playwright" }} />
+<PackageManagerTabs
+  command={{
+    npm: 'npm init playwright',
+    yarn: 'yarn create playwright',
+    pnpm: 'pnpm create playwright',
+  }}
+/>
 
 The above commands will automatically install Playwright dependencies and help you install and configure it in your project through a series of prompts, including adding a `playwright.config.ts` file.
 
@@ -74,18 +80,18 @@ export default Index;
 Next, add test cases to ensure the links on your pages work properly.
 
 ```ts title="tests/example.spec.ts"
-import { test, expect } from '@playwright/test'
+import { test, expect } from '@playwright/test';
 
 test('should navigate to the about page', async ({ page }) => {
   // Start from the index page (the baseURL is set via the webServer in the playwright.config.ts)
-  await page.goto('http://localhost:8080/')
+  await page.goto('http://localhost:8080/');
   // Find an element with the text 'About' and click on it
-  await page.click('text=About')
+  await page.click('text=About');
   // The new URL should be "/about" (baseURL is used there)
-  await expect(page).toHaveURL('http://localhost:8080/about')
+  await expect(page).toHaveURL('http://localhost:8080/about');
   // The new page should contain an h1 with "About"
-  await expect(page.locator('h1')).toContainText('About')
-})
+  await expect(page.locator('h1')).toContainText('About');
+});
 ```
 
 ## Run Test Cases
@@ -108,4 +114,4 @@ Running 3 tests using 3 workers
 To open last HTML report run:
 
   npx playwright show-report
-```
+```

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

@@ -84,9 +84,9 @@ test('Page', async () => {
     </Router>,
   );
 
-  await expect.element(
-    page.getByRole('heading', { level: 1, name: 'Home' }),
-  ).toBeVisible();
+  await expect
+    .element(page.getByRole('heading', { level: 1, name: 'Home' }))
+    .toBeVisible();
 });
 ```
 
@@ -181,12 +181,14 @@ First install and use the migrate-to-rstest skill. If it is not installed, insta
 npx skills add rstackjs/agent-skills --skill migrate-to-rstest
 
 Follow the migrate-to-rstest skill instructions and the official Rstest migration guides:
+
 - Jest: https://rstest.rs/guide/migration/jest
 - Vitest: https://rstest.rs/guide/migration/vitest
 
 Modern.js-specific requirement:
+
 - Install and use @modern-js/adapter-rstest together with @rstest/core.
 - Create or update rstest.config.ts to import withModernConfig from @modern-js/adapter-rstest.
 - Reuse the Modern.js app configuration with extends: withModernConfig().
 - Do not replace this with a plain Rstest config unless the project explicitly does not need Modern.js config integration.`}
-/>
+  />

package/docs/en/guides/get-started/ai-coding-agents.mdx

@@ -15,10 +15,10 @@ AI agents use them to get APIs, config, and conventions that exactly match your
 
 ## AGENTS.md
 
-`AGENTS.md` gives AI coding agents project-level guidance — telling them to read the bundled docs before making changes and to follow Modern.js conventions. A `CLAUDE.md` is generated alongside it, reusing the same guidance for Claude Code via the `@AGENTS.md` import.
+`AGENTS.md` gives AI coding agents project-level guidance — telling them to read the bundled docs before making changes and to follow Modern.js conventions.
 
-- **New projects**: `npx @modern-js/create` generates both files by default; pass `--no-agents-md` to skip them.
-- **Existing projects**: run `npx @modern-js/create --agents-md-only` at the project root to create or update them. Re-run it any time; your own additions are preserved.
+- **New projects**: `npx @modern-js/create` generates `AGENTS.md` by default; pass `--no-agents-md` to skip it.
+- **Existing projects**: run `npx @modern-js/create --agents-md-only` at the project root to create or update `AGENTS.md`. Re-run it any time; your own additions are preserved.
 
 Modern.js only maintains the content inside the `<!-- BEGIN:modernjs-agent-rules -->` markers in `AGENTS.md`; anything you write outside them is left untouched.
 
@@ -35,9 +35,9 @@ Use it when you need content beyond the bundled docs — just let your agent ret
 
 Skills are on-demand AI capabilities following the [Agent Skills open standard](https://github.com/vercel-labs/skills). User-facing Skills:
 
-| Skill | Identifier | Description |
-|---|---|---|
-| Upgrade to v3 | `modernjs-migrate-to-v3` | Migrate a v2 app to v3: safe rewrites + manual checklist + migration report |
+| Skill           | Identifier                | Description                                                                                     |
+| --------------- | ------------------------- | ----------------------------------------------------------------------------------------------- |
+| Upgrade to v3   | `modernjs-migrate-to-v3`  | Migrate a v2 app to v3: safe rewrites + manual checklist + migration report                     |
 | Enable features | `modernjs-feature-enable` | Enable BFF / SSG / styled-components for v3 apps, and scaffold Tailwind CSS / custom Web Server |
 
 > Skills are not force-installed or implicitly installed — you install them explicitly. RSC and micro-frontend setups are configuration or architecture decisions, not one-click `modernjs-feature-enable` actions.

package/docs/en/guides/get-started/introduction.mdx

@@ -39,4 +39,3 @@ In addition, Modern.js provides richer server-side features, including comprehen
 ### Remix
 
 Pelease refer to [Modern.js vs Remix](https://github.com/web-infra-dev/modern.js/discussions/4872).
-

package/docs/en/guides/topic-detail/module-federation/deploy.mdx

@@ -63,9 +63,9 @@ At this point, the `publicPath` defined in the producer's build output `mf-manif
     "name": "remote",
     "publicPath": "https://my-remote-module/"
   },
-  "shared": [ /* xxx */ ],
+  "shared": [/* xxx */],
   "remotes": [],
-  "exposes": [ /* xxx */ ]
+  "exposes": [/* xxx */]
 }
 ```
 

package/docs/en/guides/topic-detail/module-federation/introduce.mdx

@@ -33,4 +33,3 @@ For more details, refer to [Using Module Federation](/guides/topic-detail/module
 Module Federation 2.0 offers the [Bridge](https://module-federation.io/practice/bridge/overview.html) capability to load application-level modules.
 
 Modern.js, based on Bridge and its internal implementation, provides APIs to easily export application-level modules. For more details, refer to [Application-Level Modules](/guides/topic-detail/module-federation/application).
-

package/docs/en/guides/upgrade/config.mdx

@@ -22,6 +22,18 @@ server: {
 }
 ```
 
+### dev.lazyCompilation
+
+**Change**: The default value in development has changed. Pure CSR and streaming SSR applications enable lazy compilation by default with `{ imports: true, entries: false }`; applications using string SSR, RSC or SSG keep it disabled by default. This only affects development and does not change production build output.
+
+**Migration Example**: To keep the 2.0 behavior, disable it explicitly:
+
+```typescript
+dev: {
+  lazyCompilation: false;
+}
+```
+
 ## html
 
 ### html.appIcon

package/docs/en/guides/upgrade/other.mdx

@@ -22,10 +22,10 @@ If your project's deployment configuration specifies a particular entry file nam
 
 Modern.js 3.0 has adjusted some runtime paths, and related import paths need to be updated. The path mapping is as follows:
 
-| Old Path | New Path | Description |
-|---------|---------|------|
-| `@modern-js/runtime/bff` | `@modern-js/plugin-bff/runtime` | BFF runtime path |
-| `@modern-js/runtime/server` | `@modern-js/server-runtime` | Server-side runtime path |
+| Old Path                    | New Path                        | Description              |
+| --------------------------- | ------------------------------- | ------------------------ |
+| `@modern-js/runtime/bff`    | `@modern-js/plugin-bff/runtime` | BFF runtime path         |
+| `@modern-js/runtime/server` | `@modern-js/server-runtime`     | Server-side runtime path |
 
 ## useRuntimeContext Deprecated
 

package/docs/en/guides/upgrade/tailwindcss.mdx

@@ -89,4 +89,3 @@ Change the CSS import method to the `@tailwind` directive approach.
 @tailwind components;
 @tailwind utilities;
 ```
-

package/docs/en/guides/upgrade/web-server.md

@@ -21,7 +21,10 @@ These two approaches are mutually exclusive in the legacy version. When migratin
 
 ```typescript
 // Legacy - server/index.ts
-export const unstableMiddleware: UnstableMiddleware[] = [middleware1, middleware2];
+export const unstableMiddleware: UnstableMiddleware[] = [
+  middleware1,
+  middleware2,
+];
 
 // New - server/modern.server.ts
 import { defineServerConfig } from '@modern-js/server-runtime';
@@ -38,13 +41,22 @@ export default defineServerConfig({
 
 ```typescript
 // Legacy
-import type { UnstableMiddleware, UnstableMiddlewareContext } from '@modern-js/server-runtime';
-const middleware: UnstableMiddleware = async (c: UnstableMiddlewareContext, next) => {
+import type {
+  UnstableMiddleware,
+  UnstableMiddlewareContext,
+} from '@modern-js/server-runtime';
+const middleware: UnstableMiddleware = async (
+  c: UnstableMiddlewareContext,
+  next,
+) => {
   return c.response.raw('response'); // Will continue rendering even without calling next
 };
 
 // New
-import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
 const middleware: MiddlewareHandler = async (c, next) => {
   await next(); // Must call
   return c.text('response');
@@ -53,17 +65,17 @@ const middleware: MiddlewareHandler = async (c, next) => {
 
 ### Context API Comparison
 
-| Legacy API               | New API                 | Description            |
-| -------------------- | ---------------------- | ------------- |
-| `c.request.cookie`   | `getCookie(c, 'key')`  | Cookie reading      |
-| `c.req.cookie()`     | `getCookie(c, 'key')`  | Hono v4 deprecated    |
-| `c.request.pathname` | `c.req.path`           | Request path          |
-| `c.request.host`     | `c.req.header('Host')` | Request host          |
-| `c.request.query`    | `c.req.query()`        | Query parameters          |
-| `c.request.headers`  | `c.req.header()`       | Request headers           |
-| `c.response.status`  | `c.status()`           | Response status code         |
-| `c.response.set`     | `c.res.headers.set`    | Set response headers         |
-| `c.response.raw`     | `c.text` / `c.json`    | Response body           |
+| Legacy API           | New API                | Description          |
+| -------------------- | ---------------------- | -------------------- |
+| `c.request.cookie`   | `getCookie(c, 'key')`  | Cookie reading       |
+| `c.req.cookie()`     | `getCookie(c, 'key')`  | Hono v4 deprecated   |
+| `c.request.pathname` | `c.req.path`           | Request path         |
+| `c.request.host`     | `c.req.header('Host')` | Request host         |
+| `c.request.query`    | `c.req.query()`        | Query parameters     |
+| `c.request.headers`  | `c.req.header()`       | Request headers      |
+| `c.response.status`  | `c.status()`           | Response status code |
+| `c.response.set`     | `c.res.headers.set`    | Set response headers |
+| `c.response.raw`     | `c.text` / `c.json`    | Response body        |
 
 ## afterRender Hook
 
@@ -88,7 +100,10 @@ export const afterRender = (ctx, next) => {
 };
 
 // New - server/modern.server.ts
-import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
 
 const renderMiddleware: MiddlewareHandler = async (c, next) => {
   await next(); // Wait for page rendering first
@@ -104,6 +119,8 @@ const renderMiddleware: MiddlewareHandler = async (c, next) => {
 };
 
 export default defineServerConfig({
-  renderMiddlewares: [{ name: 'custom-content-injection', handler: renderMiddleware }],
+  renderMiddlewares: [
+    { name: 'custom-content-injection', handler: renderMiddleware },
+  ],
 });
 ```

package/docs/en/index.md

@@ -1,4 +1,5 @@
 ---
 pageType: home
 ---
+
 # Modern.js - A Progressive React Framework for modern web development