@modern-js/main-doc 2.67.3 → 2.67.5

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

@@ -88,3 +88,73 @@ export default () => {
 `<Outlet>` is a new API in React Router 6. For details, see [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
 
 :::
+
+## Upgrading to React Router v7
+
+React Router v7 reduces bundle size (approximately 15% smaller) compared to React Router v6, provides a more efficient route matching algorithm, and offers better support for React 19 and TypeScript. There are very few breaking changes compared to React Router v6, and Modern.js has made both versions compatible, allowing for a seamless upgrade by simply installing and registering the appropriate plugin.
+
+:::info
+
+For more changes from React Router v6 to React Router v7, check the [documentation](https://reactrouter.com/upgrading/v6#upgrade-to-v7)
+
+:::
+
+### Requirements
+
+React Router v7 has certain environment requirements:
+
+- Node.js 20+
+- React 18+
+- React DOM 18+
+
+### Install the Plugin
+
+First, install the Modern.js React Router v7 plugin:
+
+```bash
+pnpm add @modern-js/plugin-router-v7
+```
+
+### Configure the Plugin
+
+Register the plugin in `modern.config.ts`:
+
+```ts title="modern.config.ts"
+import { routerPlugin } from '@modern-js/plugin-router-v7';
+
+export default {
+  runtime: {
+    router: true,
+  },
+  plugins: [routerPlugin()],
+};
+```
+
+### Code Changes
+
+In React Router v7, you no longer need to use the `defer` API; you can directly return data in the data loader:
+
+```ts title="routes/page.data.ts"
+import { defer } from '@modern-js/runtime/router';
+
+export const loader = async ({ params }) => {
+  // Recommended v7 style
+  const user = fetchUser(params.id)
+  return { user };
+
+  // v6 style, still compatible with Modern.js
+  return defer({ data: 'hello' });
+};
+```
+
+React Router v7 has also deprecated the `json` API:
+
+```ts title="routes/page.data.ts"
+export const loader = async ({ params }) => {
+  // Recommended v7 style
+  return { data: 'hello' };
+
+  // v6 style, still compatible with Modern.js
+  return json({ data: 'hello' });
+};
+```

package/docs/en/configure/app/output/filename.mdx

@@ -3,13 +3,20 @@ title: filename
 configName: output.filename
 ---
 
+:::warning
+
+In Modern.js `dev` command or use Modern.js server deployment, don't modify the html output filename. This will cause the page to be 404.
+
+In common, you don't need to modify the html filename. If you want modify `main.html` to `index.html`, using [source.mainEntryName](/configure/app/source/main-entry-name).
+
+:::
+
 # output.filename
 
 - **Type:**
 
 ```ts
 type FilenameConfig = {
-  html?: string;
   js?:
     | string
     | ((pathData: Rspack.PathData, assetInfo: Rspack.JsAssetInfo) => string);
@@ -27,7 +34,6 @@ type FilenameConfig = {
 ```js
 // Development mode
 const devDefaultFilename = {
-  html: '[name].html',
   js: '[name].js',
   css: '[name].css',
   svg: '[name].[contenthash:8].svg',
@@ -39,7 +45,6 @@ const devDefaultFilename = {
 
 // Production mode
 const prodDefaultFilename = {
-  html: '[name].html',
   js: output.target === 'node' ? '[name].js' : '[name].[contenthash:8].js',
   css: '[name].[contenthash:8].css',
   svg: '[name].[contenthash:8].svg',

package/docs/en/configure/app/plugins.mdx

@@ -1,47 +1,27 @@
----
-sidebar_position: 9
----
-
 # plugins
 
 - **Type:** `CliPlugin[]`
 - **Default:** `[]`
 
-Used to configure custom Modern.js framework plugins.
-
-Refer to [How to Develop Plugins](/plugin/plugin-system) for how to write custom plugins.
+Used to configure custom Modern.js framework CLI plugins. For information on how to create custom CLI plugins, please refer to [How to Write CLI Plugins](/plugin/introduction.html#cli-plugins).
 
 ## Note
 
-This option is used to configure framework plugins. If you need to configure other types of plugins, please choose the corresponding configuration method:
-
-- Use [builderPlugins](/configure/app/builder-plugins) to configure Rsbuild plugins.
-- Use [tools.bundlerChain](/configure/app/tools/bundler-chain) to configure Rspack or webpack plugins.
-- Use [tools.babel](/configure/app/tools/babel) to configure Babel plugins.
-
-## Plugin types
-
-Modern.js has three types of plugins:
-
-- `CLI plugins`, applicable to local development, compilation and construction stages, can extend various capabilities in the command line and compilation stages.
-- `Server plugins`, applicable to the server.
-- `Runtime plugins`, applicable to the front-end runtime.
-
-Currently, Modern.js has opened up the ability to customize CLI plugins, and Server plugins and Runtime plugins will be opened up later.
-
-## Plugin execution order
+This option is **specifically for configuring framework CLI plugins**. If you need to configure other types of plugins, use the appropriate configuration method:
 
-By default, custom plugins are executed in the order of the `plugins` array, and the execution time of built-in Modern.js plugins is earlier than that of custom plugins.
+- Use [builderPlugins](/configure/app/builder-plugins) for Rsbuild plugins.
+- Use [tools.bundlerChain](/configure/app/tools/bundler-chain) for Rspack or webpack plugins.
+- Use [tools.babel](/configure/app/tools/babel) for Babel plugins.
+- Use the [plugins field in runtime config](/configure/app/runtime/plugins) for framework Runtime plugins.
 
-When the plugin sets options that control the order, such as `pre` and `post`, the execution order will be adjusted based on the declared fields. Refer to [Plugins Structure](/plugin/plugin-system) for more information.
 
-## Example
+## Examples
 
-The following is an example of using CLI plugins.
+Below are examples of using CLI plugins:
 
-### Use plugins on npm
+### Using plugins from npm
 
-To use plugins from npm registry, you need to first install the plugins , and import them in `modern.config.ts`.
+To use plugins from the npm registry, first install the plugins and then import them in your configuration:
 
 ```ts title="modern.config.ts"
 import { myPlugin } from 'my-plugin';
@@ -51,9 +31,9 @@ export default defineConfig({
 });
 ```
 
-### Use local plugins
+### Using local plugins
 
-To use local plugins, import them directly using a relative path.
+To use plugins from your local repository, import them directly using a relative path:
 
 ```ts title="modern.config.ts"
 import { myPlugin } from './config/plugin/myPlugin';
@@ -65,7 +45,7 @@ export default defineConfig({
 
 ### Plugin configuration
 
-If the plugin provides some custom configuration options, they can be passed in as parameters to the plugin function.
+If a plugin provides custom configuration options, pass them as parameters to the plugin function:
 
 ```ts title="modern.config.ts"
 import { myPlugin } from 'my-plugin';

package/docs/en/configure/app/runtime/master-app.mdx

@@ -1,8 +1,4 @@
----
-title: masterApp
----
-
-# runtime.masterApp
+# masterApp
 
 - **Type:** `Object`
 

package/docs/en/configure/app/runtime/plugins.mdx

@@ -0,0 +1,58 @@
+# plugins
+
+- **Type:** `RuntimePlugin[]`
+- **Default:** `[]`
+
+Used to configure custom Modern.js Runtime plugins. For details on how to create custom Runtime plugins, please refer to [How to Write Runtime Plugins](/plugin/introduction#runtime-plugins).
+
+:::info
+
+Runtime plugins must be configured in the `plugins` array within the `src/modern.runtime.ts` file.
+
+:::
+
+## Examples
+
+Here are examples demonstrating how to use Runtime plugins:
+
+### Using plugins from npm packages
+
+To use plugins published on npm, first install them via your package manager, then import them into your configuration.
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import { myPlugin } from 'my-plugin';
+
+export default defineRuntimeConfig({
+  plugins: [myPlugin()],
+});
+```
+
+### Using local plugins
+
+To use plugins from your local codebase, import them directly using relative paths.
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import { myPlugin } from './config/plugin/myPlugin';
+
+export default defineRuntimeConfig({
+  plugins: [myPlugin()],
+});
+```
+
+### Plugin configuration
+
+If a plugin supports custom configuration options, you can provide them as arguments to the plugin function.
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import { myPlugin } from './config/plugin/myPlugin';
+
+export default defineRuntimeConfig({
+  plugins: [myPlugin({
+    foo: 1,
+    bar: 2,
+  })],
+});
+```

package/docs/en/configure/app/usage.mdx

@@ -13,9 +13,7 @@ Modern.js does not support configuring the same configuration item in both `pack
 
 **Runtime configuration** can be configured in the `src/modern.runtime.(ts|js|mjs)` file.
 
-{/* TODO server 配置文件更新 */}
-**Server Runtime configuration** can be configured in the `modern.server-runtime.config.(ts|js|mjs)` file in the root path.
-
+**Server Runtime configuration** can be configured in the `server/modern.server.(ts|js|mjs)` file.
 
 ## Compile Configuration
 

package/docs/en/guides/advanced-features/_meta.json

@@ -23,5 +23,6 @@
     "label": "server-monitor",
     "collapsed": true
   },
+  "custom-server",
   "web-server"
 ]

package/docs/en/guides/advanced-features/bff.mdx

@@ -6,7 +6,7 @@ title: BFF
 
 BFF (Backends for Frontends) is an architectural pattern primarily used to address issues of data aggregation in front-end and back-end collaboration. Under the BFF architecture, front-end applications do not communicate directly with backend services. Instead, they interact with backend services through a dedicated BFF middleware layer, custom-made for the front end.
 
-The main problems it to solve include:
+The main problems it tries to solve include:
 
 - Aggregation, mapping, clipping, and proxying of lower-level APIs according to their own business needs.
 - Cache data for some specific scenarios to improve performance and thus improve user experience.

package/docs/en/guides/advanced-features/compatibility.mdx

@@ -26,7 +26,7 @@ Please refer to [Rsbuild - Browserslist](https://rsbuild.dev/guide/advanced/brow
 
 ### Polyfill At Compile
 
-Modern.js defaults to importing corresponding polyfill code from [core-js] (https://github.com/zloirock/core-js) during compilation.
+Modern.js defaults to importing corresponding polyfill code from [core-js](https://github.com/zloirock/core-js) during compilation.
 
 By default, the required Polyfill code will be introduced according to the settings of the Browserslist, so there is no need to worry about the Polyfill problem of the project source code and third-party dependencies, but because it contains some Polyfill code that is not used, the final bundle size may be increased.
 

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

@@ -0,0 +1,218 @@
+---
+sidebar_position: 16
+---
+
+# Custom Server
+
+Modern.js encapsulates most server-side capabilities required by projects, typically eliminating the need for server-side development. However, in certain scenarios such as user authentication, request preprocessing, or adding page skeletons, custom server-side logic may still be necessary.
+
+## Custom Server Capabilities
+
+Create the `server/modern.server.ts` file in the project directory, and you can add the following configurations to extend the Server:
+- **Middleware**
+- **Render Middleware**
+- **Server Plugin**
+
+In the **Plugin**, you can define **Middleware** and **RenderMiddleware**. The middleware loading process is illustrated in the following diagram:
+
+<img
+  src="https://lf3-static.bytednsdoc.com/obj/eden-cn/10eh7nuhpenuhog/server-md-wf.png"
+  style={{ width: '100%', maxWidth: '540px' }}
+/>
+
+### Basic Configuration
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+
+export default defineServerConfig({
+  middlewares: [],
+  renderMiddlewares: [],
+  plugins: [],
+});
+```
+
+
+### Type Definition
+
+`defineServerConfig` type definition is as follows:
+
+```ts
+import type { MiddlewareHandler } from 'hono';
+
+type MiddlewareOrder = 'pre' | 'post' | 'default';
+type MiddlewareObj = {
+    name: string;
+    path?: string;
+    method?: 'options' | 'get' | 'post' | 'put' | 'delete' | 'patch' | 'all';
+    handler: MiddlewareHandler | MiddlewareHandler[];
+    before?: Array<MiddlewareObj['name']>;
+    order?: MiddlewareOrder;
+};
+type ServerConfig = {
+    middlewares?: MiddlewareObj[];
+    renderMiddlewares?: MiddlewareObj[];
+    plugins?: (ServerPlugin | ServerPluginLegacy)[];
+}
+```
+
+
+### Middleware
+
+Middleware supports executing custom logic before and after the **request handling** and **page routing** processes in Modern.js services.
+That is, if custom logic needs to handle both API routes and affect page routes, then Middleware is the obvious choice. If you only need to handle BFF API routes, this can be achieved by configuring the `path` to the BFF's `prefix`.
+
+:::note
+In the BFF scenario, BFF routing will only go through Middleware when the [runtime framework](/guides/advanced-features/bff/frameworks.html) is Hono.
+:::
+
+#### Using Posture
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+import { getMonitors } from '@modern-js/runtime';
+
+export const handler: MiddlewareHandler = async (c, next) => {
+  const monitors = getMonitors();
+  const start = Date.now();
+
+  await next();
+
+  const end = Date.now();
+  // Report Duration
+  monitors.timing('request_timing', end - start);
+};
+
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'request-timing',
+      handler,
+    },
+  ],
+});
+```
+
+:::warning
+You must execute the `next` function to proceed with the subsequent Middleware.
+:::
+
+
+### RenderMiddleware
+
+If you only need to handle the logic before and after page rendering, modern.js also provides rendering middleware.
+
+#### Using Posture
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+
+// Inject render performance metrics
+const renderTiming: MiddlewareHandler = async (c, next) => {
+  const start = Date.now();
+
+  await next();
+
+  const end = Date.now();
+  c.res.headers.set('server-timing', `render; dur=${end - start}`);
+};
+
+// Modify the Response Body
+const modifyResBody: MiddlewareHandler = async (c, next) => {
+  await next();
+
+  const { res } = c;
+  const text = await res.text();
+  const newText = text.replace('<body>', '<body> <h3>bytedance</h3>');
+
+  c.res = c.body(newText, {
+    status: res.status,
+    headers: res.headers,
+  });
+};
+
+export default defineServerConfig({
+  renderMiddlewares: [
+    {
+      name: 'render-timing',
+      handler: renderTiming,
+    },
+    {
+      name: 'modify-res-body',
+      handler: modifyResBody,
+    },
+  ],
+});
+```
+
+
+### Plugin
+
+Modern.js supports adding the aforementioned middleware and rendering middleware for the Server in custom plugins.
+
+#### Using Posture
+
+
+```ts title="server/plugins/server.ts"
+import type { ServerPluginLegacy } from '@modern-js/server-runtime';
+
+export default (): ServerPluginLegacy => ({
+  name: 'serverPlugin',
+  setup(api) {
+    return {
+      prepare(serverConfig) {
+        const { middlewares, renderMiddlewares } = api.useAppContext();
+
+        // Inject server-side data for page dataLoader consumption
+        middlewares?.push({
+          name: 'server-plugin-middleware',
+          handler: async (c, next) => {
+            c.set('message', 'hi modern.js');
+            await next();
+            // ...
+          },
+        });
+
+        // redirect
+        renderMiddlewares?.push({
+          name: 'server-plugin-render-middleware',
+          handler: async (c, next) => {
+            const user = getUser(c.req);
+            if (!user) {
+              return c.redirect('/login');
+            }
+
+            await next();
+          },
+        });
+        return serverConfig;
+      },
+    };
+  },
+});
+```
+
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+import serverPlugin from './plugins/serverPlugin';
+
+export default defineServerConfig({
+  plugins: [serverPlugin()],
+});
+```
+
+
+```ts title="src/routes/page.data.ts"
+import { useHonoContext } from '@modern-js/server-runtime';
+import { defer } from '@modern-js/runtime/router';
+
+export default () => {
+  const ctx = useHonoContext();
+  // Consuming Data Injected by the Server-Side
+  const message = ctx.get('message');
+
+  // ...
+};
+
+```

package/docs/en/guides/advanced-features/page-performance/inline-assets.mdx

@@ -96,6 +96,8 @@ When you reference a static asset in your CSS file, you can also force the asset
 :::tip Do you really need to exclude assets from inlining?
 Excluding assets from inlining will increase the number of assets that the Web App needs to load. This will reduce the efficiency of loading assets in a weak network environment or in scenarios where HTTP2 is not enabled. Please use force no Inline with caution.
 
+:::
+
 ## Inline JS files
 
 In addition to inlining static assets into JS files, Modern.js also supports inlining JS files into HTML files.

package/docs/en/guides/advanced-features/page-performance/optimize-bundle.mdx

@@ -4,7 +4,7 @@ sidebar_position: 13
 
 # Bundle Size Optimization
 
-Bundle size optimization is an important part in production environment because it directly affects the user experience of online users. In this document, we will introduce some common bundle size optimization methods in Modern.js.
+Bundle size optimization is an important part of optimizing your production environment because it directly affects the user experience. In this document, we will introduce some common bundle size optimization methods in Modern.js.
 
 ## Reduce duplicate dependencies