@modern-js/main-doc 2.68.12 → 2.68.14

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

@@ -47,6 +47,7 @@ export default defineServerConfig({
   middlewares: [],
   renderMiddlewares: [],
   plugins: [],
+  onError: () => {},
 });
 ```
 
@@ -71,6 +72,7 @@ type ServerConfig = {
     middlewares?: MiddlewareObj[];
     renderMiddlewares?: MiddlewareObj[];
     plugins?: (ServerPlugin | ServerPluginLegacy)[];
+    onError?: (err: Error, c: Context) => Promise<any> | any;
 }
 ```
 
@@ -231,6 +233,35 @@ 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.
+
+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);
+  },
+});
+```
+
 ## Legacy API (Deprecated)
 
 :::warning
@@ -267,9 +298,6 @@ const time: UnstableMiddleware = async (c: UnstableMiddlewareContext, next) => {
 export const unstableMiddleware: UnstableMiddleware[] = [time];
 ```
 
-:::info
-For detailed API and more usage, see [UnstableMiddleware](/apis/app/runtime/web-server/unstable_middleware).
-:::
 
 ### Hooks
 
@@ -302,9 +330,6 @@ Best practices when using Hooks:
 2. Handle Rewrite and Redirect in afterMatch.
 3. Inject HTML content in afterRender.
 
-:::info
-For detailed API and more usage, see [Hook](/apis/app/runtime/web-server/hook).
-:::
 
 
 ## Migrate to the New Version of Custom Web Server

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

@@ -48,6 +48,7 @@ export default defineServerConfig({
   middlewares: [], // 中间件
   renderMiddlewares: [], // 渲染中间件
   plugins: [], // 插件
+  onError: () => {}, // 错误处理
 });
 ```
 
@@ -69,6 +70,7 @@ type ServerConfig = {
     middlewares?: MiddlewareObj[];
     renderMiddlewares?: MiddlewareObj[];
     plugins?: (ServerPlugin | ServerPluginLegacy)[];
+    onError?: (err: Error, c: Context) => Promise<any> | any;
 }
 ```
 
@@ -228,6 +230,36 @@ export default () => {
 ```
 
 
+### onError
+
+`onError` 是一个全局错误处理函数，用于捕获和处理 Modern.js server 中的所有未捕获错误。通过自定义 `onError` 函数，开发者可以统一处理不同类型的错误，返回自定义的错误响应，实现错误日志记录、错误分类处理等功能。
+
+以下是一个基本的 `onError` 配置示例：
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+
+export default defineServerConfig({
+  onError: (err, c) => {
+    // 记录错误日志
+    console.error('Server error:', err);
+
+    // 根据不同的错误类型返回不同的响应
+    if (err instanceof SyntaxError) {
+      return c.json({ error: 'Invalid JSON' }, 400);
+    }
+
+    // 根据请求路径定制 bff 异常响应
+    if (c.req.path.includes('/api')) {
+      return c.json({ message: 'API error occurred' }, 500);
+    }
+
+    return c.text('Internal Server Error', 500);
+  },
+});
+```
+
+
 ## 旧版 API（废弃）
 
 :::warning

package/package.json

@@ -15,14 +15,14 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.68.12",
+  "version": "2.68.14",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.4.1",
-    "@modern-js/sandpack-react": "2.68.12"
+    "@modern-js/sandpack-react": "2.68.14"
   },
   "devDependencies": {
     "@rsbuild/plugin-sass": "1.4.0",