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

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

@@ -0,0 +1,212 @@
+# Plugin API
+
+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

@@ -0,0 +1,43 @@
+# Life Cycle
+
+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

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

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

@@ -0,0 +1,31 @@
+---
+title: Route Authorization
+---
+
+# Route Authorization
+
+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:
+
+- Access to the `/` route does not require authorization and can be accessed directly.
+- Access to the `/protected` route requires authorization. If there is no authorization, it will automatically redirect to the `/login` route. After successful login, it returns to `/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/en/tutorials/foundations/introduction.mdx

@@ -0,0 +1,22 @@
+---
+title: Introduction
+sidebar_position: 1
+---
+
+# Modern.js Example Library
+
+Welcome to Modern.js Example Library! Here you'll find practical code examples to help you get started with Modern.js quickly.
+
+If you're new to Modern.js, we recommend reading the [Modern.js Introduction](/guides/get-started/introduction) first.
+
+## 📚 Example List
+
+import ExampleList from '@site-docs-en/components/turtorials-example-list';
+
+<ExampleList />
+
+---
+
+## 💡 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/_nav.json

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

package/docs/zh/apis/_meta.json

@@ -0,0 +1,13 @@
+[
+  "app/commands",
+  {
+    "type": "dir",
+    "name": "app/hooks",
+    "label": "file-conventions"
+  },
+  {
+    "type": "dir",
+    "name": "app/runtime",
+    "label": "runtime-api"
+  }
+]

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

@@ -0,0 +1,215 @@
+---
+sidebar_position: 1
+---
+
+# 命令
+
+Modern.js 内置了一些命令，可以帮助你快速启动开发服务器、构建生产环境代码等。
+
+通过本章节，你可以了解到 Modern.js 内置的命令有哪些，以及如何使用这些命令。
+
+## modern dev
+
+`modern dev` 命令用于启动一个本地开发服务器，对源代码进行开发环境编译。
+
+```bash
+Usage: modern dev [options]
+
+Options:
+  -e --entry <entry>    指定入口，只编译特定的页面
+  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
+  -h, --help            显示命令帮助
+  --web-only            仅启动 Web 服务
+  --api-only            仅启动 API 接口服务
+```
+
+运行 `modern dev` 后，Modern.js 会监听源文件变化并进行模块热更新。
+
+```bash
+$ modern dev
+
+info    Starting dev server...
+
+  > Local:    http://localhost:8080/
+  > Network:  http://192.168.0.1:8080/
+```
+
+### 编译部分页面
+
+在多页面（MPA）项目中，可以添加 `--entry` 参数来指定编译其中的一个或多个页面。这样可以只编译项目中的部分代码，从而提升 dev 启动速度。
+
+比如执行 `modern dev --entry`，在命令行界面中会展示入口选择框：
+
+```bash
+$ modern dev --entry
+
+? 请选择需要构建的入口
+❯ ◯ foo
+  ◯ bar
+  ◯ baz
+```
+
+比如选择 `foo` 入口，那么只有 `foo` 入口相关的代码会进行编译，其他页面的代码将不会参与构建。
+
+### 通过参数指定页面
+
+你也可以在 `--entry` 后面通过参数来指定页面名称，多个页面的名称使用逗号分隔。
+
+```bash
+# 编译 foo 页面
+modern dev --entry foo
+
+# 编译 foo 和 bar 页面
+modern dev --entry foo,bar
+```
+
+## modern start
+
+`modern start` 是 `modern dev` 命令的别名，两者的功能和用法完全一致。
+
+## modern build
+
+`modern build` 命令默认会在 `dist/` 目录下构建出可用于生产环境的产物。你可以通过修改配置 [`output.distPath`](/configure/app/output/dist-path) 指定产物的输出目录。
+
+```bash
+Usage: modern build [options]
+
+Options:
+  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
+  -h, --help  显示命令帮助
+  -w --watch  开启 watch 模式, 监听文件变更并重新构建
+```
+
+## modern new
+
+`modern new` 命令用于在已有项目中添加项目元素。
+
+比如添加应用入口、启用一些可选功能如 BFF、微前端开发模式等。
+
+```bash
+Usage: modern new [options]
+
+Options:
+  --config-file <configFile>  指定配置文件路径，可以为相对路径或绝对路径
+  --lang <lang>          设置 new 命令执行语言(zh 或者 en)
+  -d, --debug            开启 Debug 模式，打印调试日志信息 (default: false)
+  -c, --config <config>  生成器运行默认配置(JSON 字符串)
+  --dist-tag <tag>       生成器使用特殊的 npm Tag 版本
+  --registry             生成器运行过程中定制 npm Registry
+  -h, --help             显示命令帮助
+```
+
+### 添加入口
+
+在 Modern.js 工程中，执行 `new` 命令添加入口的步骤如下：
+
+```bash
+$ npx modern new
+? 请选择你想要的操作 创建工程元素
+? 请选择创建元素类型 新建「应用入口」
+? 请填写入口名称 entry
+```
+
+### 启用可选功能
+
+在 Modern.js 工程中，执行 `new` 命令启用可选能力的步骤如下：
+
+```bash
+$ npx modern new
+? 请选择你想要的操作 启用可选功能
+? 请选择功能名称 (Use arrow keys)
+❯ 启用「BFF」功能
+  启用「微前端」模式
+```
+
+:::tip
+`--config` 参数对应参数值需要使用 JSON 字符串。
+
+pnpm 暂不支持使用 JSON 字符串作为参数值，可使用 `npm new` 开启相关功能。【[相关 Issue](https://github.com/pnpm/pnpm/issues/3876)】
+
+:::
+
+import ServeCommand from '@site-docs/components/serve-command';
+
+<ServeCommand />
+
+## modern upgrade
+
+在项目根目录下执行命令 `npx modern upgrade`，会默认将当前执行命令项目的 `package.json` 中的 Modern.js 相关依赖更新至最新版本。
+
+```bash
+Usage: modern upgrade [options]
+
+Options:
+  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
+  --registry <registry>  定制 npm registry (default: "")
+  -d,--debug             开启 Debug 模式，打印调试日志信息 (default: false)
+  --cwd <cwd>            项目路径 (default: "")
+  -h, --help             display help for command
+```
+
+## modern inspect
+
+`modern inspect` 命令用于查看项目的 Modern.js 配置、[Rsbuild 配置](https://v2.rsbuild.rs/zh/config/index) 以及 Rspack 配置。
+
+```bash
+Usage: modern inspect [options]
+
+Options:
+  --env <env>           查看指定环境下的配置 (default: "development")
+  --output <output>     指定在 dist 目录下输出的路径 (default: "./")
+  --verbose             在结果中展示函数的完整内容
+  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
+  -h, --help            显示命令帮助
+```
+
+在项目根目录下执行命令 `npx modern inspect` 后，会在项目的 `dist` 目录生成以下文件：
+
+- `modern.js.config.mjs`: 表示当前使用的 Modern.js 配置。
+- `rsbuild.config.mjs`: 表示在构建时使用的 Rsbuild 配置。
+- `rspack.config.web.mjs`: 表示在构建时使用的 Rspack 配置。
+
+```bash
+➜ npx modern inspect
+
+Inspect config succeed, open following files to view the content:
+
+  - Rsbuild Config: /root/my-project/dist/rsbuild.config.mjs
+  - Rspack Config (web): /root/my-project/dist/rspack.config.web.mjs
+  - Modern.js Config: /root/my-project/dist/modern.js.config.mjs
+```
+
+### 指定环境
+
+默认情况下，inspect 命令会输出开发环境的配置，你可以添加 `--env production` 选项来输出生产环境的配置：
+
+```bash
+modern inspect --env production
+```
+
+### 完整内容
+
+默认情况下，inspect 命令会省略配置对象中的函数内容，你可以添加 `--verbose` 选项来输出函数的完整内容：
+
+```bash
+modern inspect --verbose
+```
+
+### SSR 构建配置
+
+如果项目开启了 SSR 能力，则在 `dist` 目录会另外生成一份 `rspack.config.node.mjs` 文件，对应 SSR 构建时的 Rspack 配置。
+
+```bash
+➜ npx modern inspect
+
+Inspect config succeed, open following files to view the content:
+
+  - Rsbuild Config: /root/my-project/dist/rsbuild.config.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
+```
+
+import DeployCommand from '@site-docs/components/deploy-command';
+
+<DeployCommand />

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

@@ -0,0 +1,28 @@
+[
+  {
+    "type": "dir",
+    "name": "src",
+    "label": "src/",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "api",
+    "label": "api/",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "server",
+    "label": "server/",
+    "collapsed": true
+  },
+  "shared",
+  {
+    "type": "dir",
+    "name": "config",
+    "label": "config/",
+    "collapsed": true
+  },
+  "modern-config"
+]

package/docs/zh/apis/app/hooks/api/lambda.mdx

@@ -0,0 +1,14 @@
+---
+title: lambda/*.ts
+sidebar_position: 3
+---
+
+# lambda/*.ts
+
+开启 BFF 后，`lambda/` 目录下的文件会按照约定被注册为 BFF 的路由。
+
+:::note
+文件支持使用 `js` 或 `ts` 语言，但必须使用 `esm` 语法导出函数。
+:::
+
+详细内容可以参考 [BFF 函数路由](/guides/advanced-features/bff/function.html#函数路由)。

package/docs/zh/apis/app/hooks/config/_meta.json

@@ -0,0 +1 @@
+["html", "favicon", "icon", "mock", "public", "upload"]

package/docs/zh/apis/app/hooks/config/favicon.mdx

@@ -0,0 +1,29 @@
+---
+title: favicon.*
+sidebar_position: 3
+---
+
+# Favicon
+
+当项目根目录的 `config` 目录下存在 `favicon.*` 文件时，Modern.js 会自动将该文件设置到 [html.favicon](/configure/app/html/favicon) 配置项中，用于生成页面的 favicon 图标：
+
+```
+./config
+└── favicon.ico
+```
+
+构建完成后，可以看到 HTML 中自动生成了以下标签：
+
+```html
+<link rel="icon" href="/favicon.ico" />
+```
+
+## 查找顺序
+
+在设置 app icon 时，Modern.js 会按以下顺序寻找文件：
+
+- `favicon.png`
+- `favicon.jpg`
+- `favicon.jpeg`
+- `favicon.svg`
+- `favicon.ico`

package/docs/zh/apis/app/hooks/config/html.mdx

@@ -0,0 +1,9 @@
+---
+title: html/
+sidebar_position: 1
+---
+# html/
+
+通过 `config/html` 目录可以在内部默认 html 模板的不同位置注入自定义的 html 片段。
+
+具体使用方式请参考: [自定义 HTML](/guides/basic-features/html)