@modern-js/main-doc 2.49.3 → 2.50.0

package/docs/en/apis/app/runtime/web-server/middleware.mdx

@@ -1,10 +1,17 @@
 ---
 title: Middleware
 ---
+
 # Middleware
 
 Used to extend the built-in Web Server of Modern.js, unlike [Hook](/apis/app/runtime/web-server/hook), Middleware can directly operate Node's origin request and response, and can be extended using the framework plugin.
 
+:::note
+In the next major release, Modern.js will use new middleware to replace this approach.
+
+It is recommended to use [UnstableMiddleware](/apis/app/runtime/web-server/unstable_middleware) to handle page requests.
+:::
+
 :::note
 For more detail, see [Extend Web Server](/guides/advanced-features/web-server).
 
@@ -125,7 +132,6 @@ export const middleware: SomeType = (ctx, next) => {
 
 By default, the framework extension capability of Web Server is turned off after installing the framework extension plugin. If you want to use the framework extension, you can turn it on through ['server.enableFrameworkExt'](/configure/app/server/enable-framework-ext.html).
 
-
 :::info
 The type name exported by the framework extension may not 'Middleware', but is named by the framework extension plugin.
 :::

package/docs/en/apis/app/runtime/web-server/unstable_middleware.mdx

@@ -0,0 +1,134 @@
+---
+title: Unstable Middleware
+---
+
+# Unstable Middleware
+
+Used to extend the built-in Web Server in Modern.js.
+UnstableMiddleware will replace [Middleware](/apis/app/runtime/web-server/middleware) in the future.
+
+## Usage
+
+```ts title="server/index.ts"
+import { UnstableMiddleware } from '@modern-js/runtime/server';
+
+export const unstableMiddlewares: UnstableMiddleware[] = [];
+```
+
+## Types
+
+**UnstableMiddleware**
+
+```ts
+type UnstableMiddleware<
+  V extends Record<string, unknown> = Record<string, unknown>,
+> = (
+  c: UnstableMiddlewareContext<V>,
+  next: UnstableNext,
+) => Promise<void | Response>;
+```
+
+**UnstableMiddlewareContext**
+
+```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>;
+  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>;
+};
+```
+
+**UnstableNext**
+
+```ts
+type UnstableNext = () => Promise<void>;
+```
+
+## Examples
+
+### Web Server Timing
+
+```ts
+import { UnstableMiddleware } from '@modern-js/runtime/server';
+
+const time: UnstableMiddleware = async (c, next) => {
+  const start = Date.now();
+
+  await next();
+
+  const end = Date.now();
+
+  console.log(`${end - start}`);
+};
+
+export const unstableMiddlewares: UnstableMiddleware = [time];
+```
+
+### Injecting Server Data for DataLoader Consumption
+
+```ts title="shared/index.ts"
+export type Vars = {
+  message: string;
+};
+```
+
+```ts title="server/index.ts"
+import {
+  UnstableMiddleware,
+  UnstableMiddlewareContext,
+} from '@modern-js/runtime/server';
+import type { Vars } from '../shared/index';
+
+const setPayload: UnstableMiddleware = async (
+  c: UnstableMiddlewareContext<Vars>,
+  next,
+) => {
+  c.set('message', 'facker');
+
+  await next();
+};
+
+export const unstableMiddlewares: UnstableMiddleware = [setPayload];
+```
+
+```ts title="src/routes/page.data.ts"
+import type { Payload } from '../../shared/index';
+import { LoaderFunctionArgs } from '@modern-js/runtime/router';
+
+export const loader = async ({ context }: LoaderFunctionArgs<Vars>) => {
+  const message = context?.get('message');
+
+  // ...
+};
+```
+
+### Redirect
+
+```ts
+import { UnstableMiddleware } from '@modern-js/runtime/server';
+
+const auth: UnstableMiddleware = async (c, next) => {
+  const user = getUser(c.request);
+
+  if (!user) {
+    return c.redirect('/login');
+  }
+
+  await next();
+};
+
+export const unstableMiddlewares: UnstableMiddleware = [auth];
+```

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

@@ -50,15 +50,18 @@ The Hook provided by Modern.js is used to control the built-in logic in the Web
 Currently, two Hooks are provided: `AfterMatch` and `AfterRender`, which can be used to modify the rendering results. It can be written in `server/index.ts` as follows:
 
 ```ts
-import type { AfterMatchHook, AfterRenderHook } from '@modern-js/runtime/server';
+import type {
+  AfterMatchHook,
+  AfterRenderHook,
+} from '@modern-js/runtime/server';
 
 export const afterMatch: AfterMatchHook = (ctx, next) => {
   next();
-}
+};
 
 export const afterRender: AfterRenderHook = (ctx, next) => {
   next();
-}
+};
 ```
 
 Projects should follow these best practices when using Hook:
@@ -75,13 +78,21 @@ For more detail, see [Hook](/apis/app/runtime/web-server/hook).
 
 For some projects, there may be more requirements at the server level, Modern.js provides Middleware to add pre-middleware for Web Server. It can only run in a Node environment, so if the project is deployed to another environment, such as a Worker environment, Middleware cannot be used.
 
+:::note
+In the next major release, Modern.js will use new middleware to replace this approach.
+
+It is recommended to use [UnstableMiddleware](/guides/advanced-features/web-server.html#unstablemiddleware) to handle page requests.
+:::
+
 Modern.js provides a set of APIs by default for projects to use:
 
 ```ts
 import { Middlewre } from '@modern-js/runtime/server';
 
 export const middleware: Middlewre = (context, next) => {
-  const { source: { req, res } } = context;
+  const {
+    source: { req, res },
+  } = context;
   console.log(req.url);
   next();
 };
@@ -99,6 +110,33 @@ Projects should follow these best practices when using Middleware:
 
 **In general, in CSR projects, using Hook can basically meet all the needs of simple scenarios. In SSR projects, Middleware can be used for more complex Node extensions.**
 
+### UnstableMiddleware
+
+Modern.js will provide new Middleware to add pre-processing middleware to the Web Server, supporting the execution of custom logic before and after handling the page.
+
+```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];
+```
+
+:::note
+For detailed API and more usage, please refer to [UnstableMiddleware](/apis/app/runtime/web-server/unstable_middleware)
+:::
+
 ## Managed Page Requests with BFF
 
 The second way is to use BFF to Managed page rendering. In this way, all requests will first hit the BFF service.

package/docs/zh/apis/app/runtime/web-server/middleware.mdx

@@ -1,10 +1,17 @@
 ---
 title: Middleware
 ---
+
 # Middleware
 
 用于拓展 Modern.js 内置的 Web Server，与 [Hook](/apis/app/runtime/web-server/hook) 不同的是，Middleware 可以直接操作 Node 原生的请求、响应对象，并且可以使用框架拓展。
 
+:::note
+在下一个大版本，Modern.js 将会使用新 Middleware 来替代该写法。
+
+推荐使用 [UnstableMiddleware](/apis/app/runtime/web-server/unstable_middleware) 处理页面请求。
+:::
+
 :::note
 更多内容可以查看[自定义 Web Server](/guides/advanced-features/web-server)。
 :::

package/docs/zh/apis/app/runtime/web-server/unstable_middleware.mdx

@@ -0,0 +1,133 @@
+---
+title: Unstable Middleware
+---
+
+# Unstable Middleware
+
+用于拓展 Modern.js 内置的 Web Server。 未来 UnstableMiddleware 将替代 [Middleware](/apis/app/runtime/web-server/middleware)
+
+## 使用
+
+```ts title="server/index.ts"
+import { UnstableMiddleware } from '@modern-js/runtime/server';
+
+export const unstableMiddlewares: UnstableMiddleware = [];
+```
+
+## 类型
+
+**UnstableMiddleware**
+
+```ts
+type UnstableMiddleware<
+  V extends Record<string, unknown> = Record<string, unknown>,
+> = (
+  c: UnstableMiddlewareContext<V>,
+  next: UnstableNext,
+) => Promise<void | Response>;
+```
+
+**UnstableMiddlewareContext**
+
+```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>;
+  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>;
+};
+```
+
+**UnstableNext**
+
+```ts
+type UnstableNext = () => Promise<void>;
+```
+
+## 用例
+
+### web server 耗时打点
+
+```ts
+import { UnstableMiddleware } from '@modern-js/runtime/server';
+
+const time: UnstableMiddleware = async (c, next) => {
+  const start = Date.now();
+
+  await next();
+
+  const end = Date.now();
+
+  console.log(`${end - start}`);
+};
+
+export const unstableMiddlewares: UnstableMiddleware = [time];
+```
+
+### 注入服务端数据，供页面 dataLoader 消费
+
+```ts title="shared/index.ts"
+export type Vars = {
+  message: string;
+};
+```
+
+```ts title="server/index.ts"
+import {
+  UnstableMiddleware,
+  UnstableMiddlewareContext,
+} from '@modern-js/runtime/server';
+import type { Vars } from '../shared/index';
+
+const setPayload: UnstableMiddleware = async (
+  c: UnstableMiddlewareContext<Vars>,
+  next,
+) => {
+  c.set('message', 'facker');
+
+  await next();
+};
+
+export const unstableMiddlewares: UnstableMiddleware = [setPayload];
+```
+
+```ts title="src/routes/page.data.ts"
+import type { Payload } from '../../shared/index';
+import { LoaderFunctionArgs } from '@modern-js/runtime/router';
+
+export const loader = async ({ context }: LoaderFunctionArgs<Vars>) => {
+  const message = context?.get('message');
+
+  // ...
+};
+```
+
+### 重定向
+
+```ts
+import { UnstableMiddleware } from '@modern-js/runtime/server';
+
+const auth: UnstableMiddleware = async (c, next) => {
+  const user = getUser(c.request);
+
+  if (!user) {
+    return c.redirect('/login');
+  }
+
+  await next();
+};
+
+export const unstableMiddlewares: UnstableMiddleware = [auth];
+```

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

@@ -76,6 +76,12 @@ export const afterRender: AfterRenderHook = (ctx, next) => {
 
 对于某些项目，可能在服务端有更多的需求，Modern.js 提供了 Middleware 为 Web Server 添加前置中间件。它只能运行在 Node 环境下，因此如果项目被部署到其他环境中，如 Worker 环境，则不可以使用 Middleware。
 
+:::note
+下一个大版本，Modern.js 将会使用新 Middleware 来替代该写法。
+
+推荐使用 [UnstableMiddleware](/guides/advanced-features/web-server.html#unstablemiddleware) 处理页面请求。
+:::
+
 Modern.js 默认提供了一套 API 供项目使用：
 
 ```ts
@@ -102,6 +108,33 @@ export const middleware: Middlewre = (context, next) => {
 
 **总的来说，CSR 项目中，使用 Hook 基本能满足简单场景的所有需求。SSR 项目中，可以使用 Middleware 做更复杂的 Node 扩展。**
 
+### UnstableMiddleware
+
+Modern.js 将提供新 Middleware 为 Web Server 添加前置中间件，支持在处理页面的前后执行自定义逻辑。
+
+```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];
+```
+
+:::note
+详细 API 和更多用法查看 [UnstableMiddleware](/apis/app/runtime/web-server/unstable_middleware)
+:::
+
 ## 通过 BFF 托管页面请求
 
 第二种方式，是利用 BFF 来托管页面渲染，这种方式下，所有的请求都会先打到 BFF 的服务。

package/package.json

@@ -15,17 +15,17 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.49.3",
+  "version": "2.50.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "2.49.3"
+    "@modern-js/sandpack-react": "2.50.0"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.49.3"
+    "@modern-js/builder-doc": "^2.50.0"
   },
   "devDependencies": {
     "classnames": "^2",
@@ -39,8 +39,8 @@
     "@rspress/shared": "1.18.2",
     "@types/node": "^16",
     "@types/fs-extra": "9.0.13",
-    "@modern-js/builder-doc": "2.49.3",
-    "@modern-js/doc-plugin-auto-sidebar": "2.49.3"
+    "@modern-js/doc-plugin-auto-sidebar": "2.50.0",
+    "@modern-js/builder-doc": "2.50.0"
   },
   "scripts": {
     "dev": "rspress dev",