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

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

@@ -0,0 +1,212 @@
+# 插件 API
+
+Modern.js 的 Server 插件允许您在服务端请求处理阶段扩展和定制功能，例如添加中间件、修改请求响应等。
+
+:::info
+
+Server 插件需要通过 `server/modern.server.ts` 中的 `plugins` 字段配置。
+
+:::
+
+## 插件基础结构
+
+一个典型的 Server 插件结构如下：
+
+```typescript
+import type { ServerPlugin } from '@modern-js/server-runtime';
+
+const myServerPlugin = (): ServerPlugin => ({
+  name: '@my-org/my-server-plugin', // 插件名称，确保唯一性
+  setup: api => {
+    // 在这里使用 API 注册钩子、添加中间件等
+    api.onPrepare(() => {
+      const { middlewares } = api.getServerContext();
+      middlewares?.push({
+        name: 'my-middleware',
+        handler: async (c, next) => {
+          console.log('处理请求...');
+          await next();
+        },
+      });
+    });
+  },
+});
+
+export default myServerPlugin;
+```
+
+- `name`： 插件的唯一标识符。
+- `setup` 函数接收一个 `api` 对象，该对象提供了所有可用的 Server 插件 API。
+
+## 信息获取
+
+#### `api.getServerContext`
+
+获取 Modern.js 服务器的上下文信息。
+
+- **返回值：** `ServerContext` 对象，包含以下字段：
+
+| 字段名            | 类型                | 描述                           |
+| ----------------- | ------------------- | ------------------------------ |
+| `middlewares`     | `MiddlewareObj[]`   | 中间件列表                     |
+| `renderMiddlewares` | `MiddlewareObj[]` | 渲染中间件列表                 |
+| `routes`          | `ServerRoute[]`     | 服务器路由信息                 |
+| `appDirectory`    | `string`            | 项目根目录的绝对路径           |
+| `apiDirectory`    | `string`            | API 模块目录的绝对路径         |
+| `lambdaDirectory` | `string`            | Lambda 模块目录的绝对路径     |
+| `sharedDirectory` | `string`            | 公共模块目录的绝对路径         |
+| `distDirectory`   | `string`            | 项目产物输出目录的绝对路径     |
+| `plugins`         | `ServerPlugin[]`    | 当前已注册的插件列表           |
+
+- **示例：**
+
+```typescript
+api.onPrepare(() => {
+  const serverContext = api.getServerContext();
+  console.log(`应用目录：${serverContext.appDirectory}`);
+  console.log(`已注册 ${serverContext.plugins.length} 个插件`);
+});
+```
+
+:::info
+`getServerContext` 返回的上下文信息是只读的，如需修改请使用 `updateServerContext`。
+:::
+
+---
+
+#### `api.getServerConfig`
+
+获取用户在 `server/modern.server.ts` 文件中定义的服务器配置。
+
+- **返回值：** 用户定义的服务器配置对象。
+- **示例：**
+
+```typescript
+api.onPrepare(() => {
+  const serverConfig = api.getServerConfig();
+  if (serverConfig.middlewares) {
+    console.log('用户自定义了中间件配置');
+  }
+});
+```
+
+---
+
+#### `api.getHooks`
+
+获取所有已注册的钩子函数。
+
+- **返回值：** 包含所有钩子函数的对象。
+- **示例：**
+
+```typescript
+const hooks = api.getHooks();
+// 手动触发 onPrepare 钩子
+await hooks.onPrepare.call();
+```
+
+:::warning
+在自定义插件中，只能手动调用对应插件注册的钩子，不能调用官方钩子，以免影响正常应用的执行顺序。
+:::
+
+---
+
+
+## 上下文修改
+
+#### `api.updateServerContext`
+
+更新服务器上下文信息。
+
+- **类型：** `api.updateServerContext(updateContext: DeepPartial<ServerContext>)`
+- **参数：**
+  - `updateContext`： 要更新的上下文对象（部分更新）。
+- **执行阶段：** 可在任何阶段使用。
+- **示例：**
+
+```typescript
+api.onPrepare(() => {
+  const context = api.getServerContext();
+  api.updateServerContext({
+    middlewares: [
+      ...context.middlewares,
+      {
+        name: 'new-middleware',
+        handler: async (c, next) => {
+          await next();
+        },
+      },
+    ],
+  });
+});
+```
+
+---
+
+
+## 生命周期钩子
+
+#### `api.onPrepare`
+
+在服务器准备阶段添加额外的逻辑。
+
+- **类型：** `api.onPrepare(prepareFn: () => void | Promise<void>)`
+- **参数：**
+  - `prepareFn`： 准备函数，无参数，可异步。
+- **执行阶段：** 在服务器完成配置校验之后，应用中间件之前。
+- **示例：**
+
+```typescript
+api.onPrepare(async () => {
+  const { middlewares } = api.getServerContext();
+
+  // 添加自定义中间件
+  middlewares.push({
+    name: 'request-logger',
+    handler: async (c, next) => {
+      const start = Date.now();
+      await next();
+      const duration = Date.now() - start;
+      console.log(`请求耗时: ${duration}ms`);
+    },
+  });
+});
+```
+
+:::info
+在 `onPrepare` 钩子中，可以修改 `getServerContext()` 返回的上下文对象（如 `middlewares`、`renderMiddlewares`），这些修改会在服务器启动时生效。
+:::
+
+---
+
+#### `api.onReset`
+
+在服务器重置时添加额外的逻辑。
+
+- **类型：** `api.onReset(resetFn: (params: { event: ResetEvent }) => void | Promise<void>)`
+- **参数：**
+  - `resetFn`： 重置处理函数，接收重置事件参数。
+    - `event.type`： 事件类型，可能的值：
+      - `'repack'`： 重新打包事件
+      - `'file-change'`： 文件变化事件
+    - `event.payload`： 当 `type` 为 `'file-change'` 时，包含文件变化信息数组。
+- **执行阶段：** 当文件发生变化或需要重新打包时。
+- **示例：**
+
+```typescript
+api.onReset(async ({ event }) => {
+  if (event.type === 'file-change') {
+    console.log('检测到文件变化:', event.payload);
+    // 执行清理或重新初始化操作
+  } else if (event.type === 'repack') {
+  }
+});
+```
+
+---
+
+
+## 其他说明
+
+- 可以参考 [Server 插件生命周期](./life-cycle.mdx) 了解插件钩子的执行顺序。
+- 中间件的执行顺序可以通过 `order` 字段控制（`'pre'`、`'default'`、`'post'`），也可以通过 `before` 字段指定在其他中间件之前执行。

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

@@ -0,0 +1,43 @@
+# 生命周期
+
+import Mermaid from '@site/src/components/Mermaid';
+
+<Mermaid>
+{`
+flowchart TD
+    init{{"Server 初始化"}}
+    load_config(加载用户配置文件)
+    server_plugin(加载 Server 插件<br><sub>配置文件中注册的插件<br>CLI 插件注册的 Server 插件<br>插件中使用的插件</sub>)
+    registry_hooks(注册 Hooks 函数<br><sub>执行插件 setup 函数，注册插件中定义的 Hook, 插件 setup 中逻辑也会在这里执行</sub>)
+
+    modifyConfig(modifyConfig<br><sub>修改服务器配置</sub>)
+    onPrepare(onPrepare<br><sub>在服务器完成配置校验之后，应用中间件之前执行</sub>)
+    apply_middlewares(应用中间件<br><sub>按照 order 和 before 规则应用中间件</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
+
+**运行时钩子**
+
+`onReset` 钩子在运行时触发，当文件发生变化或需要代码重新编译(Rspack)完成时会被调用。它不属于初始化流程，因此未在上图中展示。
+
+- **触发时机**：文件变化（`event.type: 'file-change'`）或代码重新编译(Rspack)完成（`event.type: 'repack'`）
+- **使用场景**：清理缓存、重新初始化资源等
+
+:::

package/docs/zh/tutorials/_meta.json

@@ -0,0 +1,7 @@
+[
+  {
+    "type": "dir",
+    "name": "examples",
+    "label": "examples"
+  }
+]

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

@@ -0,0 +1,31 @@
+---
+title: 路由鉴权
+---
+
+# 路由鉴权
+
+Modern.js 默认提供的路由方式是基于 React Router v7 的约定式路由，具体可查看[路由方案](/guides/basic-features/routes/routes#路由方案)。
+
+在一个 Web 应用中如果存在多个路由，我们可能需要对部分路由进行鉴权后才能访问。例如下面这个案例：
+
+- 访问 `/` 路由，无需鉴权，可直接访问。
+- 访问 `/protected` 路由，需要鉴权，如果无，自动跳转到 `/login` 路由，登录成功后返回 `/protected`。
+
+import Sandpack from '@site/src/components/Sandpack';
+import srcRoutesPageText from '../../../../src/sandbox/csr-auth/src/routes/page-tsx.txt';
+import srcRoutesLayoutText from '../../../../src/sandbox/csr-auth/src/routes/layout-tsx.txt';
+import srcRoutesAuthText from '../../../../src/sandbox/csr-auth/src/routes/Auth-tsx.txt';
+import srcRoutesFakeAuthText from '../../../../src/sandbox/csr-auth/src/routes/fakeAuth-ts.txt';
+import srcRoutesProtectedPageText from '../../../../src/sandbox/csr-auth/src/routes/protected/page-tsx.txt';
+import srcRoutesLoginPageText from '../../../../src/sandbox/csr-auth/src/routes/login/page-tsx.txt';
+
+<Sandpack template="web-app" files={{
+  '/src/routes/page.tsx': srcRoutesPageText,
+  '/src/routes/layout.tsx': srcRoutesLayoutText,
+  '/src/routes/Auth.tsx': srcRoutesAuthText,
+  '/src/routes/fakeAuth.ts': srcRoutesFakeAuthText,
+  '/src/routes/protected/page.tsx': srcRoutesProtectedPageText,
+  '/src/routes/login/page.tsx': srcRoutesLoginPageText,
+}}>
+
+</Sandpack>

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

@@ -0,0 +1,22 @@
+---
+title: 介绍
+sidebar_position: 1
+---
+
+# Modern.js 示例库
+
+欢迎来到 Modern.js 示例库！这里提供实用的代码示例，帮助你快速上手 Modern.js。
+
+如果你是第一次接触 Modern.js，建议先阅读 [Modern.js 介绍](/guides/get-started/introduction)。
+
+## 📚 示例列表
+
+import ExampleList from '@site-docs/components/turtorials-example-list';
+
+<ExampleList />
+
+---
+
+## 💡 贡献示例
+
+如果你有好的示例想要分享，欢迎通过 [GitHub](https://github.com/web-infra-dev/modern.js) 提交 PR！

package/i18n.json

@@ -0,0 +1,142 @@
+{
+  "guide": {
+    "zh": "指南",
+    "en": "Guide"
+  },
+  "tutorials": {
+    "zh": "教程",
+    "en": "Tutorials"
+  },
+  "configure": {
+    "zh": "配置",
+    "en": "Config"
+  },
+  "plugin-menu": {
+    "zh": "插件",
+    "en": "Plugin"
+  },
+  "apis": {
+    "zh": "API",
+    "en": "API"
+  },
+  "community": {
+    "zh": "社区",
+    "en": "Community"
+  },
+  "gettingStarted": {
+    "zh": "开始",
+    "en": "Start"
+  },
+  "concept": {
+    "zh": "核心概念",
+    "en": "Core Concept"
+  },
+  "basic": {
+    "zh": "基础功能",
+    "en": "Basic Features"
+  },
+  "advanced": {
+    "zh": "进阶功能",
+    "en": "Advanced Features"
+  },
+  "topic": {
+    "zh": "专题详解",
+    "en": "Topic Detail"
+  },
+  "troubleshooting": {
+    "zh": "常见问题",
+    "en": "FAQ"
+  },
+  "data-solution": {
+    "zh": "数据管理",
+    "en": "Data Solution"
+  },
+  "rendering": {
+    "zh": "渲染",
+    "en": "Rendering"
+  },
+  "css-solution": {
+    "zh": "样式开发",
+    "en": "Styling"
+  },
+  "debug": {
+    "zh": "调试",
+    "en": "Debug"
+  },
+  "static-assets": {
+    "zh": "引用静态资源",
+    "en": "Import Static Assets"
+  },
+  "testing": {
+    "zh": "测试",
+    "en": "Testing"
+  },
+  "use-bff": {
+    "zh": "使用 BFF",
+    "en": "Using BFF"
+  },
+  "page-performance": {
+    "zh": "优化页面性能",
+    "en": "Optimize Page Performance"
+  },
+  "server-monitor": {
+    "zh": "服务端监控",
+    "en": "Server Monitor"
+  },
+  "micro-frontend": {
+    "zh": "微前端",
+    "en": "Micro Frontend"
+  },
+  "plugin-system": {
+    "zh": "插件系统",
+    "en": "Plugin System"
+  },
+  "official-plugins": {
+    "zh": "官方插件",
+    "en": "Official Plugins"
+  },
+  "cli-plugins": {
+    "zh": "CLI 插件",
+    "en": "CLI Plugins"
+  },
+  "server-plugins": {
+    "zh": "服务端插件",
+    "en": "Server Plugins"
+  },
+  "runtime-plugins": {
+    "zh": "运行时插件",
+    "en": "Runtime Plugins"
+  },
+  "rsbuild-plugins": {
+    "zh": "Rsbuild 插件",
+    "en": "Rsbuild Plugins"
+  },
+  "module-federation": {
+    "zh": "模块联邦",
+    "en": "Module Federation"
+  },
+  "examples": {
+    "zh": "示例",
+    "en": "Examples"
+  },
+  "first-app": {
+    "zh": "第一个应用",
+    "en": "First App"
+  },
+  "foundations": {
+    "zh": "基础",
+    "en": "Foundations"
+  },
+  "file-conventions": {
+    "zh": "文件约定",
+    "en": "File Conventions"
+  },
+  "runtime-api": {
+    "zh": "运行时",
+    "en": "Runtime"
+  },
+  "blog": {
+    "zh": "博客",
+    "en": "Blog"
+  }
+}