@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

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

@@ -0,0 +1,242 @@
+# Monitors
+
+Modern.js is a full-stack framework that supports both client-side and server-side development. When server-side rendering (SSR), the framework automatically injects additional logs and metrics during server runtime to help production issue diagnosis.
+
+As server code operates in Node.js environments, developers cannot directly utilize browser consoles for troubleshooting. Given that different projects may adopt varied logging libraries or data reporting platforms, the framework provides a unified approach for developers to manage built-in logging and metric collection.
+
+The Monitors module in Modern.js empowers application monitoring through two core capabilities: Monitor registration and monitoring event distribution. When developers invoke Monitors APIs, the framework propagates corresponding monitoring events to all registered Monitors.
+
+:::note
+Modern.js ships with a default Monitor implementation, while simultaneously allowing developers to register custom Monitors.
+:::
+
+## Monitors Type
+
+The Monitors module is defined with the following types, where the `push` method is used to register Monitor and other methods are used to dispatch monitoring events.
+
+```ts
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace';
+export interface LogEvent {
+  type: 'log';
+  payload: {
+    level: LogLevel;
+    message: string;
+    args?: any[];
+  };
+}
+
+export interface TimingEvent {
+  type: 'timing';
+  payload: {
+    name: string;
+    dur: number;
+    desc?: string;
+    args?: any[];
+  };
+}
+
+export interface CounterEvent {
+  type: 'counter';
+  payload: {
+    name: string;
+    args?: any[];
+  };
+}
+
+export type MonitorEvent = LogEvent | TimingEvent | CounterEvent;
+
+export type CoreMonitor = (event: MonitorEvent) => void;
+
+export interface Monitors {
+  // Register Monitor
+  push(monitor: CoreMonitor): void;
+
+  // Log Event
+  error(message: string, ...args: any[]): void;
+  warn(message: string, ...args: any[]): void;
+  debug(message: string, ...args: any[]): void;
+  info(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;
+}
+```
+
+## Internal Monitor
+
+Modern.js comes with a built-in default Monitor, where different events trigger different behaviors in the built-in Monitor. For more details, see:
+
+- [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](/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.
+
+```ts title="server/modern.server.ts"
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
+import type { MonitorEvent } from '@modern-js/types';
+
+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') {
+          // 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}`);
+        }
+      };
+
+      // 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 default defineServerConfig({
+  plugins: [myMonitorPlugin()],
+});
+```
+
+## Use Monitors
+
+Modern.js allows developers to invoke Monitors in Data Loaders and components.
+
+:::tip
+Monitors can only be invoked in Node.js environments, and calling them in browser environments will have no effect.
+:::
+
+In Data Loaders, developers can use them as follows:
+
+```ts title="routes/page.data.ts"
+import { LoaderFunctionArgs } from '@modern-js/runtime/router';
+import { getMonitors } from '@modern-js/runtime';
+const loader = async ({ context }: LoaderFunctionArgs) => {
+    const monitors = getMonitors();
+    const start = Date.now();
+    try {
+        await fetch(...);
+        monitors.timing('loader_fetch_timing', Date.now() - start);
+    } catch(e) {
+        monitors.error(e);
+    }
+}
+```
+
+When invoking Monitors in components, you need to determine whether the current runtime environment is Node.js:
+
+```tsx title="routes/page.tsx"
+import { use } from 'react';
+import { RuntimeContext, getMonitors } from '@modern-js/runtime';
+const Page = () => {
+  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/modern.server.ts"
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
+
+export const handler: MiddlewareHandler = async (c, next) => {
+  const monitors = c.get('monitors');
+  const start = Date.now();
+
+  await next();
+
+  const end = Date.now();
+  // Report timing
+  monitors.timing('request_timing', end - start);
+};
+
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'request-timing',
+      handler,
+    },
+  ],
+});
+```

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

@@ -0,0 +1,168 @@
+---
+sidebar_position: 11
+---
+
+# Source Code Build Mode
+
+The source code build mode is used in the monorepo development scenario, allowing developers to directly reference the source code of other sub-projects within the monorepo for development.
+
+## Use Cases
+
+In a monorepo, there are two main ways for projects to reference each other: artifact referencing and source code referencing. Let's use a simple monorepo as an example to illustrate the use case of source code referencing.
+
+For example, the monorepo contains an app application and a lib:
+
+```ts
+monorepo
+├── app
+└── lib
+    └── src
+        └── index.ts
+```
+
+The app is built using Modern.js and relies on some methods from the lib:
+
+```json
+{
+  "name": "app",
+  "dependencies": {
+    "lib": "workspace:*"
+  }
+}
+```
+
+### Artifact Referencing
+
+**When using artifact referencing, the current project references the artifacts built from other sub-projects.**
+
+In the example above, the lib is written in TypeScript. Typically, we need to build the lib's code in advance to generate JavaScript artifacts so that the app can reference it correctly. When the lib's code is updated, we need to rebuild it (or use `tsgo --watch`) to ensure that the app can use the latest code.
+
+The advantages of this approach are:
+
+- The build processes of each sub-project are completely independent and can have different build configurations.
+- Build caching can be applied to individual sub-projects.
+
+The disadvantages are:
+
+- The HMR chain becomes longer during local development.
+- The process becomes cumbersome when a project contains multiple lib packages.
+
+### Source Code Referencing
+
+**When using source code referencing, the current project references the source code of other sub-projects for building.**
+
+In the example mentioned earlier, when you enable the source code build mode and add the relevant configuration in the `lib` directory, Modern.js will automatically reference the `src/index.ts` source code of the lib. This means that you don't need to build the lib's code in advance, and when the source code of the lib is updated, it can trigger automatic hot updates for the app.
+
+The advantages of this approach are:
+
+- The sub-project does not rely on a build tool and does not require build configurations. The code of the sub-project will be compiled by the build tool of the current project.
+- There is no need to execute the build process for the sub-projects in advance.
+- HMR is more efficient during local development.
+
+The disadvantages are:
+
+- The current project needs to support syntax features used by sub-projects and follow the same syntax specifications, such as using a consistent version of decorator syntax. If the current project and sub-projects require different build configurations, building from source code may not be suitable.
+- The current project requires compiling more code, which may result in longer build times.
+
+## Building from Source Code
+
+### Enabling Configuration
+
+You can enable source code build mode by setting [experiments.sourceBuild](/configure/app/experiments/source-build.html) to `true`.
+
+```ts
+export default {
+  experiments: {
+    sourceBuild: true,
+  },
+};
+```
+
+### Configuring Sub-projects
+
+When the source code build mode is enabled, the Modern.js will prioritize reading the file specified in the `source` field of the sub-project during the build process. Therefore, you need to configure the `source` field in the package.json file of the sub-project and point it to the source code file.
+
+For example, in the following example, when the lib package is referenced, the `./src/index.ts` file will be read for building:
+
+```json title="package.json"
+{
+  "name": "lib",
+  "main": "./dist/index.js",
+  "source": "./src/index.ts"
+}
+```
+
+If the sub-project uses [exports](https://nodejs.org/api/packages.html#package-entry-points) field, you also need to add the `source` field in the `exports` field.
+
+```json title="package.json"
+{
+  "name": "lib",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./features": {
+      "source": "./src/features/index.ts",
+      "default": "./dist/features/index.js"
+    }
+  }
+}
+```
+
+## Configure Project Reference
+
+In a TypeScript project, you need to use the capability provided by TypeScript called [Project Reference](https://www.typescriptlang.org/docs/handbook/project-references.html). It helps you develop source code more effectively.
+
+### Introduction
+
+Project reference provides the following capabilities:
+
+- It allows TypeScript to correctly recognize the types of other sub-projects without the need to build them.
+- When you navigate the code in VS Code, it automatically takes you to the corresponding source code file of the module.
+- Modern.js reads the project reference configuration and automatically recognizes the `tsconfig.compilerOptions.path` configuration of the sub-project, so that the use of aliases in the sub-project works correctly.
+
+### Example
+
+In the example mentioned earlier, since the app project references the lib sub-project, we need to configure the `references` options in the app project's `tsconfig.json` to point to the relative directory of the lib:
+
+```json title="app/tsconfig.json"
+{
+  "references": [
+    {
+      "path": "../lib"
+    }
+  ]
+}
+```
+
+At the same time, we need to set `composite` to `true` in the lib project's `tsconfig.json`:
+
+```json title="lib/A/tsconfig.json"
+{
+  "compilerOptions": {
+    "composite": true
+  },
+}
+```
+
+After adding these two options, the project reference is already configured. You can restart VS Code to see the effects of the configuration.
+
+Note that the above example is a simplified one. In real monorepo projects, there may be more complex dependency relationships. You need to add a complete `references` configuration for the functionality to work correctly.
+
+:::tip
+If you want to learn more about project reference, please refer to the official documentation on [TypeScript - Project References](https://www.typescriptlang.org/docs/handbook/project-references.html).
+:::
+
+## Caveat
+
+When using source code build mode, there are a few things to keep in mind:
+
+1. Ensure that the current project can compile the syntax or features used in the sub-project. For example, if the sub-project uses Stylus to write CSS, the current app needs to support Stylus compilation.
+2. Ensure that the current project has the same code syntax and features as the sub-project, such as consistent syntax versions for decorators.
+3. Source code building may have some limitations. When encountering issues, you can remove the `source` field from the sub-project's package.json and debug using the built artifacts of the sub-project.
+4. When `composite: true` is enabled, TypeScript will generate `*.tsbuildinfo` temporary files. You need to add these temporary files to the `.gitignore` file.
+
+```text title=".gitignore"
+*.tsbuildinfo
+```

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

@@ -0,0 +1,284 @@
+---
+sidebar_position: 16
+---
+
+# Custom Web 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.
+
+To use the Custom Web Server in a Modern.js project, follow these steps:
+
+1. Install `@modern-js/server-runtime` dependency
+
+If the `@modern-js/server-runtime` dependency is not yet installed in your project, install it first:
+
+```bash
+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>
+```
+
+:::
+
+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**
+
+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: [],
+  onError: () => {},
+});
+```
+
+### 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[];
+  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.
+If custom logic needs to handle both API routes and page routes, Middleware is the clear choice.
+
+:::note
+If you only need to handle BFF API routes, you can determine whether a request is for a BFF API by checking if `req.path` starts with the BFF `prefix`.
+:::
+
+Usage is as follows:
+
+```ts title="server/modern.server.ts"
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
+
+export const handler: MiddlewareHandler = async (c, next) => {
+  const monitors = c.get('monitors');
+  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, which can be used as follows:
+
+```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, which can be used as follows:
+
+```ts title="server/plugins/server.ts"
+import type { ServerPlugin } from '@modern-js/server-runtime';
+
+export default (): ServerPlugin => ({
+  name: 'serverPlugin',
+  setup(api) {
+    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';
+
+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();
+  // SSR scenario consumes data injected by the Server Side
+  const message = ctx.get('message');
+
+  // ...
+};
+```
+
+### 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.
+
+Below is a basic example of an `onError` configuration:
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+
+export default defineServerConfig({
+  onError: (err, c) => {
+    // Log the error
+    console.error('Server error:', err);
+
+    // Return different responses based on the error type
+    if (err instanceof SyntaxError) {
+      return c.json({ error: 'Invalid JSON' }, 400);
+    }
+
+    // Customize BFF error response based on request path
+    if (c.req.path.includes('/api')) {
+      return c.json({ message: 'API error occurred' }, 500);
+    }
+
+    return c.text('Internal Server Error', 500);
+  },
+});
+```