@modern-js/main-doc 2.7.0 → 2.9.0

package/docs/zh/apis/app/runtime/model/use-model.mdx

@@ -0,0 +1,89 @@
+---
+sidebar_position: 2
+title: useModel
+---
+# useModel
+
+import ReduckTip from "@site-docs/components/reduck-tip"
+
+<ReduckTip />
+
+:::tip 提示
+Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [model](https://github.com/web-infra-dev/reduck/blob/main/packages/store/src/model/useModel.ts)。
+
+:::
+
+## 函数签名
+
+```ts
+function useModel(
+  models: Models[],
+  stateSelector?: StateSelector,
+  actionSelector?: ActionSelector,
+): [state, actions, subscribe];
+function useModel(
+  ...models: Models[],
+  stateSelector?: (...args: State[]) => any,
+  actionSelector?: (...args: Actions[]) => any,
+): [state, actions, subscribe];
+```
+
+### 参数
+
+- models：Model 对象数组，可以作为一个数组类型的参数传入，也可以所有 Model 逐个作为参数传入。
+- stateSelector：可选参数，用于筛选 State 计算。前 n 个参数为 n 个 Model 对应的 State，返回的数据作为 `useModel` 返回值数组的第一个元素。
+- actionSelector：可选参数，用于筛选 Actions 计算。前 n 个参数为 n 个 Model 对应的 Actions，返回的数据作为 `useModel` 返回值数组的第二个元素。
+
+### 返回值
+
+返回一个数组，每一项元素分别为：
+
+- state：`stateSelector` 的返回值。如果未传 `stateSelector`，会把传入的所有 Model 的 State (包含衍生状态)合并后返回。如果不同 Model 的 State 中存在同名属性，后面的 State 会覆盖前面的 State。当 `state` 发生变化时，调用 `useModel` 的组件会重新渲染。
+- actions：第二个元素为 `actionSelector` 的返回值。如果未传 `actionSelector`，会把传入的所有 Model 的 Actions (包含 Effects) 合并后返回。如果不同 Model 的 Actions 中存在同名属性，后面的 Actions 会覆盖前面的 Actions。
+- subscribe：订阅 State 变化的函数。当传入的任意 Model 的 State 发生改变时，该函数会被调用。
+
+## 示例
+
+### 基本用法
+
+```tsx
+import todoModel from 'models/todo';
+import filterModel from 'models/filter';
+
+function Test(props) {
+  const [state, actions] = useModel([todoModel, filterModel]);
+  actions.add(); // 调用 todoModel add action
+  actions.setVisibleStatus(); // 调用 filterModel filterModel action
+
+  state.items; // 获取 todoModel state items
+  state.visibleStatus; // 获取 filterModel state visibleStatus
+}
+```
+
+### selector 用法
+
+```js
+function Test(props) {
+  const [state, actions] = useModel(
+    [todoModel, filterModel],
+    (todoState, filterState) => ({
+      items: todoState.items,
+      visibleStatus: `${props.prefix}-${filterState.visibleStatus}`,
+    }),
+    (todoActions, filterActions) => ({
+      ...todoActions,
+      ...filterActions,
+    }),
+  );
+  actions.add(); // 调用 todoModel add action
+  actions.setVisibleStatus(); // 调用 filterModel filterModel action
+
+  state.items; // 获取 todoModel state items
+  state.visibleStatus; // 获取 filterModel state visibleStatus
+}
+```
+
+:::info 更多参考
+[使用 Model](/guides/topic-detail/model/use-model)
+
+:::

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

@@ -0,0 +1,132 @@
+---
+title: Hook
+---
+# Hook
+
+用于拓展 Modern.js 内置的 Web Server，所有的页面请求都会经过 Hook。
+
+:::note
+更多内容可以查看[自定义 Web Server](/guides/advanced-features/web-server)。
+:::
+
+## 使用姿势
+
+```ts
+import { AfterMatchHook, AfterRenderHook } from '@modern-js/runtime/server';
+
+export const afterMatch: AfterMatchHook = (context, next) => {};
+export const afterRender: AfterRenderHook = (context, next) => {};
+```
+
+:::info 自定义 Web Server
+使用该 API 前，请先执行 `pnpm run new` 新建「自定义 Web Serve」源码目录。
+
+```bash
+pnpm run new
+? 请选择你想要的操作 创建工程元素
+? 新建「自定义 Web Server」源码目录
+```
+:::
+
+## 函数签名
+
+```ts
+type HookContext = {
+  response: {
+    set: (key: string, value: string) => void;
+    status: (code: number) => void;
+    cookies: {
+      get: (key: string) => string;
+      set: (key: string, value: string) => void;
+      delete: () => void;
+      clear: () => void;
+    };
+    raw: (
+      body: string,
+      { status, headers }: { status: number; headers: Record<string, any> },
+    ) => void;
+  };
+  request: {
+    url: string;
+    host: string;
+    pathname: string;
+    query: Record<string, any>;
+    cookie: string;
+    cookies: {
+      get: (key: string) => string;
+    };
+    headers: IncomingHttpHeaders;
+  };
+};
+
+function Hook(context: HookContext, next: NextFunction): Promsie<void> | void;
+```
+
+另外，不同 Hook 额外提供了不同的上下文。目前 Modern.js 支持 `AfterMatch` 和 `AfterRender` 两个 Hook。
+
+```ts
+type AfterMatchContext = HookContext & {
+  router: {
+    redirect: (url: string, status: number) => void;
+    rewrite: (entry: string) => void;
+  };
+};
+
+type AfterRenderContext = {
+  template: {
+    get: () => string;
+    set: (html: string) => void;
+    prependHead: (fragment: string) => void;
+    appendHead: (fragment: string) => void;
+    prependBody: (fragment: string) => void;
+    appendBody: (fragment: string) => void;
+  };
+};
+```
+
+### 参数
+
+- `context`：提供当前 Hook 上下文。
+  - `response`：提供一系列处理响应的操作
+  - `request`：提供一系列获取请求信息的操作
+  - `router`：提供对响应路由的快捷操作
+  - `template`：提供对响应内容的快捷操作
+- `next`：执行当前 Hook 的下一个监听函数（不影响整体服务端流程）。
+
+## 示例
+
+### Redirect
+
+将页面重定向到站点外的页面，例如跳转到统一登录页：
+
+```ts
+import type { AfterMatch } from '@modern-js/runtime/server';
+
+export const afterMatch: AfterMatch = async (ctx, next) => {
+  ctx.router.redirect('https://website.com/login', 302);
+};
+```
+
+### Rewrite
+
+将页面重写到当前站点的其他页面，例如同一个路由根据 UA 返回适配不同端的页面：
+
+```ts
+import type { AfterMatch } from '@modern-js/runtime/server';
+
+export const afterMatch: AfterMatch = async (ctx, next) => {
+  ctx.router.rewrite('mobile');
+};
+```
+
+### HTML 内容注入
+
+为页面注入某些与渲染主体无关的 HTML 内容，如脚本、页面骨架等：
+
+```ts
+import type { AfterRender } from '@modern-js/runtime/server';
+
+export const afterRender: AfterRenderHook = (context, next) => {
+  ctx.template.prependBody('<div>Footer</div>');
+};
+```

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

@@ -0,0 +1,131 @@
+---
+title: Middleware
+---
+# Middleware
+
+用于拓展 Modern.js 内置的 Web Server，与 [Hook](/apis/app/runtime/web-server/hook) 不同的是，Middleware 可以直接操作 Node 原生的请求、响应对象，并且可以使用框架拓展。
+
+:::note
+更多内容可以查看[自定义 Web Server](/guides/advanced-features/web-server)。
+:::
+
+## 使用姿势
+
+```ts
+import { Middleware } from '@modern-js/runtime/server';
+
+export const middleware: Middleware = async (context, next) => {};
+export const middleware: Middleware[] = [
+  async (context, next) => {},
+  async (context, next) => {},
+];
+```
+
+:::info 自定义 Web Server
+使用该 API 前，请先执行 `pnpm run new` 新建「自定义 Web Server」源码目录。
+
+```bash
+pnpm run new
+? 请选择你想要的操作 创建工程元素
+? 新建「自定义 Web Server」源码目录
+```
+
+:::
+
+## 函数签名
+
+```ts
+type Middleware = (
+  context: MiddlewareContext,
+  next: NextFunction,
+) => Promise<void> | void;
+
+type MiddlewareContext = {
+  response: {
+    set: (key: string, value: string) => void;
+    status: (code: number) => void;
+    cookies: {
+      get: (key: string) => string;
+      set: (key: string, value: string) => void;
+      delete: () => void;
+      clear: () => void;
+      apply: () => void;
+    };
+    raw: (
+      body: string,
+      { status, headers }: { status: number; headers: Record<string, any> },
+    ) => void;
+    locals: Record<string, any>;
+  };
+  request: {
+    url: string;
+    host: string;
+    pathname: string;
+    query: Record<string, any>;
+    cookie: string;
+    cookies: {
+      get: (key: string) => string;
+    };
+    headers: IncomingHttpHeaders;
+  };
+  source: {
+    req: IncomingMessage;
+    res: ServerResponse;
+  };
+};
+```
+
+### 参数
+
+- `context`：提供当前 Hook 上下文。
+  - `response`：提供一系列处理响应的操作
+  - `request`：提供一系列获取请求信息的操作
+  - `source`：提供 Node.js 原生的 `req` 与 `res` 对象。
+- `next`：执行当前 Hook 的下一个监听函数（不影响整体服务端流程）。
+
+:::warning
+`next` 函数的执行不影响后续内置流程，只控制下一个中间件是否执行。只有当响应被写入时，后续渲染流程才会中断。
+:::
+
+## 示例
+
+### 服务端耗时打点
+
+```ts
+export const Middleware = () => async (ctx, next) => {
+  const start = Date.now();
+  ctx.res.once('finish', () => {
+    console.log(Date.now() - start);
+  });
+};
+```
+
+### 注入服务端工具 & 数据
+
+Modern.js 提供了 `res.locals` 属性用来存放当前请求的局部变量。
+
+```ts
+export const Middleware = () => async (ctx, next) => {
+  ctx.res.locals.id = 'Modern.js';
+  ctx.res.locals.rpc = createRpcInstance();
+};
+```
+
+### 框架拓展
+
+Middleware 还可以和 BFF 一样，使用运行时框架拓展。Modern.js 约定，当使用框架运行时拓展时，类型信息从 `@modern-js/runtime/{namespace}` 下导出，Middleware 可以使用框架语法，例如框架中间件写法，以下是伪代码：
+
+```ts
+import { SomeType } from '@modern-js/runtime/{namespace}';
+
+export const middleware: SomeType = (ctx, next) => {
+  console.log(ctx.url);
+  next();
+};
+```
+
+默认情况下，在安装框架拓展插件后，Web Server 的框架拓展能力是关闭的。如果希望使用框架拓展，可以通过 [`server.enableFrameworkExt`](/configure/app/server/enable-framework-ext.html) 开启。
+
+:::info
+框架拓展导出的类型名不一定为 Middleware，命名由框架拓展插件。
+:::

package/docs/zh/apis/monorepo/commands/gen-release-note.mdx

@@ -0,0 +1,32 @@
+---
+sidebar_position: 9
+---
+# gen-release-note
+
+```bash
+Usage: modern gen-release-note [options]
+
+根据当前仓库 changeset 文件生成 Release Note
+
+Options:
+  --repo <repo>      仓库名称，用于生成 Pull Request 链接， 例如： web-infra-dev/modern.js
+  --custom <cumtom>  自定义 Release Note 生成函数
+  -h, --help         display help for command
+```
+
+根据当前仓库的 changeset 信息自动生成 Release Note。
+
+:::warning 注意
+需要在 bump 命令之前执行。
+
+:::
+
+```markdown
+## Features:
+
+[[#1160](https://github.com/web-infra-dev/modern.js/pull/1160)] export ExecaError type
+
+## Bug Fix:
+
+[[#1264](https://github.com/web-infra-dev/modern.js/pull/1264)] fix: conventional router app use App.init not work
+```

package/docs/zh/apis/monorepo/commands/new.mdx

@@ -0,0 +1,39 @@
+---
+sidebar_position: 1
+---
+# new
+
+```bash
+Usage: modern new [options]
+
+Monorepo 创建子项目
+
+Options:
+  -d, --debug            开启 Debug 模式，打印调试日志信息 (default: false)
+  -c, --config <config>  生成器运行默认配置(JSON 字符串)
+  --dist-tag <tag>       生成器使用特殊的 npm Tag 版本
+  --registry             生成器运行过程中定制 npm Registry
+  -h, --help             display help for command
+```
+
+`modern new` 命令在 monorepo 中可以用来添加应用工程和可复用的模块：
+
+```bash
+$ modern new
+? 请选择你想创建的工程类型 (Use arrow keys)
+❯ Web 应用
+  Web 应用（测试）
+  Npm 模块
+  Npm 模块（内部）
+```
+
+应用工程默认会添加到 `apps` 目录， 测试应用会添加到 `examples` 目录，公共模块默认会添加到 `packages` 目录， 内部模块默认会添加到 `features` 目录。
+
+内部模块在 monorepo 的应用里面使用时，可以无需构建直接使用源码。
+
+:::caution 注意
+`--config` 参数对应参数值需要使用 JSON 字符串。
+
+pnpm 暂不支持使用 JSON 字符串作为参数值，可使用 `npm new` 开启相关功能。【[相关 Issue](https://github.com/pnpm/pnpm/issues/3876)】
+
+:::

package/docs/zh/components/default-mwa-generate.mdx

@@ -0,0 +1,5 @@
+```bash
+? 请选择你想创建的工程类型：Web 应用
+? 请选择开发语言：TS
+? 请选择包管理工具：pnpm
+```

package/docs/zh/components/enable-bff.mdx

@@ -0,0 +1,31 @@
+1. 执行 `pnpm new`，选择启用 BFF
+2. 根据选择的运行时框架，将下面的代码添加到 `modern.config.[tj]s` 中：
+
+import { Tabs, Tab as TabItem } from "@theme";
+
+<Tabs>
+  <TabItem value="express" label="Express.js" default>
+
+```ts title="edenx.config.ts"
+import expressPlugin from '@modern-js/plugin-express';
+import bffPlugin from '@modern-js/plugin-bff';
+
+export default defineConfig({
+  plugins: [expressPlugin(), bffPlugin()],
+});
+```
+
+  </TabItem>
+  <TabItem value="koa" label="Koa.js">
+
+```ts title="edenx.config.ts"
+import koaPlugin from '@modern-js/plugin-koa';
+import bffPlugin from '@modern-js/plugin-bff';
+
+export default defineConfig({
+  plugins: [koaPlugin(), bffPlugin()],
+});
+```
+
+  </TabItem>
+</Tabs>

package/docs/zh/components/init-app.mdx

@@ -0,0 +1,44 @@
+Modern.js 生成器会提供一个可交互的问答界面，根据结果初始化项目，按照默认的选择进行初始化：
+
+```bash
+? 请选择你想创建的工程类型：Web 应用
+? 请选择开发语言：TS
+? 请选择包管理工具：pnpm
+```
+
+在生成项目后，Modern.js 会自动安装依赖、创建 git 仓库。
+
+```bash
+[INFO] 依赖自动安装成功
+[INFO] git 仓库初始化成功
+[INFO] 创建成功！
+可在新项目的目录下运行以下命令：
+pnpm run dev          # 按开发环境的要求，运行和调试项目
+pnpm run build        # 按生产环境的要求，构建项目
+pnpm run serve        # 按生产环境的要求，运行项目
+pnpm run lint         # 检查和修复所有代码
+pnpm run new          # 继续创建更多项目要素，比如应用入口
+```
+
+:::note
+Modern.js 生成器除了在项目初始化时工作外，也能在后续研发中生成项目各种粒度的模块，并非一用即抛开。
+
+:::
+
+现在，项目结构如下：
+
+```
+.
+├── node_modules
+├── src
+│   ├── modern-app-env.d.ts
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+├── modern.config.ts
+├── package.json
+├── pnpm-lock.yaml
+├── README.md
+└── tsconfig.json
+```

package/docs/zh/components/init-rspack-app.mdx

@@ -0,0 +1,7 @@
+```bash
+$ npx @modern-js/create myapp
+? 请选择你想创建的工程类型：Web 应用
+? 请选择开发语言：TS
+? 请选择包管理工具：pnpm
+? 请选择构建工具：Rspack
+```

package/docs/zh/components/prerequisites.mdx

@@ -0,0 +1,18 @@
+### Node.js
+
+import NodeVersion from '@modern-js/builder-doc/docs/zh/shared/nodeVersion.md';
+
+<NodeVersion />
+
+### pnpm
+
+推荐使用 [pnpm](https://pnpm.io/installation) 来管理依赖：
+
+```bash
+npm install -g pnpm@7
+```
+
+:::note
+Modern.js 同样支持使用 `yarn`、`npm` 进行依赖管理。
+
+:::

package/docs/zh/components/release-note.mdx

@@ -0,0 +1 @@
+根据官网 [Release Note](https://github.com/web-infra-dev/modern.js/releases)，开发者也可以手动将项目升级到想要的版本。

package/docs/zh/configure/app/bff/enable-handle-web.mdx

@@ -0,0 +1,24 @@
+---
+title: enableHandleWeb
+---
+
+# bff.enableHandleWeb
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+:::caution 注意
+请先在当前应用项目根目录使用【[new](/apis/app/commands#modern-new)】 启用 BFF 功能。
+:::
+
+默认情况下，BFF 服务只能处理 BFF API 的请求。
+
+当该值设置为 `true` 时，页面请求流量也会经过 BFF，并且 Modern.js 内置的页面渲染的逻辑默认会作为 BFF 服务的最后一个中间件运行。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    enableHandleWeb: true,
+  },
+});
+```

package/docs/zh/configure/app/dev/asset-prefix.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: assetPrefix
+---
+
+# dev.assetPrefix
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.assetPrefix](https://modernjs.dev/builder/api/config-dev.html#devassetprefix)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/assetPrefix.md';
+
+<Main />

package/docs/zh/configure/app/dev/before-start-url.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: beforeStartUrl
+---
+
+# dev.beforeStartUrl
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.beforeStartUrl](https://modernjs.dev/builder/api/config-dev.html#devbeforestarturl)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/beforeStartUrl.md';
+
+<Main />

package/docs/zh/configure/app/dev/hmr.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: hmr
+---
+
+# dev.hmr
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.hmr](https://modernjs.dev/builder/api/config-dev.html#devhmr)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/hmr.md';
+
+<Main />

package/docs/zh/configure/app/dev/host.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: host
+---
+
+# dev.host
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.host](https://modernjs.dev/builder/api/config-dev.html#devhost)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/host.md';
+
+<Main />

package/docs/zh/configure/app/dev/https.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: https
+---
+
+# dev.https
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.https](https://modernjs.dev/builder/api/config-dev.html#devhttps)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/https.md';
+
+<Main />

package/docs/zh/configure/app/dev/port.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: port
+---
+
+# dev.port
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.port](https://modernjs.dev/builder/api/config-dev.html#devport)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/port.md';
+
+<Main />

package/docs/zh/configure/app/dev/progress-bar.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: progressBar
+---
+
+# dev.progressBar
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.progressBar](https://modernjs.dev/builder/api/config-dev.html#devprogressbar)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/progressBar.md';
+
+<Main />

package/docs/zh/configure/app/dev/start-url.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: startUrl
+---
+
+# dev.startUrl
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.startUrl](https://modernjs.dev/builder/api/config-dev.html#devstarturl)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/startUrl.md';
+
+<Main />