@modern-js/main-doc 2.7.0 → 2.9.0

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

@@ -0,0 +1,301 @@
+---
+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            显示命令帮助
+  --analyze             分析构建产物体积，查看各个模块打包后的大小
+  --web-only            仅启动 Web 服务
+  --api-only            仅启动 API 接口服务
+```
+
+运行 `modern dev` 后，Modern.js 会监听源文件变化并进行模块热更新。
+
+```bash
+$ modern dev
+
+info    Starting dev server...
+info    App running at:
+
+  > 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  显示命令帮助
+  --analyze   分析构建产物体积，查看各个模块打包后的大小
+```
+
+### 分析构建产物体积
+
+执行 `npx modern build --analyze` 命令，可以在打包生产环境代码的同时，产出一个分析构建产物体积的 HTML 文件：
+
+```
+Bundle Analyzer saved report to /example/dist/report.html
+File sizes after production build:
+
+  122.35 KB  dist/static/js/885.1d4fbe5a.js
+  2.3 KB     dist/static/js/main.4b8e8d64.js
+  761 B      dist/static/js/runtime-main.edb7cf35.js
+  645 B      dist/static/css/main.0dd3ecc1.css
+```
+
+手动在浏览器中打开上述 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、微前端开发模式等。
+
+```bash
+Usage: modern new [options]
+
+Options:
+  -d, --debug            开启 Debug 模式，打印调试日志信息 (default: false)
+  -c, --config <config>  生成器运行默认配置(JSON 字符串)
+  --dist-tag <tag>       生成器使用特殊的 npm Tag 版本
+  --registry             生成器运行过程中定制 npm Registry
+  -h, --help             显示命令帮助
+```
+
+### 添加入口
+
+在应用工程中，执行 `new` 命令添加入口如下：
+
+```bash
+$ npx modern new
+? 请选择你想要的操作 创建工程元素
+? 创建工程元素 新建「应用入口」
+? 请填写入口名称 entry
+```
+
+### 启用可选功能
+
+在应用工程中，执行 `new` 命令启用可选能力如下：
+
+```bash
+$ npx modern new
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 (Use arrow keys)
+❯ 启用 Tailwind CSS 支持
+  启用「BFF」功能
+  启用「微前端」模式
+  启用「单元测试 / 集成测试」功能
+  启用「Visual Testing (Storybook)」模式
+```
+
+:::tip
+`--config` 参数对应参数值需要使用 JSON 字符串。
+
+pnpm 暂不支持使用 JSON 字符串作为参数值，可使用 `npm new` 开启相关功能。【[相关 Issue](https://github.com/pnpm/pnpm/issues/3876)】
+
+:::
+
+## modern serve
+
+`modern serve` 命令用于在生产环境下启用应用工程, 注意需要提前执行 [`build`](/apis/app/commands#modern-build) 命令构建出对应产物。
+
+```bash
+Usage: modern serve [options]
+
+Options:
+  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
+  -h, --help            显示命令帮助
+  --web-only            仅启动 Web 服务
+  --api-only            仅启动 API 接口服务
+```
+
+默认情况下，应用将会在 `localhost:8080` 启动，可以通过 `server.port` 修改 Server 端口号：
+
+```js
+export default defineConfig({
+  server: {
+    port: 8081,
+  },
+});
+```
+
+## modern upgrade
+
+在项目根目录下执行命令 `npx modern upgrade`，会默认将当前执行命令项目的 `package.json` 中的 Modern.js 相关依赖更新至最新版本。
+
+```
+Usage: modern upgrade [options]
+
+Options:
+  --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 Builder 配置](https://modernjs.dev/builder/guide/basic/builder-config.html) 以及 webpack 配置。
+
+```
+Usage: modern inspect [options]
+
+Options:
+  --env <env>           查看指定环境下的配置 (default: "development")
+  --output <output>     指定在 dist 目录下输出的路径 (default: "/")
+  --verbose             在结果中展示函数的完整内容
+  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
+  -h, --help            显示命令帮助
+```
+
+在项目根目录下执行命令 `npx modern inspect` 后，会在项目的 `dist` 目录生成以下文件：
+
+- `builder.config.js`: 表示在构建时使用的 Modern.js Builder 配置。
+- `webpack.config.web.js`: 表示在构建时使用的 webpack 配置。
+
+```bash
+➜ npx modern inspect
+
+Inspect config succeed, open following files to view the content:
+
+  - Builder Config: /root/my-project/dist/builder.config.js
+  - Webpack Config (web): /root/my-project/dist/webpack.config.web.js
+```
+
+### 指定环境
+
+默认情况下，inspect 命令会输出开发环境的配置，你可以添加 `--env production` 选项来输出生产环境的配置：
+
+```bash
+modern inspect --env production
+```
+
+### 完整内容
+
+默认情况下，inspect 命令会省略配置对象中的函数内容，你可以添加 `--verbose` 选项来输出函数的完整内容：
+
+```bash
+modern inspect --verbose
+```
+
+### SSR 构建配置
+
+如果项目开启了 SSR 能力，则在 `dist` 目录会另外生成一份 `webpack.config.node.js` 文件，对应 SSR 构建时的 webpack 配置。
+
+```bash
+➜ npx modern inspect
+
+Inspect config succeed, open following files to view the content:
+
+  - Builder Config: /root/my-project/dist/builder.config.js
+  - Webpack Config (web): /root/my-project/dist/webpack.config.web.js
+  - Webpack Config (node): /root/my-project/dist/webpack.config.node.js
+```
+
+## modern lint
+
+运行 `ESLint` 进行代码语法检查。
+
+```bash
+Usage: modern lint [options] [...files]
+
+lint and fix source files
+
+Options:
+  --no-fix    disable auto fix source file
+  -h, --help  display help for command
+```
+
+通常情况下，我们只需要在 `git commit` 阶段通过 `lint-staged` 检查本次提交修改的部分代码。
+
+- 设置 `--no-fix` 参数后可以关闭自动修复 lint 错误代码的能力。
+
+## modern test
+
+`modern test` 命令会自动运行项目下的测试用例。
+
+```bash
+Usage: modern test [options]
+
+Options:
+  -h, --help  显示命令帮助
+```
+
+:::tip
+在使用 `modern test` 命令前，需要先通过 [`new`](/apis/app/commands#modern-new) 命令启用「单元测试 / 集成测试」功能。
+:::
+
+效果如下：
+
+```bash
+$ npx modern test
+ PASS  src/tests/index.test.ts
+  The add method
+    ✓ should work fine. (2ms)
+
+Test Suites: 1 passed, 1 total
+Tests:       1 passed, 1 total
+Snapshots:   0 total
+Time:        0.994 s, estimated 1 s
+```
+
+:::info
+`src` 和 `api` 目录下面的 `*.test.(js|ts)` 文件都会被识别为测试用例。
+:::

package/docs/zh/apis/app/runtime/model/connect.mdx

@@ -0,0 +1,143 @@
+---
+sidebar_position: 5
+title: connect
+---
+# connect
+
+import ReduckTip from "@site-docs/components/reduck-tip"
+
+<ReduckTip />
+
+:::tip 提示
+Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [**connect**](https://github.com/web-infra-dev/reduck/blob/main/packages/react/src/connect.ts)。
+
+:::
+
+`connect` 功能上同 `useModel` 一致，是对应的 HOC 风格的 API。建议优先使用 Hook 风格的 `useModel`。
+
+## 类型
+
+```ts
+type SelectStateToProps = (
+  ...modelStates: State[],
+  ownProps?: any,
+) => PlainObject;
+type SelectActionsToProps = (
+  ...modelActions: Actions[],
+  ownProps?: any,
+) => PlainObject;
+
+function connect(models: Model, options?: ConnectOptions);
+function connect(
+  models: [...Model[], SelectStateToProps?, SelectActionsToProps?],
+  options?: ConnectOptions,
+);
+```
+
+## 参数
+
+- `models`：传入的 1 个或多个 Model，当 `models` 为数组类型参数时，最后两项元素可以是用于筛选 State 的函数（ `SelectStateToProps` 类型）和用于筛选 Actions 的函数（ `SelectActionsToProps` 类型）。
+  - `SelectStateToProps`： `modelStates` 是传入的 Model 对象的 State 组成的数组，`ownProps` 是当前组件接收外部传递的 `props`，`SelectStateToProps` 返回的数据会传递到组件的 `props` 上。当 `models` 中没有传入 `SelectStateToProps` 参数时，所有 Model 的 State 进行合并后传递到组件的 `props` 上。
+  - `SelectActionsToProps`： `modelActions` 是传入的 Model 对象的 Actions 组成的数组，`ownProps` 是当前组件接收外部传递的 `props`，`SelectActionsToProps` 返回的数据也会传递到组件的 `props` 上。当 `models` 中没有传入 `SelectActionsToProps` 参数时，所有 Model 的 Actions 进行合并后传递到组件的 `props` 上。
+
+- `options`：可选参数，用于辅助配置。目前支持设置 `forwardRef`，用于控制是否转发组件的 `ref`，默认值为 `false`，表示不转发 `ref`。设置为 `{forwardRef: true}`，表示转发 `ref`。
+
+## 返回值
+
+返回一个高阶组件：接收一个传入的组件，返回一个在 `props` 上注入了额外 State 和 Actions 的组件。
+
+## 示例
+
+### 简单用法
+
+```ts
+const modelA = model('modelA').define({
+  state: {
+    a: 1,
+  },
+  actions: {
+    incA(state) {
+      return {
+        ...state,
+        a: state.a + 1,
+      };
+    },
+  },
+});
+
+const modelB = model('modelB').define({
+  state: {
+    b: 10,
+  },
+  actions: {
+    incB(state) {
+      return {
+        ...state,
+        b: state.b + 1,
+      };
+    },
+  },
+});
+
+function Test(props) {
+  props.incA(); // 调用 modelA 的 action
+  props.incB(); // 调用 modelB 的 action
+
+  props.a; // 获取 modelA 的 state: a
+  props.b; // 获取 modelB 的 state: b
+}
+
+export default connect([modelA, modelB])(Test);
+```
+
+### 筛选 State 和 Actions
+
+```ts
+function Test(props) {
+  props.incAll();
+  props.c;
+}
+
+const stateSelector = (stateA, stateB) => ({
+  ...stateA,
+  ...stateB,
+  c: stateA.a + stateA.b,
+});
+const actionsSelector = (actionsA, actionsB) => ({
+  ...actionsA,
+  ...actionsB,
+  incAll: () => {
+    actionsA.incA();
+    actionsB.incB();
+  },
+});
+
+export default connect([modelA, modelB, stateSelector, actionsSelector])(Test);
+```
+
+### 转发组件的 ref
+
+```ts
+import { useRef, forwardRef } from 'react';
+
+function Test(props, ref) {
+  const { a, b } = props;
+
+  return (
+    <div ref={ref}>
+      <span>{a}</span>
+      <span>{b}</span>
+    </div>
+  );
+}
+
+const TestWrapper = connect([modelA, modelB], { forwardRef: true })(
+  forwardRef(Test),
+);
+
+function App() {
+  const testRef = useRef();
+
+  return <TestWrapper ref={testRef} />;
+}
+```

package/docs/zh/apis/app/runtime/model/model_.mdx

@@ -0,0 +1,199 @@
+---
+sidebar_position: 1
+title: model
+---
+# model
+
+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/model.ts)。
+
+:::
+
+## model
+
+用于创建管理应用状态的 Model。
+
+`function model(name: string): { define: function }`
+
+- name：`string`，创建的 Model 的唯一标识。
+
+```ts title="示例"
+model('foo');
+```
+
+## define
+
+用于定义 Model 的详细结构，支持传入一个对象类型或函数类型的参数。
+
+### 对象类型
+
+`function define(modelDesc: ModelDesc): Model;`
+
+- modelDesc: `ModelDesc`，对 Model 结构的定义，包含 `state`、`computed`、`actions`、`effects` 等属性。
+
+```tsx title="示例"
+const fooModel = model('foo').define({
+  state: 'foo',
+  computed: {
+    cFoo: state => `c${state}`,
+  },
+  actions: {
+    setState: (state, value) => {
+      return value;
+    },
+  },
+  effects: {
+    loadState: async () => {
+      // 从服务端获取 state
+    },
+  },
+});
+```
+
+### 函数类型
+
+`function define((context: Context, utils: Utils) => ModelDesc): Model;`
+
+- context: Context，Reduck 上下文对象，可以获取底层的 `store` 对象。`store` 除支持 Redux Store 的所有 [API](https://redux.js.org/api/store) 以外，还挂载了用于消费 Model 的 `use` 的方法，和用于卸载 Model 的 `unmount` 方法。
+- utils: Utils，定义 Model 时，常用的工具函数：`use`、`onMount`。`use` 作用同 `store` 对象上的 `use`，`onMount` 是 Model 挂载后的钩子函数。
+
+{/* TODO: @anchao 调整类型  */}
+```ts
+interface Utils {
+  use: UseModel;
+  onMount: OnMountHook;
+}
+
+interface Context {
+  store: ReduxStore & {
+    use: UseModel;
+    unmount: (model: Model) => void;
+  };
+}
+```
+
+如通过 `use`，可以获取 Model 自身及其它 Model 的 `state`，`actions`。
+
+```tsx title="示例"
+const fooModel = model('foo').define(() => {
+  return {
+    state: 'foo',
+    actions: {
+      setState: (state, value) => {
+        return value;
+      },
+    },
+  };
+});
+
+const barModel = model('bar').define((_, { use }) => {
+  return {
+    state: 'bar',
+    effects: {
+      syncFoo() {
+        const [state, actions] = use(fooModel);
+        actions.setState(state);
+      },
+    },
+  };
+});
+```
+
+### 参数
+
+#### ModelDesc.state
+
+定义 Model 的状态。技术上，支持任意类型的 **State**，但是实践中建议使用可进行 JSON 序列化的类型。
+
+```ts
+interface ModelDesc {
+  state: any;
+}
+```
+
+#### ModelDesc.actions
+
+定义 Model 的 Actions。Actions 的函数类型为：
+
+```ts
+interface ModelDesc {
+  actions: {
+    [actionKey: string]: (state: State, payload: any) => State | void;
+  };
+}
+```
+
+Reduck 内部集成了 [immer](https://github.com/immerjs/immer)，可以直接原始的 `state`，当 Action 没有显式返回值时，Reduck 内部会返回修改过的新的 State 对象。
+
+#### ModelDesc.computed
+
+定义 Model 的衍生状态。衍生状态的定义支持两种类型：
+
+1. 只依赖 Model 自身的状态
+
+```ts
+interface ModelDesc {
+  computed: {
+    [computedKey: string]: (state: State) => any;
+  };
+}
+```
+
+2. 依赖其他 Model 的状态
+
+```ts
+interface ModelDesc {
+  computed: {
+    [computedKey: string]: [
+      ...models: Model[],
+      (state: State, ...args: ModelState[]) => any,
+    ];
+  };
+}
+```
+
+```ts title="示例"
+const fooModel = model('foo').define({
+  state: 'foo',
+});
+
+const barModel = model('bar').define({
+  state: 'bar',
+  computed: {
+    combineFoo: [fooModel, (state, fooState) => state + fooState],
+  },
+});
+```
+
+#### ModelDesc.effects
+
+定义 Model 的 Effects。Effects 中定义的函数类型为：
+
+```ts
+interface ModelDesc {
+  effects: {
+    [effectKey: string]: (...args: any[]) => any;
+  };
+}
+```
+
+```ts title="示例"
+const fooModel = model('foo').define((context, { use }) => ({
+  state: 'foo',
+  effects: {
+    persist() {
+      const [state] = use(fooModel);
+      localStorage.setItem('state', state);
+    },
+  },
+}));
+```
+
+:::info 更多参考
+[创建 Model](/guides/topic-detail/model/define-model)
+
+:::