@modern-js/main-doc 0.0.0-next-20221116121040

package/zh/apis/generator/plugin/new/createSubProject.md

@@ -0,0 +1,35 @@
+---
+sidebar_position: 4
+---
+
+# createSubProject
+
+创建子项目，只支持 Monorepo 工程方案。
+
+该方法可在 onForged 生命周期的 api 参数上获取。
+
+其类型定义为：
+
+```ts
+export enum SubSolution {
+  MWA = 'mwa',
+  MWATest = 'mwa_test',
+  Module = 'module',
+  InnerModule = 'inner_module',
+}
+export type ForgedAPI = {
+  createSubProject: (
+    solution: SubSolution,
+    params: Record<string, unknown>,
+  ) => Promise<void>;
+  ...
+};
+```
+
+## solution
+
+子项目工程方案名称。
+
+## params
+
+创建子项目的其他参数，详细参考[Monorepo 创建子项目](/docs/configure/generator/monorepo#%E5%88%9B%E5%BB%BA%E5%AD%90%E9%A1%B9%E7%9B%AE)。

package/zh/apis/generator/plugin/new/enableFunc.md

@@ -0,0 +1,46 @@
+---
+sidebar_position: 3
+---
+
+# enableFunc
+
+启用功能，支持应用和模块工程方案。
+
+该方法可在 onForged 生命周期的 api 参数上获取。
+
+其类型定义为：
+
+```ts
+export enum ActionFunction {
+  UnBundle = 'unbundle',
+  TailwindCSS = 'tailwindcss',
+  Less = 'less',
+  Sass = 'sass',
+  BFF = 'bff',
+  MicroFrontend = 'micro_frontend',
+  I18n = 'i18n',
+  Test = 'test',
+  E2ETest = 'e2e_test',
+  Doc = 'doc',
+  Storybook = 'storybook',
+  RuntimeApi = 'runtimeApi',
+  SSG = 'ssg',
+  Polyfill = 'polyfill',
+  Deploy = 'deploy',
+}
+export type ForgedAPI = {
+  enableFunc: (
+    func: ActionFunction,
+    params?: Record<string, unknown> | undefined,
+  ) => Promise<void>;
+  ...
+};
+```
+
+## func
+
+功能名称，根据不用的工程方案支持的功能进行传值。
+
+## params
+
+启用功能时其他参数，详细参考[应用 New 命令](/docs/configure/generator/mwa#new-%E5%91%BD%E4%BB%A4)和[模块 New 命令](/docs/configure/generator/module#new-命令)。

package/zh/apis/generator/plugin/new/introduce.md

@@ -0,0 +1,15 @@
+---
+sidebar_position: 1
+---
+
+# 介绍
+
+Modern.js 提供的三个工程方案支持在项目中执行 new 命令创建元素和开启功能。在生成器插件中可直接调用相关 API 默认创建一些元素和开启支持的功能。
+
+不同的工程方案支持的 new 操作
+
+- [应用](/docs/configure/generator/mwa#new-%E5%91%BD%E4%BB%A4)
+
+- [模块](/docs/configure/generator/module#new-命令)
+
+- [Monorepo](/docs/configure/generator/monorepo#创建子项目)

package/zh/apis/generator/plugin/npm/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "NPM API",
+  "position": 7
+}

package/zh/apis/generator/plugin/npm/install.md

@@ -0,0 +1,16 @@
+---
+sidebar_position: 1
+---
+
+# install
+
+在项目根目录安装依赖。
+
+install 函数中将根据 packageManager 的值使用对应的包管理工具安装依赖。
+
+```ts
+export type AfterForgedAPI = {
+  install: () => Promise<void>;
+  ...
+};
+```

package/zh/apis/monorepo/commands/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "命令",
+  "position": 4,
+  "link": {
+    "type": "doc",
+    "id": "apis/monorepo/commands/index"
+  }
+}

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

@@ -0,0 +1,42 @@
+---
+sidebar_position: 4
+---
+
+```bash
+Usage: modern bump [options]
+
+使用变更集自动更新发布版本和变更日志
+
+Options:
+  --canary       创建一个预发布版本进行测试 (default: false)
+  --preid <tag>  在对预发布版本进行版本控制时指定标识符 (default: "next")
+  --snapshot     创建一个特殊版本进行测试 (default: false)
+  -h, --help     display help for command
+```
+
+:::info 注
+`bump` 命令执行之前需要提前执行 [`change`](/docs/apis/monorepo/commands/change) 命令添加 changeset。
+:::
+
+按 changeset 记录修改 `package.json` 中的版本号， 同时生成 `CHANGELOG.md`：
+
+```bash
+npx modern bump
+🦋  All files have been updated. Review them and commit at your leisure
+```
+
+`CHANGELOG.md` 示例内容如下：
+
+```md
+# package-a
+
+## 0.1.1
+### Patch Changes
+
+- test publish
+
+```
+
+import CommandTip from '@site/docs/components/command-tip.md'
+
+<CommandTip />

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

@@ -0,0 +1,58 @@
+---
+sidebar_position: 2
+---
+
+```bash
+Usage: modern change [options]
+
+创建变更集
+
+Options:
+  --empty     创建空变更集 (default: false)
+  --open      使用编辑器中打开创建的变更集 (default: false)
+  -h, --help  display help for command
+```
+
+:::info 注
+[`change`](/docs/apis/monorepo/commands/change)、[`pre`](/docs/apis/monorepo/commands/pre)、[`bump`](/docs/apis/monorepo/commands/bump)、[`release`](/docs/apis/monorepo/commands/release) 命令集成了工具 [`changesets`](https://github.com/atlassian/changesets) 管理版本变更和 Changelog。
+:::
+
+`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.0
+🦋  package-b@0.1.0
+🦋  Please enter a summary for this change (this will be in the changelogs). Submit empty line to open external editor
+🦋  Summary · test 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 /xxxx/monorepo/.changeset/long-lizards-talk.md
+```
+上面我们给 `package-a` 和 `package-b` 都选择了 `patch` 变更，具体的变更信息在 monorepo 根目录下的 `.changeset/long-lizards-talk.md` 中:
+
+```md
+---
+"package-a": patch
+"package-b": patch
+---
+
+test publish
+```
+
+import CommandTip from '@site/docs/components/command-tip.md'
+
+<CommandTip />

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

@@ -0,0 +1,27 @@
+---
+sidebar_position: 8
+---
+
+```bash
+Usage: modern clear [options]
+
+clear project dirs
+
+Options:
+  --remove-dirs [dirs...]  remove dirs, default is node_modules
+  -h, --help               display help for command
+```
+
+import CommandTip from '@site/docs/components/command-tip.md'
+
+<CommandTip />
+
+默认对 Monorepo 以及 Monorepo 子项目的 `node_modules` 进行清理。
+
+可以通过参数 `--remove-dirs` 来指定要删除的目录，例如执行：
+
+```bash
+$ npx modern clear --remove-dirs dist
+```
+
+则会清理所有 Monorepo 子项目的 `dist` 目录。

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

@@ -0,0 +1,39 @@
+---
+sidebar_position: 7
+---
+
+```bash
+Usage: modern deploy [options]
+
+deploy project
+
+Options:
+  -p, --path [path]  Specify the path of the product output (default: "output")
+  -h, --help         display help for command
+```
+
+import CommandTip from '@site/docs/components/command-tip.md'
+
+<CommandTip />
+
+对指定的项目进行部署，会通过指定项目分析其依赖的 Monorepo 下的子项目。
+
+在执行命令之后，会首先生成 `output` 目录，在目录当中包含了指定部署的项目以及其依赖的子项目，形成一个最小集合的 Monorepo。
+
+:::info 补充信息
+`output` 目录是默认目录，可以通过 `-p` 参数进行自定义。
+:::
+
+然后会在 `output` 目录下进行依赖的安装以及必要文件的复制。
+
+最后当依赖安装完成后，便完成了对指定项目的部署任务。
+
+例如部署项目名称为 `app` 的应用，则可以执行：
+
+```
+pnpm deploy app
+```
+
+:::info 补充信息
+其中 `app` 为项目的 `package.json` 的 `name` 值。
+:::

package/zh/apis/monorepo/commands/gen-release-note.md

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

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

@@ -0,0 +1,12 @@
+---
+type: ref
+---
+
+# 命令
+
+本节涵盖了使用Monorepo工程的所有命令。
+
+
+
+
+

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

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

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

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

@@ -0,0 +1,68 @@
+---
+sidebar_position: 3
+---
+
+```bash
+Usage: modern pre [options] <enter|exit> [tag]
+
+进入和退出预发布模式
+
+Options:
+  -h, --help  display help for command
+```
+
+import CommandTip from '@site/docs/components/command-tip.md'
+
+<CommandTip />
+
+可以使用 `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.md

@@ -0,0 +1,20 @@
+---
+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

@@ -0,0 +1,23 @@
+---
+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/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "文件约定",
+  "position": 3,
+  "link": {
+    "type": "doc",
+    "id": "apis/monorepo/hooks/index"
+  }
+}

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

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

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

@@ -0,0 +1,10 @@
+---
+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

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

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

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

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

@@ -0,0 +1,12 @@
+---
+type: ref
+---
+
+# 命令
+
+本节涵盖了使用Monorepo工程所有的文件约定
+
+
+
+
+

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

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

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

@@ -0,0 +1,10 @@
+---
+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

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

package/zh/apis/monorepo/overview.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 0
+---
+
+# 概览
+本节涵盖了使用@modern-js/monorepo-tools的所有API。
+
+import OverviewNav from '@site/src/components/OverviewNav';
+import sidebarData from '@site/plugins/overview-loader!@site/plugins/overview-data.json';
+
+<OverviewNav cards={sidebarData.docsSidebars.apisMonorepoSidebar} />

package/zh/community/index.md

@@ -0,0 +1,3 @@
+# 社区
+
+Modern.js 社区正在建设中，敬请关注！