@modern-js/main-doc 2.1.0 → 2.2.0

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

@@ -1,19 +0,0 @@
----
-sidebar_position: 5
----
-
-```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。
-
-import CommandTip from '@site-docs/components/command-tip.md'
-
-<CommandTip />

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

@@ -1,23 +0,0 @@
----
-sidebar_position: 11
----
-
-```
-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 相关依赖更新至最新版本。
-
-:::info
-命令在 `@modern-js/monorepo-tools` 版本 >= 1.17.0 提供，之前版本可使用 `npx @modern-js/upgrade` 进行升级。
-:::

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

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

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

@@ -1,10 +0,0 @@
----
-title: monorepo.code-workspace
-sidebar_position: 7
----
-
-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.md

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

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

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

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

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

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

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

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

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

package/zh/components/command-tip.md

@@ -1,58 +0,0 @@
-:::tip 提示
-pnpm v6 和 pnpm v7 版本在执行命令时使用姿势不完全一致，需要注意以下事项：
-
-pnpm v7：
-
-在使用 pnpm 调用 `package.json` 中的命令时，如果需要传递参数至 pnpm，需要将参数放到命令前。
-
-例如使用 pnpm `--filter` 参数执行 prepare 命令：
-
-```bash
-pnpm run --filter "./packages/**" prepare
-```
-
-如果需要传递参数至命令，需要将参数放到命令后。
-
-例如，在如下 `package.json` 配置中：
-
-```json
-{
-  "scripts": {
-    "command": "modern command"
-  }
-}
-```
-
-执行 command 命令时携带参数方式为：
-
-```bash
-pnpm run command --options
-```
-
-pnpm v6:
-
-在如下 `package.json` 配置中：
-
-```json
-{
-  "scripts": {
-    "command": "modern command"
-  }
-}
-```
-
-当需要执行 `modern command --option`：
-
-使用 pnpm 时，需要执行 `pnpm run command -- --option`。
-
-这是因为 pnpm 对于命令参数的处理与 Yarn 并不相同，但是与 npm 类似：在不加 `--` 字符串的时候，传递的是 pnpm 的参数；在使用 `--` 字符串的时候，传递的是执行脚本的参数。
-
-在上述例子里参数 `--option` 传递给了 `modern command`。如果执行 `pnpm run command --option`，则参数 `--option` 将传递给 pnpm。
-
-总结来说：
-
-**在使用 pnpm v7 时，如果传递参数给 pnpm，需要将参数放置到命令前**
-
-**在使用 pnpm v6 时，如果传递的参数给 pnpm，不需要加 `--`；如果传递的参数是给脚本使用，需要增加 `--` 字符串**。
-
-:::

package/zh/components/enable-bff.md

@@ -1,32 +0,0 @@
-1. 执行 `pnpm new`，选择启用 BFF
-2. 根据选择的运行时框架，将下面的代码添加到 `modern.config.[tj]s` 中：
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<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.md

@@ -1,67 +0,0 @@
-- 类型： `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.md

@@ -1,27 +0,0 @@
-Modern.js 提供了开箱即用的全局代理插件 `@modern-js/plugin-proxy`，该插件底层基于 [whistle](https://github.com/avwo/whistle)，可用来查看、修改 HTTP/HTTPS 的请求和响应，也可作为 HTTP 代理服务器使用。
-
-### 设置代理规则
-
-引入代理插件并填写规则后，执行 `pnpm run dev`，Modern.js 会在开发服务器启动之后，自动启用代理服务器。
-
-具体代理规则，可通过 [`dev.proxy`](/docs/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.md

@@ -1,43 +0,0 @@
-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.md

@@ -1,19 +0,0 @@
-### 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.md

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

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

@@ -1,61 +0,0 @@
----
-title: autoLoadPlugins (自动注册插件)
-sidebar_position: 11
----
-
-- 类型：`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.md

@@ -1,33 +0,0 @@
----
-sidebar_label: prefix
----
-
-# bff.prefix
-
-- 类型：`string`
-- 默认值：`/api`
-
-:::caution 注意
-请先在当前应用项目根目录使用【[new](/docs/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`。

package/zh/configure/app/bff/proxy.md

@@ -1,72 +0,0 @@
----
-sidebar_label: proxy
----
-
-# bff.proxy
-
-- 类型：`Record<string, string>`
-- 默认值：`{}`
-
-:::info 补充信息
-请先在当前应用项目根目录使用【[new](/docs/apis/app/commands/new)】 启用 BFF 功能。
-:::
-
-通过简单配置，无需编写代码，Modern.js 会自动转发请求。发送给 Modern.js BFF server 的请求，会代理到指定的服务上。
-BFF Proxy 使用了强大的 [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)，如果需要更多高级的用法， 可以查看它的[文档](https://github.com/chimurai/http-proxy-middleware#options)。
-
-在 `modern.server-runtime.config.js` 中加入以下配置；即可开启代理：
-
-```js title="modern.server-runtime.config.js"
-import { defineConfig } from '@modern-js/app-tools/server';
-export default defineConfig({
-  bff: {
-    proxy: {
-      '/api': 'https://cnodejs.org',
-    },
-  },
-});
-```
-
-假设启动的 Modern.js BFF server 的服务地址是 `localhost:8080`，所有 path 以 `api` 开头的请求都会被拦截，如发送到 `localhost:8080/api/v1/topics` 的请求会被代理到 `https://cnodejs.org/api/v1/topics`。
-
-你可以做路径的重写，如将发送到 `localhost:8080/api/topics` 的请求代理到 `https://cnodejs.org/api/v1/topics`。
-
-```ts title="modern.server-runtime.config.ts"
-import { defineConfig } from '@modern-js/app-tools/server';
-export default defineConfig({
-  bff: {
-    proxy: {
-      '/api': {
-        target: 'https://cnodejs.org',
-        pathRewrite: { '/api/topics': '/api/v1/topics' },
-        changeOrigin: true,
-      },
-    },
-  },
-});
-```
-
-与 [dev.proxy](/docs/configure/app/dev/proxy) 不同，本节所介绍的代理只作用于进入 BFF/API 服务的请求；同时，这一配置不但可以在开发环境中使用，在生产环境中也会代理相应的请求。
-
-## 常见用法
-
-### 解决接口跨域问题
-
-在项目开发过程中，因为 web 页面和接口服务不是部署在同一个域名下，常常会遇到跨域问题。
-解决跨域问题的方式有很多，在这里我们使用 `bff.proxy` 可以轻松解决跨域问题。
-
-:::info 注
-BFF proxy 模式下，如果不需要写 BFF 的接口， API 目录可以删除；此时 BFF proxy 仍会开启。
-:::
-
-如下所示，在 `modern.server-runtime.config.ts` 中，写入如下配置；我们将所有 web 页面发送到同域的以 `/api` 开头的请求代理到另一个域名的服务上。
-
-```ts title="modern.server-runtime.config.ts"
-export default defineServerConfig({
-  bff: {
-    proxy: {
-      '/api': 'https://cnodejs.org',
-    },
-  },
-};
-```

package/zh/configure/app/builder-plugins.md

@@ -1,72 +0,0 @@
----
-title: builderPlugins (构建插件)
-sidebar_position: 10
----
-
-- 类型：`BuilderPlugin[]`
-- 默认值：`[]`
-
-用于配置 Modern.js Builder 构建插件。
-
-Modern.js Builder 是 Modern.js 底层的构建引擎，请阅读 [构建能力](/docs/guides/basic-features/builder) 了解相关背景。
-
-如果你想了解 Builder 插件的编写方式，可以参考 [Modern.js Builder - 插件系统](https://modernjs.dev/builder/zh/plugins/introduction.html)。
-
-## 注意事项
-
-该选项**用于配置 Modern.js Builder 构建插件**，如果你需要配置其他类型的插件，请选择对应的配置方式：
-
-- 配置 Modern.js 框架插件，请使用 [plugins](docs/configure/app/plugins) 配置项。
-- 配置 webpack 插件，请使用 [tools.webpack](/docs/configure/app/tools/webpack) 或 [tools.webpackChain](/docs/configure/app/tools/webpack-chain) 配置项。
-- 配置 Babel 插件，请使用 [tools.babel](/docs/configure/app/tools/babel) 配置项。
-
-## 何时使用
-
-大部分场景下，我们推荐你使用 Modern.js 框架插件，框架插件可以通过 [plugins](docs/configure/app/plugins) 字段进行注册。因为框架插件提供的 API 更丰富、能力更强，而 Builder 插件提供的 API 只能用于构建场景。
-
-当你需要引用一些现有的 Builder 插件（并且在 Modern.js 中没有相关能力），或是在不同的框架之间复用 Builder 插件时，你可以使用 `builderPlugins` 字段进行注册。
-
-## 示例
-
-下面是 Builder 插件的使用示例。
-
-### 使用 npm 上的插件
-
-使用 npm 上的插件，需要通过包管理器安装插件，并通过 import 引入。
-
-```ts title="modern.config.ts"
-import myBuilderPlugin from 'my-builder-plugin';
-
-export default defineConfig({
-  builderPlugins: [myBuilderPlugin()],
-});
-```
-
-### 使用本地插件
-
-使用本地代码仓库中的插件，直接通过相对路径 import 引入即可。
-
-```ts title="modern.config.ts"
-import myBuilderPlugin from './plugin/myBuilderPlugin';
-
-export default defineConfig({
-  builderPlugins: [myBuilderPlugin()],
-});
-```
-
-### 插件配置项
-
-如果插件提供了一些自定义的配置项，可以通过插件函数的参数传入配置。
-
-```ts title="modern.config.ts"
-import myBuilderPlugin from 'my-builder-plugin';
-
-export default defineConfig({
-  builderPlugins: [
-    myBuilderPlugin({
-      foo: 1,
-      bar: 2,
-    }),
-  ],
-});
-```