@modern-js/main-doc 2.1.0 → 2.2.0

package/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 链接， 例如： modern-js-dev/modern.js
+  --custom <cumtom>  自定义 Release Note 生成函数
+  -h, --help         display help for command
+```
+
+根据当前仓库的 changeset 信息自动生成 Release Note。
+
+:::warning 注意
+需要在 bump 命令之前执行。
+
+:::
+
+```markdown
+## Features:
+
+[[#1160](https://github.com/modern-js-dev/modern.js/pull/1160)] export ExecaError type
+
+## Bug Fix:
+
+[[#1264](https://github.com/modern-js-dev/modern.js/pull/1264)] fix: conventional router app use App.init not work
+```

package/zh/apis/monorepo/commands/lint.mdx

@@ -0,0 +1,18 @@
+---
+sidebar_position: 6
+---
+# lint
+
+```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
+```
+
+运行 `ESLint` 检查 monorepo 中代码语法情况， 通长情况下，我们只需要在 `git commit` 阶段通过 `lint-staged` 检查本次提交修改的部分代码。
+
+- `--no-fix` 参数设置后可以关闭自动修复 lint 错误代码的能力。

package/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)
+❯ 应用
+  应用（测试）
+  模块
+  模块（内部）
+```
+
+应用工程默认会添加到 `apps` 目录， 测试应用会添加到 `examples` 目录，公共模块默认会添加到 `packages` 目录， 内部模块默认会添加到 `features` 目录。
+
+内部模块在 monorepo 的应用里面使用时，可以无需构建直接使用源码。
+
+:::caution 注意
+`--config` 参数对应参数值需要使用 JSON 字符串。
+
+pnpm 暂不支持使用 JSON 字符串作为参数值，可使用 `npm new` 开启相关功能。【[相关 Issue](https://github.com/pnpm/pnpm/issues/3876)】
+
+:::

package/zh/apis/monorepo/commands/pre.mdx

@@ -0,0 +1,65 @@
+---
+sidebar_position: 3
+---
+# pre
+
+```bash
+Usage: modern pre [options] <enter|exit> [tag]
+
+进入和退出预发布模式
+
+Options:
+  -h, --help  display help for command
+```
+
+可以使用 `modern pre` 命令在正式发布前[预发布](https://github.com/atlassian/changesets/blob/main/docs/prereleases.md)一个版本。
+
+首先 `modern pre enter <tag>` 进入预发布模式:
+
+```bash
+$ npx modern pre enter next
+🦋  success Entered pre mode with tag next
+🦋  info Run `changeset version` to version packages with prerelease versions
+```
+
+之后通过 `modern change` 命令添加 changeset:
+
+```bash
+$ npx modern change
+🦋  Which packages would you like to include? · package-a, package-b
+🦋  Which packages should have a major bump? · No items were selected
+🦋  Which packages should have a minor bump? · No items were selected
+🦋  The following packages will be patch bumped:
+🦋  package-a@0.1.1
+🦋  package-b@0.1.1
+🦋  Please enter a summary for this change (this will be in the changelogs). Submit empty line to open external editor
+🦋  Summary · test pre publish
+🦋  === Releasing the following packages ===
+🦋  [Patch]
+🦋    package-a, package-b
+🦋  ╔════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
+🦋  ║                                                      ========= NOTE ========                                                       ║
+🦋  ║All dependents of these packages that will be incompatible with the new version will be patch bumped when this changeset is applied.║
+🦋  ╚════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
+🦋  Is this your desired changeset? (Y/n) · true
+🦋  Changeset added! - you can now commit it
+🦋
+🦋  If you want to modify or expand on the changeset summary, you can find it here
+🦋  info /xxxxxx/monorepo/.changeset/beige-paws-rule.md
+```
+
+接着可以使用 `modern bump` 命令更新具体的版本号：
+
+```bash
+$ npx modern bump
+🦋  warn ===============================IMPORTANT!===============================
+🦋  warn You are in prerelease mode
+🦋  warn If you meant to do a normal release you should revert these changes and run `changeset pre exit`
+🦋  warn You can then run `changeset version` again to do a normal release
+🦋  warn ----------------------------------------------------------------------
+🦋  All files have been updated. Review them and commit at your leisure
+```
+
+可以看到 `package-a` 和 `package-b` 的 `package.json` 中版本号均已更新到 `0.1.2-next.0`。
+
+提交完变更之后，我们可以通过 `modern pre exit` 命令退出预发布模式。

package/zh/apis/monorepo/commands/release.mdx

@@ -0,0 +1,16 @@
+---
+sidebar_position: 5
+---
+# release
+
+```bash
+Usage: modern release [options]
+
+publish changes to npm
+
+Options:
+  --tag <tag>  publish use special tag (default: "")
+  -h, --help   display help for command
+```
+
+发布当前仓库的 Packages 至 NPM。

package/zh/apis/monorepo/commands/upgrade.mdx

@@ -0,0 +1,20 @@
+---
+sidebar_position: 11
+---
+# upgrade
+
+```
+Usage: modern upgrade [options]
+
+升级 Modern.js 到最新版本
+
+Options:
+  --registry <registry>  定制 npm registry (default: "")
+  -d,--debug             开启 Debug 模式，打印调试日志信息 (default: false)
+  --cwd <cwd>            项目路径 (default: "")
+  -h, --help             display help for command
+```
+
+`modern upgrade` 命令，用于升级项目 Modern.js 相关依赖至最新版本。
+
+在项目根目录下执行命令 `npx modern upgrade`，会默认将当前执行命令项目的 `package.json` 中的 Modern.js 相关依赖更新至最新版本。

package/zh/apis/monorepo/hooks/apps.mdx

@@ -0,0 +1,14 @@
+---
+title: apps/*
+sidebar_position: 1
+---
+# apps/*
+
+Monorepo 工程方案应用类型项目目录。
+
+Modern.js Monorepo 工程方案约定将应用类型子项目放置在 `apps` 目录下进行统一管理，`apps` 目录下每一个文件夹都是一个完整的应用项目。
+
+:::info 注
+可直接在项目下执行 new 命令创建应用类型子项目。
+
+:::

package/zh/apis/monorepo/hooks/code-workspace.mdx

@@ -0,0 +1,11 @@
+---
+title: monorepo.code-workspace
+sidebar_position: 7
+---
+# monorepo.code-workspace
+
+Monorepo 工程方案 VS Code 配置文件。
+
+Monorepo 工程方案支持 VS Code Workspace 配置，可以通过该配置文件打开的一个或多个文件夹的集合。
+
+VS Code workspace 协议详情可查看: [VS Code Workspace](https://code.visualstudio.com/docs/editor/workspaces)

package/zh/apis/monorepo/hooks/examples.mdx

@@ -0,0 +1,16 @@
+---
+title: examples/*
+sidebar_position: 2
+---
+# examples/*
+
+Monorepo 工程方案测试应用类型项目目录。
+
+Modern.js Monorepo 工程方案约定将测试的应用类型子项目放置在 `examples` 目录下进行统一管理，`examples` 目录下每一个文件夹都是一个完整的应用项目。
+
+测试类型的应用项目不包含部署相关的 scripts 命令，用于开发过程中进行测试项目、测试案例的编写。
+
+:::info 注
+可直接在项目下执行 new 命令创建测试应用类型子项目。
+
+:::

package/zh/apis/monorepo/hooks/features.mdx

@@ -0,0 +1,16 @@
+---
+title: features/
+sidebar_position: 3
+---
+# features/
+
+Monorepo 工程方案内部模块类型项目目录。
+
+Modern.js Monorepo 工程方案约定将内部模块类型子项目放置在 `features` 目录下进行统一管理，`features` 目录下每一个文件夹都是一个完整的模块项目。
+
+内部模块项目用于一些不需要编译的公共的组件和工具的编写，这类型的项目不包含编译、发布命令，在应用类型项目中引用时，应用类型项目会默认对其进行编译。
+
+:::info 注
+可直接在项目下执行 new 命令内部模块类型子项目。
+
+:::

package/zh/apis/monorepo/hooks/packages.mdx

@@ -0,0 +1,16 @@
+---
+title: packages/
+sidebar_position: 4
+---
+# packages/
+
+Monorepo 工程方案公共模块类型项目目录。
+
+Modern.js Monorepo 工程方案约定将公共模块类型子项目放置在 `packages` 目录下进行统一管理，`packages` 目录下每一个文件夹都是一个完整的模块项目。
+
+公共模块项目用户一些公共的组件和工具的编写，这些公共包可自行进行编译和发布，也可在应用类型项目中引用。
+
+:::info 注
+可直接在项目下执行 new 命令创建模块类型子项目。
+
+:::

package/zh/apis/monorepo/hooks/pnpm-workspace.mdx

@@ -0,0 +1,11 @@
+---
+title: pnpm-workspace.yaml
+sidebar_position: 5
+---
+# pnpm-workspace.yaml
+
+Monorepo 工程方案 pnpm workspace 配置文件。
+
+Monorepo 工程方案支持使用 pnpm 作为包管理工具对项目进行管理，支持 pnpm 的 workspace 协议。
+
+pnpm workspace 配置详情可查看: [pnpm workspace](https://pnpm.io/workspaces)

package/zh/apis/monorepo/hooks/pnpmfile.mdx

@@ -0,0 +1,11 @@
+---
+title: .pnpmfile.cjs
+sidebar_position: 6
+---
+# .pnpmfile.cjs
+
+Monorepo 工程方案 pnpm 钩子文件。
+
+Monorepo 工程方案支持使用 pnpm 作为包管理工具对项目进行管理，支持使用 pnpm 的钩子文件对安装过程进行自定义。
+
+pnpm .pnpmfile.cjs 使用详情可查看: [pnpmfile](https://pnpm.io/pnpmfile)

package/zh/blog/index.md

@@ -0,0 +1,6 @@
+---
+title: Modern.js 2.0
+---
+# Modern.js 2.0
+
+> 即将到来

package/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 '@edenx/plugin-express';
+import bffPlugin from '@edenx/plugin-bff';
+
+export default defineConfig({
+  plugins: [expressPlugin(), bffPlugin()],
+});
+```
+
+  </TabItem>
+  <TabItem value="koa" label="Koa.js">
+
+```ts title="edenx.config.ts"
+import koaPlugin from '@edenx/plugin-koa';
+import bffPlugin from '@edenx/plugin-bff';
+
+export default defineConfig({
+  plugins: [koaPlugin(), bffPlugin()],
+});
+```
+
+  </TabItem>
+</Tabs>

package/zh/components/global-proxy-config.mdx

@@ -0,0 +1,70 @@
+- 类型： `string | Object`
+- 默认值： `null`
+
+配置该选项后，开发环境时会启动全局代理，类似 [Fiddler](https://www.telerik.com/fiddler), [Charles](https://www.charlesproxy.com/) 等 web 代理调试工具，可以用来查看、修改 HTTP/HTTPS 请求、响应、也可以用作代理服务器。
+
+:::tip 提示
+使用该选项需要提前安装 `@modern-js/plugin-proxy`。
+
+:::
+
+值为 `Object` 时，对象的 `key` 对应匹配的 `pattern`，对象的 `value` 对应匹配的 `target`。
+
+例如：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  dev: {
+    proxy: {
+      'https://www.baidu.com': 'https://google.com.hk',
+      //可以通过 file 协议直接返回静态文件。
+      'https://example.com/api': 'file://./data.json',
+    },
+  },
+});
+```
+
+值为 `string` 时， 可以用来指定单独的代理文件，例如：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  dev: {
+    proxy: './proxy.js',
+  },
+});
+```
+
+```js title="proxy.js"
+module.exports = {
+  name: 'my-app',
+  rules: `
+    ^example.com:8080/api/***   http://localhost:3001/api/$
+  `,
+};
+```
+
+:::info 注
+Modern.js 全局代理实现底层基于 [whistle](https://wproxy.org/whistle/), 更多匹配模式请参考: [匹配模式](https://wproxy.org/whistle/pattern.html)
+
+:::
+
+执行 `dev`, 提示如下时，即代理服务器启动成功：
+
+```bash
+  App running at:
+
+  Local:    http://localhost:8080/
+  Network:  http://192.168.0.1:8080/
+
+ℹ  info      Starting the proxy server.....
+✔  success   Proxy Server start on localhost:8899
+```
+
+访问 `localhost:8899`, 可以在 UI 界面上查看 Network 以及配置代理规则：
+
+![proxy ui 界面](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/dev-proxy.png)
+
+:::caution 注意
+https 代理自动安装证书需要获取 root 权限, 请根据提示输入密码即可。**密码仅在信任证书时使用，不会泄漏或者用于其他环节**。
+
+:::

package/zh/components/global-proxy.mdx

@@ -0,0 +1,27 @@
+Modern.js 提供了开箱即用的全局代理插件 `@modern-js/plugin-proxy`，该插件底层基于 [whistle](https://github.com/avwo/whistle)，可用来查看、修改 HTTP/HTTPS 的请求和响应，也可作为 HTTP 代理服务器使用。
+
+### 设置代理规则
+
+引入代理插件并填写规则后，执行 `pnpm run dev`，Modern.js 会在开发服务器启动之后，自动启用代理服务器。
+
+具体代理规则，可通过 [`dev.proxy`](/configure/app/dev/proxy) 选项或 `config/proxy.js` 文件进行设置。
+
+### 代理服务器 UI 界面
+
+安装代理插件并配置代理规则后， 执行 `pnpm run dev` 命令：
+
+```bash
+  App running at:
+
+  Local:    http://localhost:8080/
+  Network:  http://192.168.0.1:8080/
+
+ℹ  info      Starting the proxy server.....
+✔  success   Proxy Server start on localhost:8899
+```
+
+在控制台中可以看到代理服务器成功启动。
+
+访问 `http://localhost:8899`，显示下图所示的 UI 界面后，即可通过界面设置规则。
+
+![debug-proxy-ui](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/debug/debug-proxy-ui.png)

package/zh/components/init-app.mdx

@@ -0,0 +1,44 @@
+Modern.js 生成器会提供一个可交互的问答界面，根据结果初始化项目，按照默认的选择进行初始化：
+
+```bash
+? 请选择你想创建的工程类型 应用
+? 请选择开发语言 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/zh/components/prerequisites.mdx

@@ -0,0 +1,20 @@
+### Node.js
+
+需要 [Node.js LTS](https://github.com/nodejs/Release)，并确保 Node 版本大于等于 v16.18.1。
+
+Modern.js 推荐在开发环境里先安装 [nvm](https://github.com/nvm-sh/nvm#install--update-script)，在 shell 里集成[自动切换 node 版本的脚本](https://github.com/nvm-sh/nvm#deeper-shell-integration)。
+
+然后只要仓库根目录下有内容为 `lts/gallium` 的 `.nvmrc` 文件，进入这个仓库时就会自动安装或切换到正确的 Node.js 版本。
+
+### pnpm
+
+推荐使用 [pnpm](https://pnpm.io/installation) 来管理依赖：
+
+```bash
+npm install -g pnpm
+```
+
+:::note
+Modern.js 同样支持使用 `yarn`、`npm` 进行依赖管理。
+
+:::

package/zh/components/reduck-tip.mdx

@@ -0,0 +1,8 @@
+
+
+:::info 补充信息
+默认情况下，本节所有 API 的导出包名为：`@modern-js/runtime/model`。
+
+如果是在 Modern.js 以外单独集成 Reduck，导出包名为：`@modern-js-reduck/react`。
+
+:::

package/zh/components/self-route-example.mdx

@@ -0,0 +1,21 @@
+```tsx title="src/App.tsx"
+import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
+import { StaticRouter } from '@modern-js/runtime/router/server';
+import React from 'react';
+import { useRuntimeContext } from '@modern-js/runtime';
+
+const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
+
+export default () => {
+  const { context } = useRuntimeContext();
+  const pathname = context?.request?.pathname;
+  return (
+    <Router location={pathname}>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </Router>
+  );
+};
+```

package/zh/configure/app/auto-load-plugin.mdx

@@ -0,0 +1,62 @@
+---
+title: autoLoadPlugins (自动注册插件)
+sidebar_position: 11
+---
+# autoLoadPlugins (自动注册插件)
+
+- 类型：`boolean`
+- 默认值：`false`
+
+用于配置 Modern.js 是否开启自动注册插件。
+
+### 手动注册插件
+
+默认情况下，安装插件后，你需要在 `modern.config.ts` 文件中手动注册插件。
+
+```ts title="modern.config.ts"
+import appTools, { defineConfig } from '@modern-js/app-tools';
+import i18nPlugin from '@modern-js/plugin-i18n';
+
+export default defineConfig({
+  plugins: [appTools(), i18nPlugin()],
+});
+```
+
+### 自动注册插件
+
+除了手段注册，Modern.js 还提供自动注册插件的方式: 将 `autoLoadPlugin` 配置项置为 `true`。
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  autoLoadPlugins: true,
+});
+```
+
+Modern.js 将通过以下几个步骤帮你自动注册插件
+
+1. Modern.js 在内部维护一份官方插件列表。
+
+```js
+const InternalPlugins = ['@modern-js/app-tools', '@modern-js/plugin-i18n', ...];
+```
+
+2. Modern.js 将读取你的 `package.json` 文件，收集依赖信息。
+
+```json title="package.json"
+"dependencies": {
+  "@modern-js/plugin-i18n": "x.x.x"
+  ...
+},
+"devDependencies": {
+  "@modern-js/app-tools": "x.x.x"
+  ...
+}
+```
+
+3. Modern.js 观察到你安装了 `@modern-js/plugin-i18n` 和 `@modern-js/app-tools` 等依赖后，将会引入插件自动注册。
+
+可以注意到这种方式相对黑盒，你甚至对加载插件的过程是无感知的。我们希望更多的细节暴露给开发者，能让开发者去控制这一过程。
+
+**因此我们更加推荐你手动注册插件。**

package/zh/configure/app/bff/prefix.mdx

@@ -0,0 +1,34 @@
+---
+sidebar_label: prefix
+---
+
+# bff.prefix
+
+- 类型：`string`
+- 默认值：`/api`
+
+:::caution 注意
+请先在当前应用项目根目录使用【[new](/apis/app/commands/new)】 启用 BFF 功能。
+
+:::
+
+默认情况下，BFF API 目录下的路由访问前缀是 `/api`, 如下目录结构：
+
+```bash
+api
+└── hello.ts
+```
+
+`api/hello.ts` 访问时对应的路由为 `localhost:8080/api/hello`。
+
+该配置选项可以修改默认的路由前缀：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    prefix: '/api-demo',
+  },
+});
+```
+
+对应的 `api/hello.ts` 访问路由为 `localhost:8080/api-demo/hello`。