@modern-js/main-doc 2.69.7 → 3.0.0-alpha.1

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

@@ -56,11 +56,11 @@ export interface Monitors {
   warn(message: string, ...args: any[]): void;
   debug(message: string, ...args: any[]): void;
   info(message: string, ...args: any[]): void;
-  trace(message: string,...args: any[]): void;
+  trace(message: string, ...args: any[]): void;
 
   // Metrics Event
   timing(name: string, dur: number, ...args: any[]): void;
-  counter(name: string, ...args: any[]): void
+  counter(name: string, ...args: any[]): void;
 }
 ```
 
@@ -71,31 +71,104 @@ Modern.js comes with a built-in default Monitor, where different events trigger
 - [Log Event](/guides/advanced-features/server-monitor/logger)
 - [Metrics Event](/guides/advanced-features/server-monitor/metrics)
 
-
 ## Register Monitors
 
-Developers can register their own Monitors using the `push` API, but this can only be done in [server middleware](/apis/app/runtime/web-server/unstable_middleware) or server plugins. Registration is not available in Data Loaders, components, or init functions.
+Developers can register their own Monitors using the `push` API, but this can only be done in [server middleware](/guides/advanced-features/web-server#unstable-middleware) or [server plugins](/plugin/server-plugins/api). Registration is not available in Data Loaders, components, or init functions.
 
-:::note
-Server plugins are currently not available, and documentation will be added in the future.
-:::
+```ts title="server/modern.server.ts"
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
+import type { MonitorEvent } from '@modern-js/types';
 
-```ts title="server/index.ts"
-import type { CoreMonitors } from '@modern-js/types';
-const injectMonitorMiddleware = (c) => {
-    const monitors = c.get('monitors');
-    const myMonitor = (event: MonitorEvent) => {
+const injectMonitorMiddleware: MiddlewareHandler = async (c, next) => {
+  const monitors = c.get('monitors');
+  const myMonitor = (event: MonitorEvent) => {
+    if (event.type === 'log') {
+      // Handle log events
+      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`);
+    } else if (event.type === 'counter') {
+      // Handle counter events
+      console.log(`Counter: ${event.payload.name}`);
+    }
+  };
+  monitors.push(myMonitor);
+  await next();
+};
+
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'inject-monitor',
+      handler: injectMonitorMiddleware,
+    },
+  ],
+});
+```
+
+Register Monitor in server plugins:
+
+```ts title="server/plugins/my-monitor-plugin.ts"
+import type { ServerPlugin } from '@modern-js/server-runtime';
+import type { MonitorEvent } from '@modern-js/types';
+
+const myMonitorPlugin = (): ServerPlugin => ({
+  name: '@my-org/my-monitor-plugin',
+  setup(api) {
+    api.onPrepare(() => {
+      const { middlewares } = api.getServerContext();
+
+      // Define monitor, ensuring it's only created once
+      const myMonitor = (event: MonitorEvent) => {
         if (event.type === 'log') {
-          // some code
-        } else {
-          // some other code
+          // Handle log events
+          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`,
+          );
+        } else if (event.type === 'counter') {
+          // Handle counter events
+          console.log(`Counter: ${event.payload.name}`);
         }
-    }
-    monitors.push(myMonitor);
-    return next();
-}
+      };
+
+      // Use a flag to ensure monitor is only registered once
+      let monitorRegistered = false;
+
+      middlewares.push({
+        name: 'inject-monitor',
+        handler: async (c, next) => {
+          const monitors = c.get('monitors');
+          // Only register monitor on the first request
+          if (!monitorRegistered) {
+            monitors.push(myMonitor);
+            monitorRegistered = true;
+          }
+          await next();
+        },
+      });
+    });
+  },
+});
+
+export default myMonitorPlugin;
+```
+
+Then configure the plugin in `server/modern.server.ts`:
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+import myMonitorPlugin from './plugins/my-monitor-plugin';
 
-export const middlewares = [injectMonitorMiddleware]
+export default defineServerConfig({
+  plugins: [myMonitorPlugin()],
+});
 ```
 
 ## Use Monitors
@@ -126,32 +199,44 @@ const loader = async ({ context }: LoaderFunctionArgs) => {
 When invoking Monitors in components, you need to determine whether the current runtime environment is Node.js:
 
 ```tsx title="routes/page.tsx"
-import { getMonitors } from '@modern-js/runtime';
+import { use } from 'react';
+import { RuntimeContext, getMonitors } from '@modern-js/runtime';
 const Page = () => {
-    const { context } = useRuntimeContext();
-    if (process.env.MODERN_TARGET === 'node') {
-        const monitors = getMonitors();
-        monitors.info();
-    }
-    return <div>Hello World</div>
-}
+  const context = use(RuntimeContext);
+  if (process.env.MODERN_TARGET === 'node') {
+    const monitors = getMonitors();
+    monitors.info('Page rendered');
+  }
+  return <div>Hello World</div>;
+};
 export default Page;
 ```
 
 In middleware, we can also invoke Monitors, but the approach differs from runtime code as it requires accessing them through `context`:
 
-```ts title="server/index.ts"
-import { UnstableMiddleware } from '@modern-js/runtime/server';
+```ts title="server/modern.server.ts"
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
 
-const time: UnstableMiddleware = async (c, next) => {
+export const handler: MiddlewareHandler = async (c, next) => {
+  const monitors = c.get('monitors');
   const start = Date.now();
+
   await next();
+
   const end = Date.now();
-  const monitors = c.get('monitors');
-  monitors.info(`${end - start}`);
+  // Report timing
+  monitors.timing('request_timing', end - start);
 };
 
-export const unstableMiddleware: UnstableMiddleware[] = [time];
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'request-timing',
+      handler,
+    },
+  ],
+});
 ```
-
-

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

@@ -6,27 +6,54 @@ sidebar_position: 16
 
 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.
 
-## Starting a Custom Web Server
+To use the Custom Web Server in a Modern.js project, follow these steps:
 
-:::tip
-You must ensure that the Modern.js version is x.67.5 or above.
-:::
+1. Install `@modern-js/server-runtime` dependency
 
-Developers can execute the `pnpm run new` command in the project root directory to start the "Custom Web Server" feature:
+If the `@modern-js/server-runtime` dependency is not yet installed in your project, install it first:
 
 ```bash
-? Select operation: Create project element
-? Select element type: Create "Custom Web Server" source directory
+pnpm add @modern-js/server-runtime
+```
+
+:::tip Version Consistency
+Make sure the version of `@modern-js/server-runtime` matches the version of `@modern-js/app-tools` in your project. All Modern.js official packages are released with a uniform version number, and version mismatches may cause compatibility issues.
+
+Check the version of `@modern-js/app-tools` first, then install the same version of `@modern-js/server-runtime`:
+
+```bash
+# Check the current version of @modern-js/app-tools
+pnpm list @modern-js/app-tools
+
+# Install the same version of @modern-js/server-runtime
+pnpm add @modern-js/server-runtime@<version>
 ```
 
-After executing the command, a `server/modern.server.ts` file will be automatically created in the project directory, where you can write custom logic.
+:::
+
+2. Create the `server` directory and configuration file
+
+Create a `server/modern.server.ts` file in the project root directory:
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+
+export default defineServerConfig({
+  middlewares: [], // Middleware
+  renderMiddlewares: [], // Render Middleware
+  plugins: [], // Plugins
+  onError: () => {}, // Error handling
+});
+```
 
+After creating the file, you can write custom logic in this file.
 
 ## Capabilities of the Custom Web Server
 
 Modern.js's Web Server is based on Hono, and in the latest version of the Custom Web Server, we expose Hono's middleware capabilities, you can refer to [Hono API](https://hono.dev/docs/api/context) for more usage.
 
 In the `server/modern.server.ts` file, you can add the following configurations to extend the Server:
+
 - **Middleware**
 - **Render Middleware**
 - **Server-side Plugin**
@@ -51,7 +78,6 @@ export default defineServerConfig({
 });
 ```
 
-
 ### Type Definition
 
 `defineServerConfig` type definition is as follows:
@@ -61,22 +87,21 @@ 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;
+  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)[];
-    onError?: (err: Error, c: Context) => Promise<any> | any;
-}
+  middlewares?: MiddlewareObj[];
+  renderMiddlewares?: MiddlewareObj[];
+  plugins?: ServerPlugin[];
+  onError?: (err: Error, c: Context) => Promise<any> | any;
+};
 ```
 
-
 ### Middleware
 
 Middleware supports executing custom logic before and after the **request handling** and **page routing** processes in Modern.js services.
@@ -89,7 +114,10 @@ If you only need to handle BFF API routes, you can determine whether a request i
 Usage is as follows:
 
 ```ts title="server/modern.server.ts"
-import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
 
 export const handler: MiddlewareHandler = async (c, next) => {
   const monitors = c.get('monitors');
@@ -116,13 +144,15 @@ export default defineServerConfig({
 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, which can be used as follows:
 
 ```ts title="server/modern.server.ts"
-import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
 
 // Inject render performance metrics
 const renderTiming: MiddlewareHandler = async (c, next) => {
@@ -162,52 +192,46 @@ export default defineServerConfig({
 });
 ```
 
-
 ### Plugin
 
 Modern.js supports adding the aforementioned middleware and rendering middleware for the Server in custom plugins, which can be used as follows:
 
-
 ```ts title="server/plugins/server.ts"
-import type { ServerPluginLegacy } from '@modern-js/server-runtime';
+import type { ServerPlugin } from '@modern-js/server-runtime';
 
-export default (): ServerPluginLegacy => ({
+export default (): ServerPlugin => ({
   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;
-      },
-    };
+    api.onPrepare(() => {
+      const { middlewares, renderMiddlewares } = api.getServerContext();
+
+      // 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();
+        },
+      });
+    });
   },
 });
 ```
 
-
 ```ts title="server/modern.server.ts"
 import { defineServerConfig } from '@modern-js/server-runtime';
 import serverPlugin from './plugins/serverPlugin';
@@ -217,7 +241,6 @@ export default defineServerConfig({
 });
 ```
 
-
 ```ts title="src/routes/page.data.ts"
 import { useHonoContext } from '@modern-js/server-runtime';
 import { defer } from '@modern-js/runtime/router';
@@ -229,10 +252,8 @@ export default () => {
 
   // ...
 };
-
 ```
 
-
 ### onError
 
 `onError` is a global error handling function used to capture and handle all uncaught errors in the Modern.js server. By customizing the `onError` function, developers can uniformly handle different types of errors, return custom error responses, and implement features such as error logging and error classification.
@@ -261,241 +282,3 @@ export default defineServerConfig({
   },
 });
 ```
-
-## Legacy API (Deprecated)
-
-:::warning
-The legacy API is compatible but no longer recommended. For extending server capabilities, please refer to [Custom Web Server](/guides/advanced-features/web-server.html#custom-web-server). For migration guidelines, see [Migrating to the New Version of Custom Web Server](/guides/advanced-features/web-server.html#migrate-to-the-new-version-of-custom-web-server).
-:::
-
-### Enable
-To enable the custom Web Server feature, follow these steps:
-1. Add `@modern-js/plugin-server`、`tsconfig-paths` and `ts-node` to `devDependencies` and install them.
-2. Add `server` to the `include` section of `tsconfig`.
-3. Register the `@modern-js/plugin-server` plugin in `modern.config.ts`.
-4. Create a `server/index.ts` file in the project directory, where you can write custom logic.
-
-### Unstable Middleware
-
-Modern.js supports adding rendering middleware to the Web Server, allowing custom logic execution before and after processing page routes.
-
-```ts title="server/index.ts"
-import {
-  UnstableMiddleware,
-  UnstableMiddlewareContext,
-} from '@Modern.js/runtime/server';
-
-const time: UnstableMiddleware = async (c: UnstableMiddlewareContext, next) => {
-  const start = Date.now();
-
-  await next();
-
-  const end = Date.now();
-
-  console.log(`dur=${end - start}`);
-};
-
-export const unstableMiddleware: UnstableMiddleware[] = [time];
-```
-
-
-### Hooks
-
-:::warning
-We recommend using UnstableMiddleware instead of Hooks.
-:::
-
-Modern.js provides Hooks to control specific logic in the Web Server. All page requests will pass through Hooks.
-
-Currently, two types of Hooks are available: `AfterMatch` and `AfterRender`. Developers can implement them in `server/index.ts` as follows:
-
-```ts
-import type {
-  AfterMatchHook,
-  AfterRenderHook,
-} from '@modern-js/runtime/server';
-
-export const afterMatch: AfterMatchHook = (ctx, next) => {
-  next();
-};
-
-export const afterRender: AfterRenderHook = (ctx, next) => {
-  next();
-};
-```
-
-Best practices when using Hooks:
-
-1. Perform authorization checks in afterMatch.
-2. Handle Rewrite and Redirect in afterMatch.
-3. Inject HTML content in afterRender.
-
-
-
-## Migrate to the New Version of Custom Web Server
-
-### Migration Background
-
-Modern.js Server is continuously evolving to provide more powerful features. We have optimized the definition and usage of middleware and Server plugins.
-While the old custom Web Server approach is still compatible, we strongly recommend migrating according to this guide to fully leverage the advantages of the new version.
-
-### Migration Steps
-
-1. Upgrade Modern.js version to x.67.5 or above.
-2. Configure middleware or plugins in `server/modern.server.ts` according to the new definition method.
-3. Migrate the custom logic in `server/index.ts` to middleware or plugins, and update your code with reference to the differences between `Context` and `Next`.
-
-### Context Differences
-
-In the new version, the middleware handler type is Hono's `MiddlewareHandler`, meaning the `Context` type is `Hono Context`. The differences from the old custom Web Server's `Context` are as follows:
-
-
-#### UnstableMiddleware
-
-
-```ts
-type Body = ReadableStream | ArrayBuffer | string | null;
-
-type UnstableMiddlewareContext<
-  V extends Record<string, unknown> = Record<string, unknown>,
-> = {
-  request: Request;
-  response: Response;
-  get: Get<V>;
-  set: Set<V>;
-  // Current Matched Routing Information
-  route: string;
-  header: (name: string, value: string, options?: { append?: boolean }) => void;
-  status: (code: number) => void;
-  redirect: (location: string, status?: number) => Response;
-  body: (data: Body, init?: ResponseInit) => Response;
-  html: (
-    data: string | Promise<string>,
-    init?: ResponseInit,
-  ) => Response | Promise<Response>;
-};
-```
-
-Differences between UnstableMiddleware Context and Hono Context:
-
-| UnstableMiddleware       | Hono                          | Description                                                                      |
-| :----------------------- | :---------------------------- | :------------------------------------------------------------------------ |
-| `c.request`              | `c.req.raw`                   | Refer to [HonoRequest raw](https://hono.dev/docs/api/request#raw) documentation         |
-| `c.response`             | `c.res`                       | Refer to [Hono Context res](https://hono.dev/docs/api/context#res) documentation       |
-| `c.route`                | `c.get('route')`              | Get application context information.                                                          |
-| `loaderContext.get`      | `honoContext.get`             | After injecting data using `c.set`, consume in dataLoader: the old version uses `loaderContext.get`, refer to the new version in [Plugin](/guides/advanced-features/web-server.html#plugin) example    |
-
-
-#### Middleware
-
-```ts
-type MiddlewareContext = {
-  response: {
-    set: (key: string, value: string) => void;
-    status: (code: number) => void;
-    getStatus: () => number;
-    cookies: {
-      set: (key: string, value: string, options?: any) => void;
-      clear: () => void;
-    };
-    raw: (
-      body: string,
-      { status, headers }: { status: number; headers: Record<string, any> },
-    ) => void;
-    locals: Record<string, any>;
-  };
-  request: {
-    url: string;
-    host: string;
-    pathname: string;
-    query: Record<string, any>;
-    cookie: string;
-    cookies: {
-      get: (key: string) => string;
-    };
-    headers: IncomingHttpHeaders;
-  };
-  source: {
-    req: IncomingMessage;
-    res: ServerResponse;
-  };
-};
-
-```
-
-Differences between Middleware `Context` and Hono `Context`:
-| UnstableMiddleware       | Hono                          | Description                                                                  |
-| :----------------------- | :---------------------------- | :--------------------------------------------------------------------------- |
-| `c.request.cookie`         | `c.req.cookie()`              | Refer to [Hono Cookie Helper](https://hono.dev/docs/helpers/cookie) documentation |
-| `c.request.pathname`       | `c.req.path`                  | Refer to [HonoRequest path](https://hono.dev/docs/api/request#path) documentation |
-| `c.request.url`            | -                             | Hono `c.req.url` provides the full request URL, calculate manually from URL |
-| `c.request.host`           | `c.req.header('Host')`        | Obtain host through header                                                  |
-| `c.request.query`          | `c.req.query()`               | Refer to [HonoRequest query](https://hono.dev/docs/api/request#query) documentation |
-| `c.request.headers`        | `c.req.header()`              | Refer to [HonoRequest header](https://hono.dev/docs/api/request#header) documentation |
-| `c.response.set`           | `c.res.headers.set`           | Example: `c.res.headers.set('custom-header', '1')`                          |
-| `c.response.status`        | `c.status`                    | Example: `c.status(201)`                                                    |
-| `c.response.cookies`       | `c.header`                    | Example: `c.header('Set-Cookie', 'user_id=123')`                            |
-| `c.response.raw`           | `c.res`                       | Refer to [Hono Context res](https://hono.dev/docs/api/context#res) documentation |
-
-#### Hook
-
-```ts
-type HookContext = {
-  response: {
-    set: (key: string, value: string) => void;
-    status: (code: number) => void;
-    getStatus: () => number;
-    cookies: {
-      set: (key: string, value: string, options?: any) => void;
-      clear: () => void;
-    };
-    raw: (
-      body: string,
-      { status, headers }: { status: number; headers: Record<string, any> },
-    ) => void;
-  };
-  request: {
-    url: string;
-    host: string;
-    pathname: string;
-    query: Record<string, any>;
-    cookie: string;
-    cookies: {
-      get: (key: string) => string;
-    };
-    headers: IncomingHttpHeaders;
-  };
-};
-
-type AfterMatchContext = HookContext & {
-  router: {
-    redirect: (url: string, status: number) => void;
-    rewrite: (entry: string) => void;
-  };
-};
-
-type AfterRenderContext = {
-  template: {
-    get: () => string;
-    set: (html: string) => void;
-    prependHead: (fragment: string) => void;
-    appendHead: (fragment: string) => void;
-    prependBody: (fragment: string) => void;
-    appendBody: (fragment: string) => void;
-  };
-};
-```
-
-Hook Context is mostly consistent with Middleware Context, so we need to pay extra attention to the additional parts of different Hooks.
-
-| UnstableMiddleware       | Hono                          | Description                           |
-| :----------------------- | :---------------------------- | :------------------------------------ |
-| `router.redirect`        | `c.redirect`                  | Refer to [Hono Context redirect](https://hono.dev/docs/api/context#redirect) documentation      |
-| `router.rewrite`         | -                             | No corresponding capability provided at the moment                                                   |
-| template API             | `c.res`                       | Refer to [Hono Context res](https://hono.dev/docs/api/context#res) documentation               |
-
-
-### Differences in Next API
-
-In Middleware and Hooks, the render function executes even without invoking `next`.
-In the new design, subsequent Middleware will only execute if the `next` function is invoked.

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

@@ -1,5 +1,10 @@
 [
-  "routes",
+  {
+    "type": "dir",
+    "name": "routes",
+    "label": "Routes",
+    "collapsed": true
+  },
   {
     "type": "dir",
     "name": "data",