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

package/docs/en/plugin/server-plugins/api.mdx

@@ -1,3 +1,212 @@
 # Plugin API
 
-Comming soon...
+Modern.js's Server plugins allow you to extend and customize functionality during the server-side request processing phase, such as adding middleware, modifying request responses, etc.
+
+:::info
+
+Server plugins need to be configured via the `plugins` field in `server/modern.server.ts`.
+
+:::
+
+## Plugin Basic Structure
+
+A typical Server plugin structure is as follows:
+
+```typescript
+import type { ServerPlugin } from '@modern-js/server-runtime';
+
+const myServerPlugin = (): ServerPlugin => ({
+  name: '@my-org/my-server-plugin', // Plugin name, ensure uniqueness
+  setup: api => {
+    // Use the API here to register hooks, add middleware, etc.
+    api.onPrepare(() => {
+      const { middlewares } = api.getServerContext();
+      middlewares?.push({
+        name: 'my-middleware',
+        handler: async (c, next) => {
+          console.log('Processing request...');
+          await next();
+        },
+      });
+    });
+  },
+});
+
+export default myServerPlugin;
+```
+
+- `name`: A unique identifier for the plugin.
+- The `setup` function receives an `api` object, which provides all available Server plugin APIs.
+
+## Information Retrieval
+
+#### `api.getServerContext`
+
+Gets the context information of the Modern.js server.
+
+- **Returns:** A `ServerContext` object containing the following fields:
+
+| Field Name          | Type              | Description                           |
+| ------------------- | ----------------- | ------------------------------------- |
+| `middlewares`       | `MiddlewareObj[]` | Middleware list                       |
+| `renderMiddlewares` | `MiddlewareObj[]` | Render middleware list                |
+| `routes`            | `ServerRoute[]`   | Server routing information            |
+| `appDirectory`      | `string`          | Absolute path to the project root    |
+| `apiDirectory`      | `string`          | Absolute path to the API module dir  |
+| `lambdaDirectory`   | `string`          | Absolute path to the Lambda module dir|
+| `sharedDirectory`   | `string`          | Absolute path to the shared module dir|
+| `distDirectory`     | `string`          | Absolute path to the output directory|
+| `plugins`            | `ServerPlugin[]`  | List of currently registered plugins  |
+
+- **Example:**
+
+```typescript
+api.onPrepare(() => {
+  const serverContext = api.getServerContext();
+  console.log(`App directory: ${serverContext.appDirectory}`);
+  console.log(`${serverContext.plugins.length} plugins registered`);
+});
+```
+
+:::info
+The context information returned by `getServerContext` is read-only. Use `updateServerContext` if you need to modify it.
+:::
+
+---
+
+#### `api.getServerConfig`
+
+Gets the server configuration defined by the user in the `server/modern.server.ts` file.
+
+- **Returns:** The user-defined server configuration object.
+- **Example:**
+
+```typescript
+api.onPrepare(() => {
+  const serverConfig = api.getServerConfig();
+  if (serverConfig.middlewares) {
+    console.log('User has customized middleware configuration');
+  }
+});
+```
+
+---
+
+#### `api.getHooks`
+
+Gets all registered hook functions.
+
+- **Returns:** An object containing all hook functions.
+- **Example:**
+
+```typescript
+const hooks = api.getHooks();
+// Manually trigger the onPrepare hook
+await hooks.onPrepare.call();
+```
+
+:::warning
+In custom plugins, you can only manually call the hooks registered by the corresponding plugin and cannot call official hooks to avoid affecting the normal execution order of the application.
+:::
+
+---
+
+
+## Context Modification
+
+#### `api.updateServerContext`
+
+Updates the server context information.
+
+- **Type:** `api.updateServerContext(updateContext: DeepPartial<ServerContext>)`
+- **Parameters:**
+  - `updateContext`: The context object to update (partial update).
+- **Execution Phase:** Can be used at any stage.
+- **Example:**
+
+```typescript
+api.onPrepare(() => {
+  const context = api.getServerContext();
+  api.updateServerContext({
+    middlewares: [
+      ...context.middlewares,
+      {
+        name: 'new-middleware',
+        handler: async (c, next) => {
+          await next();
+        },
+      },
+    ],
+  });
+});
+```
+
+---
+
+
+## Lifecycle Hooks
+
+#### `api.onPrepare`
+
+Adds additional logic during the server preparation phase.
+
+- **Type:** `api.onPrepare(prepareFn: () => void | Promise<void>)`
+- **Parameters:**
+  - `prepareFn`: A preparation function, without parameters, can be asynchronous.
+- **Execution Phase:** After the server completes configuration validation and before applying middleware.
+- **Example:**
+
+```typescript
+api.onPrepare(async () => {
+  const { middlewares } = api.getServerContext();
+
+  // Add custom middleware
+  middlewares.push({
+    name: 'request-logger',
+    handler: async (c, next) => {
+      const start = Date.now();
+      await next();
+      const duration = Date.now() - start;
+      console.log(`Request duration: ${duration}ms`);
+    },
+  });
+});
+```
+
+:::info
+In the `onPrepare` hook, you can modify the context object returned by `getServerContext()` (such as `middlewares`, `renderMiddlewares`), and these modifications will take effect when the server starts.
+:::
+
+---
+
+#### `api.onReset`
+
+Adds additional logic when the server resets.
+
+- **Type:** `api.onReset(resetFn: (params: { event: ResetEvent }) => void | Promise<void>)`
+- **Parameters:**
+  - `resetFn`: A reset handler function that receives reset event parameters.
+    - `event.type`: Event type, possible values:
+      - `'repack'`: Repack event
+      - `'file-change'`: File change event
+    - `event.payload`: When `type` is `'file-change'`, contains an array of file change information.
+- **Execution Phase:** When files change or repack is needed.
+- **Example:**
+
+```typescript
+api.onReset(async ({ event }) => {
+  if (event.type === 'file-change') {
+    console.log('File changes detected:', event.payload);
+    // Perform cleanup or re-initialization operations
+  } else if (event.type === 'repack') {
+  }
+});
+```
+
+---
+
+
+## Other Notes
+
+- Refer to [Server Plugin Lifecycle](./life-cycle.mdx) to understand the execution order of plugin hooks.
+- The execution order of middleware can be controlled through the `order` field (`'pre'`, `'default'`, `'post'`), or through the `before` field to specify execution before other middleware.

package/docs/en/plugin/server-plugins/life-cycle.mdx

@@ -1,3 +1,43 @@
 # Life Cycle
 
-Comming soon...
+import Mermaid from '@site/src/components/Mermaid';
+
+<Mermaid>
+{`
+flowchart TD
+    init{{"Server Initialization"}}
+    load_config(Load User Config File)
+    server_plugin(Load Server Plugins<br><sub>Plugins registered in config file<br>Server plugins registered by CLI plugins<br>Plugins used by plugins</sub>)
+    registry_hooks(Register Hooks Functions<br><sub>Execute plugin setup function, register Hooks defined in plugins, logic in plugin setup will also execute here</sub>)
+
+    modifyConfig(modifyConfig<br><sub>Modify server configuration</sub>)
+    onPrepare(onPrepare<br><sub>Execute after server completes configuration validation, before applying middleware</sub>)
+    apply_middlewares(Apply Middleware<br><sub>Apply middleware according to order and before rules</sub>)
+
+    init --> load_config
+    load_config --> server_plugin
+    server_plugin --> registry_hooks
+    registry_hooks --> modifyConfig
+    modifyConfig --> onPrepare
+    onPrepare --> apply_middlewares
+
+    style init fill:#FDE68A,font-size:10px;
+    style load_config stroke-dasharray:5 5,fill:#86EFAC,font-size:10px;
+    style server_plugin stroke-dasharray:5 5,fill:#86EFAC,font-size:10px;
+    style registry_hooks stroke-dasharray:5 5,fill:#9CA3AF,font-size:10px;
+    style modifyConfig font-size:10px;
+    style onPrepare font-size:10px;
+    style apply_middlewares font-size:10px;
+`}
+</Mermaid>
+
+:::info
+
+**Runtime Hooks**
+
+The `onReset` hook is triggered at runtime when files change or code recompilation (rspack) is needed. It is not part of the initialization flow, so it is not shown in the diagram above.
+
+- **Trigger Timing**: File changes (`event.type: 'file-change'`) or code recompilation (rspack) completion (`event.type: 'repack'`)
+- **Use Cases**: Clearing cache, re-initializing resources, etc.
+
+:::

package/docs/en/tutorials/_meta.json

@@ -1,14 +1,4 @@
 [
-  {
-    "type": "dir",
-    "name": "foundations",
-    "label": "foundations"
-  },
-  {
-    "type": "dir",
-    "name": "first-app",
-    "label": "first-app"
-  },
   {
     "type": "dir",
     "name": "examples",

package/docs/en/tutorials/examples/csr-auth.mdx

@@ -4,7 +4,7 @@ title: Route Authorization
 
 # Route Authorization
 
-Modern.js defaults to the convention-based routing based on React Router 6. For more details, please refer to [Routing](/guides/basic-features/routes.html#routing-scheme).
+Modern.js defaults to the convention-based routing based on React Router v7. For more details, please refer to [Routing](/guides/basic-features/routes/routes#routing).
 
 In a web application, if there are multiple routes, we may need to authorize access to some of them before accessing them. For example, in the following scenario:
 

package/docs/en/tutorials/foundations/introduction.mdx

@@ -3,36 +3,20 @@ title: Introduction
 sidebar_position: 1
 ---
 
-# Introduction
+# Modern.js Example Library
 
-Welcome to Modern.js tutorials!
+Welcome to Modern.js Example Library! Here you'll find practical code examples to help you get started with Modern.js quickly.
 
-After reading this section, you will have an initial understanding of Modern.js and use Modern.js to create your first application.
+If you're new to Modern.js, we recommend reading the [Modern.js Introduction](/guides/get-started/introduction) first.
 
-## What is Modern.js?
-
-If you don't know Modern.js yet, please can read [Modern.js Introduction](/guides/get-started/introduction) first.
-
-## Tutorial
-
-We have prepared a tutorial on creating a "contact list app" that you can follow step by step to create an app and learn about the following practices in Modern.js:
-
-- Creating a project
-- Using the antd component library
-- Integrating Tailwind CSS
-- Client-side routing
-- Data fetching
-- State Management
-- Container components
-- New entry
-- ...
-
-## Case Studies
-
-We offer some commonly used case studies for your reference during the development process. Here you can find some usage patterns of the feature combinations provided by Modern.js. We will continue to improve the case studies here.
+## 📚 Example List
 
 import ExampleList from '@site-docs-en/components/turtorials-example-list';
 
 <ExampleList />
 
-Let's start from [creating a project](tutorials/first-app/c01-start) now!
+---
+
+## 💡 Contribute Examples
+
+If you have good examples to share, feel free to submit a PR on [GitHub](https://github.com/web-infra-dev/modern.js)!

package/docs/zh/{_meta.json → _nav.json}

@@ -1,32 +1,36 @@
 [
   {
-    "text": "guide",
+    "text": "指南",
     "link": "/guides/get-started/introduction",
     "activeMatch": "/guides/"
   },
   {
-    "text": "configure",
+    "text": "配置",
     "link": "/configure/app/usage",
     "activeMatch": "/configure/"
   },
   {
-    "text": "plugin-menu",
+    "text": "插件",
     "link": "/plugin/introduction",
     "activeMatch": "/plugin/"
   },
   {
-    "text": "apis",
+    "text": "API",
     "link": "/apis/app/commands",
     "activeMatch": "/apis/"
   },
   {
-    "text": "tutorials",
+    "text": "示例",
     "link": "/tutorials/foundations/introduction",
     "activeMatch": "/tutorials/"
   },
   {
-    "text": "community",
+    "text": "社区",
     "link": "/community/showcase",
     "activeMatch": "/community/"
+  },
+  {
+    "text": "Modern.js 2.x 文档",
+    "link": "https://modernjs.dev/zh/guides/get-started/introduction.html"
   }
 ]

package/docs/zh/apis/app/commands.mdx

@@ -19,7 +19,6 @@ Options:
   -e --entry <entry>    指定入口，只编译特定的页面
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
   -h, --help            显示命令帮助
-  --analyze             分析构建产物体积，查看各个模块打包后的大小
   --web-only            仅启动 Web 服务
   --api-only            仅启动 API 接口服务
 ```
@@ -79,36 +78,13 @@ Options:
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
   -h, --help  显示命令帮助
   -w --watch  开启 watch 模式, 监听文件变更并重新构建
-  --analyze   分析构建产物体积，查看各个模块打包后的大小
 ```
 
-### 分析构建产物体积
-
-执行 `npx modern build --analyze` 命令，可以在打包生产环境代码的同时，产出一个分析构建产物体积的 HTML 文件：
-
-```
-Bundle Analyzer saved report to /example/dist/report.html
-
-info    Production file sizes:
-
-  File                                      Size         Gzipped
-  dist/static/js/lib-react.09721b5c.js      152.6 kB     49.0 kB
-  dist/html/main/index.html                 5.8 kB       2.5 kB
-  dist/static/js/main.3568a38e.js           3.5 kB       1.4 kB
-  dist/static/css/main.03221f72.css         1.4 kB       741 B
-```
-
-手动在浏览器中打开上述 HTML 文件，可以看到打包产物的瓦片图，并进行包体积分析和优化：
-
-<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/mwa-build-analyze-8784f762c1ab0cb20935829d5f912c4c.png" />
-
-> 该功能基于 [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) 实现。
-
 ## modern new
 
 `modern new` 命令用于在已有项目中添加项目元素。
 
-比如添加应用入口、启用一些可选功能如 Tailwind CSS、微前端开发模式等。
+比如添加应用入口、启用一些可选功能如 BFF、微前端开发模式等。
 
 ```bash
 Usage: modern new [options]
@@ -142,8 +118,7 @@ $ npx modern new
 $ npx modern new
 ? 请选择你想要的操作 启用可选功能
 ? 请选择功能名称 (Use arrow keys)
-❯ 启用 「Tailwind CSS」 支持
-  启用「BFF」功能
+❯ 启用「BFF」功能
   启用「微前端」模式
 ```
 
@@ -175,7 +150,7 @@ Options:
 
 ## modern inspect
 
-`modern inspect` 命令用于查看项目的 Modern.js 配置、[Rsbuild 配置](https://rsbuild.rs/zh/config/index) 以及 webpack 或 Rspack 配置。
+`modern inspect` 命令用于查看项目的 Modern.js 配置、[Rsbuild 配置](https://rsbuild.rs/zh/config/index) 以及 Rspack 配置。
 
 ```bash
 Usage: modern inspect [options]
@@ -192,7 +167,7 @@ Options:
 
 - `modern.js.config.mjs`: 表示当前使用的 Modern.js 配置。
 - `rsbuild.config.mjs`: 表示在构建时使用的 Rsbuild 配置。
-- `webpack.config.web.mjs`: 表示在构建时使用的 webpack 配置。
+- `rspack.config.web.mjs`: 表示在构建时使用的 Rspack 配置。
 
 ```bash
 ➜ npx modern inspect
@@ -200,7 +175,7 @@ Options:
 Inspect config succeed, open following files to view the content:
 
   - Rsbuild Config: /root/my-project/dist/rsbuild.config.mjs
-  - Webpack Config (web): /root/my-project/dist/webpack.config.web.mjs
+  - Rspack Config (web): /root/my-project/dist/rspack.config.web.mjs
   - Modern.js Config: /root/my-project/dist/modern.js.config.mjs
 ```
 
@@ -222,7 +197,7 @@ modern inspect --verbose
 
 ### SSR 构建配置
 
-如果项目开启了 SSR 能力，则在 `dist` 目录会另外生成一份 `webpack.config.node.mjs` 文件，对应 SSR 构建时的 webpack 配置。
+如果项目开启了 SSR 能力，则在 `dist` 目录会另外生成一份 `rspack.config.node.mjs` 文件，对应 SSR 构建时的 Rspack 配置。
 
 ```bash
 ➜ npx modern inspect
@@ -230,8 +205,8 @@ modern inspect --verbose
 Inspect config succeed, open following files to view the content:
 
   - Rsbuild Config: /root/my-project/dist/rsbuild.config.mjs
-  - Webpack Config (web): /root/my-project/dist/webpack.config.web.mjs
-  - Webpack Config (node): /root/my-project/dist/webpack.config.node.mjs
+  - Rspack Config (web): /root/my-project/dist/rspack.config.web.mjs
+  - Rspack Config (node): /root/my-project/dist/rspack.config.node.mjs
   - Modern.js Config: /root/my-project/dist/modern.js.config.mjs
 ```
 

package/docs/zh/apis/app/hooks/src/entry.mdx

@@ -5,10 +5,6 @@ sidebar_position: 4
 
 # entry.[tj]sx
 
-:::info
-使用该文件需要开启 [source.enableCustomEntry](/configure/app/source/enable-custom-entry)。
-:::
-
 通常情况下[`routes/`](/apis/app/hooks/src/routes.html) 和 [`App.[tj]sx`](/apis/app/hooks/src/app) 钩子文件已经能满足我们的需求，当我们需要在组件渲染之前添加自定义行为或者完全接管 webpack 打包入口时，可以在 `src` 或者入口目录下放置 `entry.[tj]s`。下面分两种情况进行讨论。
 
 ## 在组件渲染前添加自定义行为
@@ -22,7 +18,7 @@ import { render } from '@modern-js/runtime/browser';
 const ModernRoot = createRoot();
 
 async function beforeRender() {
-   // todo
+  // todo
 }
 
 beforeRender().then(() => {

package/docs/zh/apis/app/hooks/src/entry.server.mdx

@@ -5,10 +5,6 @@ sidebar_position: 5
 
 # entry.server.[tj]sx
 
-:::info
-使用该文件需要开启 [source.enableCustomEntry](/configure/app/source/enable-custom-entry)。
-:::
-
 当项目开启 `server.ssr` 时，Modern.js 生成一个默认的 Server-Side 入口。示例代码如下：
 
 ```tsx title="entry.server.tsx"
@@ -35,7 +31,10 @@ export default createRequestHandler(handleRequest);
 如果用户需自定义 Server-Side Rendering 入口，可以在 `src/entry.server.ts`、`src/{entryName}/entry.server.ts` 中自定义 server 入口。
 
 ```tsx title="src/entry.server.tsx"
-import { renderString, createRequestHandler } from '@modern-js/runtime/ssr/server';
+import {
+  renderString,
+  createRequestHandler,
+} from '@modern-js/runtime/ssr/server';
 import type { HandleRequest } from '@modern-js/runtime/ssr/server';
 
 const handleRequest: HandleRequest = async (request, ServerRoot, options) => {

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

@@ -4,7 +4,7 @@ sidebar_position: 2
 ---
 # routes/
 
-应用使用[约定式路由](guides/basic-features/routes.html#约定式路由)时的入口标识。
+应用使用[约定式路由](/guides/basic-features/routes/routes#约定式路由)时的入口标识。
 
 约定式路由以 `routes/` 为约定的入口， 会分析 `src/routes` 目录下的文件得到客户端路由配置。
 
@@ -85,6 +85,6 @@ export default () => {
 ```
 
 :::note
-`<Outlet>` 是 React Router 6 中新的 API，详情可以查看 [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
+`<Outlet>` 是 React Router v7 中新的 API，详情可以查看 [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
 
 :::

package/docs/zh/apis/app/runtime/_meta.json

@@ -5,24 +5,12 @@
     "label": "Core",
     "collapsed": true
   },
-  {
-    "type": "dir",
-    "name": "app",
-    "label": "App",
-    "collapsed": true
-  },
   {
     "type": "dir",
     "name": "router",
     "label": "Router",
     "collapsed": true
   },
-  {
-    "type": "dir",
-    "name": "model",
-    "label": "Model",
-    "collapsed": true
-  },
   {
     "type": "dir",
     "name": "ssr",
@@ -35,12 +23,6 @@
     "label": "BFF",
     "collapsed": true
   },
-  {
-    "type": "dir",
-    "name": "web-server",
-    "label": "Web Server",
-    "collapsed": true
-  },
   {
     "type": "dir",
     "name": "utility",

package/docs/zh/apis/app/runtime/bff/use-hono-context.mdx

@@ -9,7 +9,7 @@ title: useHonoContext
 ## 使用姿势
 
 ```ts
-import { useHonoContext } from '@modern-js/plugin-bff/hono';
+import { useHonoContext } from '@modern-js/plugin-bff/server';
 ```
 
 ## 函数签名
@@ -21,7 +21,7 @@ import { useHonoContext } from '@modern-js/plugin-bff/hono';
 开发者可以通过 `context` 获取更多的请求信息，例如设置响应头：
 
 ```ts
-import { useHonoContext } from '@modern-js/plugin-bff/hono';
+import { useHonoContext } from '@modern-js/plugin-bff/server';
 
 export async function get() {
   const c = useHonoContext();

package/docs/zh/apis/app/runtime/utility/css-in-js.mdx

@@ -1,6 +1,7 @@
 ---
 title: CSS-In-JS API
 ---
+
 # CSS-In-JS API
 
 使用 Style Component 来编写组件 CSS。
@@ -8,7 +9,7 @@ title: CSS-In-JS API
 ## 使用姿势
 
 ```ts
-import styled from '@modern-js/runtime/styled';
+import styled from '@modern-js/plugin-styled-components/styled';
 ```
 
 ## 函数签名
@@ -18,7 +19,7 @@ import styled from '@modern-js/runtime/styled';
 ## 示例
 
 ```tsx
-import styled from '@modern-js/runtime/styled';
+import styled from '@modern-js/plugin-styled-components/styled';
 
 const Button = styled.button`
   background: palevioletred;

package/docs/zh/community/blog/v2-release-note.mdx

@@ -232,8 +232,6 @@ Modern.js 中的部分代码实现参考了社区中的开源项目，我们对
 
 - `@modern-js/bundle-require`: 修改自 [bundle-require](https://github.com/egoist/bundle-require)。
 - `@modern-js/plugin`: hook API 的实现参考了 [farrow-pipeline](https://github.com/farrow-js/farrow/tree/master/packages/farrow-pipeline)。
-- `@modern-js/builder`: moduleScope 和 fileSize 插件参考了 [create-react-app](https://github.com/facebook/create-react-app)，TsConfigPathsPlugin 参考了 [tsconfig-paths-webpack-plugin](https://github.com/dividab/tsconfig-paths-webpack-plugin)，generateMetaTags 函数参考了 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin)。
-- `@modern-js/plugin-testing`: jest runner 参考了 [jest-cli](https://github.com/facebook/jest/blob/fdc74af37235354e077edeeee8aa2d1a4a863032/packages/jest-cli/src/cli/index.ts#L21)。
 - `@modern-js/plugin-data-loader`: 部分实现参考了 [remix](https://github.com/remix-run/remix)。
 
 ## 最后