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

package/zh/guides/troubleshooting/dependencies.md

@@ -0,0 +1,168 @@
+---
+sidebar_position: 1
+---
+
+# 依赖安装问题
+
+### 如何升级项目中的 Modern.js 到最新版本？
+
+对于使用 yarn 的项目，可以执行：
+
+```bash
+yarn upgrade --scope @modern-js
+```
+
+对于使用 pnpm 的项目，可以执行：
+
+```bash
+pnpm update "@modern-js/*" -r
+```
+
+如果需要了解不同版本之间的更新内容，可以查看：
+
+- Modern.js 发版日志：[Modern.js/releases](https://github.com/modern-js-dev/modern.js/releases)。
+- 各个 package 下的 `CHANGELOG.md` 文件。
+
+---
+
+### 如何锁定项目中的某个依赖版本？
+
+如果需要锁定项目中的某个依赖的版本，可以通过以下方式进行操作：
+
+**yarn**
+
+对于使用 yarn 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `yarn`：
+
+```json
+{
+  "resolutions": {
+    "package-name": "^1.0.0"
+  }
+}
+```
+
+**pnpm**
+
+对于使用 pnpm 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `pnpm i`：
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "package-name": "^1.0.0"
+    }
+  }
+}
+```
+
+**npm**
+
+对于使用 npm 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `npm i`：
+
+```json
+{
+  "overrides": {
+    "package-name": "^1.0.0"
+  }
+}
+```
+
+:::info
+对于 monorepo 场景，只能在项目根目录的 `package.json` 中锁定依赖版本，并且会影响 monorepo 中的所有 package。
+:::
+
+---
+
+### 如何查看项目里某个依赖实际安装的版本？
+
+可以使用包管理器自带的 `ls` 命令来查看项目里依赖的版本。
+
+下面是一些基本的示例，详细用法请查看各个包管理器的文档。
+
+**npm / yarn**
+
+对于使用 npm 或 yarn 的项目，可以使用 `npm ls` 命令。
+
+比如执行 `npm ls @modern-js/core`，可以看到如下结果：
+
+```
+project
+└─┬ @modern-js/app-tools@1.6.10
+  └── @modern-js/core@1.12.4
+```
+
+**pnpm**
+
+对于使用 pnpm 的项目，可以使用 `pnpm ls` 命令。
+
+比如执行 `pnpm ls @modern-js/core --depth Infinity`，可以看到如下结果：
+
+```
+devDependencies:
+@modern-js/app-tools 1.7.0
+└── @modern-js/core 1.13.0
+```
+
+---
+
+### 安装依赖时提示 The engine "node" is incompatible？
+
+安装依赖时如果出现以下报错提示，说明当前环境使用的 Node.js 版本过低，需要升级 Node.js 到更高版本。
+
+```bash
+The engine "node" is incompatible with this module.
+
+Expected version ">=14.17.6". Got "12.20.1"
+```
+
+使用 Modern.js 时，建议使用 [Node.js 14.x](https://nodejs.org/download/release/latest-v14.x/) 或 [Node.js 16.x](https://nodejs.org/download/release/latest-v16.x/) 的最新版本。
+
+如果当前环境的 Node.js 版本低于上述要求的版本，则可以使用 [nvm](https://github.com/nvm-sh/nvm) 或 [fnm](https://github.com/Schniz/fnm) 等工具进行版本切换。
+
+下面是使用 nvm 的示例：
+
+```
+# 安装 Node.js v14
+nvm install 14
+
+# 切换到 Node 14
+nvm use 14
+
+# 将 Node 14 设置为默认版本
+nvm default 14
+```
+
+在本地开发环境推荐使用 [fnm](https://github.com/Schniz/fnm)，它的用法与 nvm 相似，但拥有比 nvm 更好的性能。
+
+---
+
+### 升级依赖后出现 ReactNode 类型错误？
+
+升级项目的依赖后，如果出现以下类型报错，说明项目中安装了错误的 `@types/react` 版本。
+
+```bash
+The types returned by 'render()' are incompatible between these types.
+Type 'React.ReactNode' is not assignable to type 'import("/node_modules/@types/react/index").ReactNode'.
+Type '{}' is not assignable to type 'ReactNode'.
+```
+
+出现这个问题的原因是 React 18 与 React 16/17 中的 ReactNode 类型定义不同，如果项目中出现多个不同 `@types/react` 版本，就会出现 ReactNode 类型冲突，导致以上报错。
+
+解决方法为将项目中的 `@types/react` 和 `@types/react-dom` 锁定在统一的版本上，比如 `v17`。
+
+```json
+{
+  "@types/react": "^17",
+  "@types/react-dom": "^17"
+}
+```
+
+关于锁定依赖版本的方法，请参考上方的 `如何锁定项目中的某个依赖版本？`。
+
+---
+
+### 执行 pnpm install 之后，控制台出现 peer dependencies 相关 warning？
+
+出现该警告的原因是，某些三方 npm 包声明的 peer dependencies 版本范围与 Modern.js 中安装的版本范围不一致。
+
+绝大多数情况下，peer dependencies 的警告不会影响项目运行，不需要额外进行处理，请忽略相关 warning。

package/zh/tutorials/first-app/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "创建第一个应用",
+  "position": 2,
+  "collapsed": false
+}

package/zh/tutorials/first-app/c01-getting-started/1.1-prerequisites.md

@@ -0,0 +1,25 @@
+---
+title: 环境准备
+---
+
+从本章节开始，我们将进入实战教程部分。
+
+在实战教程中，我们将会从环境准备开始，从简单到复杂，一步一步搭建一个真实的项目。
+
+基于 Modern.js 框架的项目，自带全套工程环境和工程能力，对仓库目录之外的环境几乎没有任何依赖，只需要安装以下少数几个最基本的工具。
+
+## 1. Node.js
+
+需要 [Node.js LTS](https://github.com/nodejs/Release)，并确保 Node 版本大于等于 14.17.6。
+
+Modern.js 推荐在开发环境里先安装 [nvm](https://github.com/nvm-sh/nvm#install--update-script)，在 shell 里集成[自动切换 node 版本的脚本](https://github.com/nvm-sh/nvm#deeper-shell-integration)。
+
+然后只要仓库根目录下有内容为 `lts/fermium` 或 `lts/erbium` 的 `.nvmrc` 文件，进入这个仓库时就会自动安装或切换到正确的 Node.js 版本。
+
+## 2. pnpm
+
+推荐使用 [pnpm](https://pnpm.io/installation) 来管理项目依赖：
+
+```bash
+npm install -g pnpm
+```

package/zh/tutorials/first-app/c01-getting-started/1.2-minimal-mwa.md

@@ -0,0 +1,118 @@
+---
+title: 创建最简单的应用工程
+---
+
+## 开始创建
+
+### 1. 创建项目根目录和源代码目录
+
+我们创建名为 `hello-modern` 的项目：
+
+```bash
+mkdir -p hello-modern/src
+cd hello-modern
+```
+
+接下来都在项目根目录下执行命令。
+
+### 2. 在 src 目录下，创建 App.jsx
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+touch src/App.jsx
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows" >
+
+```bash
+ni src/App.jsx
+```
+
+</TabItem>
+</Tabs>
+
+在 App.jsx 里默认导出一个 React 组件，作为应用的根组件。
+
+```js title="src/App.jsx"
+export default function App() {
+  return <div>Hello World!</div>;
+}
+```
+
+### 3. 添加框架依赖
+
+在项目根目录下创建 `package.json`：
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+touch package.json
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```bash
+ni package.json
+```
+
+</TabItem>
+</Tabs>
+
+
+复制以下内容到文件里：
+```json
+{
+  "name": "hello-modern",
+  "scripts": {},
+  "dependencies": {
+    "react": "^17",
+    "react-dom": "^17",
+    "@modern-js/runtime": "^1.0.0"
+  },
+  "devDependencies": {
+    "@modern-js/app-tools": "^1.0.0"
+  }
+}
+```
+
+### 4. 添加框架命令
+
+添加本章节要用的 3 个命令到 `package.json` 的 npm scripts 里：
+
+```json
+"scripts": {
+  "new": "modern new",
+  "dev": "modern dev",
+  "build": "modern build",
+  "start": "modern start"
+},
+```
+
+## 创建完成
+
+一个基于 Modern.js 框架的应用工程，到这里就已经创建完成了。
+
+目录结构如下：
+
+```md
+.
+├── src/
+│   └── App.jsx
+└── package.json
+```
+
+可以看到，由于 Modern.js 框架的**默认零配置、约定优于配置、开箱即用、避免样板文件、Universal App** 等设计，即使不借助任何脚手架、生成器、项目模板等工具，纯手动搭建一个项目，整个过程也是极其简单的。
+
+## 安装依赖
+
+```bash
+pnpm install
+```

package/zh/tutorials/first-app/c01-getting-started/1.3-dev-command.md

@@ -0,0 +1,29 @@
+---
+title: 调试项目
+---
+
+我们已经创建了一个最简单的应用工程，接下来执行 `pnpm run dev` 命令进入开发调试：
+
+```bash
+pnpm run dev
+```
+
+执行后，控制台出现以下提示：
+
+```bash
+App running at:
+
+  > Local:    http://localhost:8080/
+```
+
+访问运行结果中的 URL 可以看到应用工程的运行效果：
+
+![bash](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/display.png)
+
+:::info 注
+在 iTerm2 这样的现代终端里，按住 CMD/Alt 键，上面的 URL 会显示为链接，可以点击访问。
+:::
+
+保持命令继续运行，修改 `src/App.jsx`，把 Hello World 改成 Hello Modern.js。
+
+因为框架默认支持 [HMR](https://webpack.js.org/concepts/hot-module-replacement/)，可以看到 `http://localhost:8080/` 里的内容会自动变成 Hello Modern.js。

package/zh/tutorials/first-app/c01-getting-started/1.4-enable-ssr.md

@@ -0,0 +1,44 @@
+---
+title: 启用 SSR
+---
+
+上一小节我们学习了如何使用 Modern.js 调试项目，本小节我们将学习如何快速开启 SSR（服务端渲染）。
+
+在项目根目录下创建 `modern.config.js`：
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+touch modern.config.js
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```bash
+ni modern.config.js
+```
+
+</TabItem>
+</Tabs>
+
+在 `modern.config.js` 中添加如下配置：
+
+```js title="modern.config.js"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: true,
+  },
+});
+```
+
+这样项目的 SSR 就已经开启了，重新执行 `pnpm run dev` 看看效果吧。
+
+用 Chrome 打开 `view-source:http://localhost:8080/`，查看 HTML 文件源代码，可以看到 root 根元素下存在已经在服务器端渲染好的 HTML。
+
+:::info 注
+Modern.js 框架使用 SSR 不需要自建 Web Server，开发者可以专注于 App 的开发。
+:::

package/zh/tutorials/first-app/c01-getting-started/1.5-start-command.md

@@ -0,0 +1,18 @@
+---
+title: 运行项目
+---
+
+`dev` 命令只是专用于开发环境中的调试运行。要正式（生产环境水平）的运行项目，可以先后运行 `build` 和 `start` 命令：
+
+```bash
+pnpm run build
+pnpm run start
+```
+
+用 Chrome 打开 `view-source:http://localhost:8080/`，查看 HTML 文件源代码，可以看到 HTML 本身和所有静态文件都符合生产环境标准。
+
+:::info 注
+基于 Modern.js 框架的项目，不需要借助其他服务器（比如 Nginx），可以直接运行。
+
+由于在任意机器、实例或容器上都能等价的运行，所以在本地机器上就能及时发现和调试线上环境中的很多问题。
+:::

package/zh/tutorials/first-app/c01-getting-started/1.6-create-repo.md

@@ -0,0 +1,31 @@
+---
+title: 创建 Git 仓库
+---
+
+经过以上操作，现在项目的目录结构变成了这样：
+
+```md
+.
+├── node_modules/
+├── dist/
+├── src/
+│   └── App.jsx
+├── package.json
+└── pnpm-lock.yaml
+```
+
+`dist` 和 `log` 都是框架生成的构建产物和运行产物，不应该进入仓库索引，需要在项目根目录下添加一个 `.gitignore`，内容：
+
+```txt
+node_modules/
+dist/
+*.log*
+```
+
+然后可以执行 `git init` 等命令创建仓库。
+
+虽然手动创建一个 Modern.js 项目也很简单，但如果用 Modern.js 开发套件提供的工具，自动创建项目还可以更方便，并且获得更多开箱即用的最佳实践（比如上面的 .gitignore 等等）。
+
+---
+
+> 本章节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c01/hello-modern)。

package/zh/tutorials/first-app/c01-getting-started/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "1: 手动创建应用工程"
+}

package/zh/tutorials/first-app/c02-generator-and-studio/2.1-generator.md

@@ -0,0 +1,87 @@
+---
+title: ​用命令行工具创建项目​​
+---
+
+上一章节中，我们介绍了如何手动创建一个 Modern.js 应用工程。
+
+这一章节中，我们将会学习使用命令行工具，更方便的创建。
+
+可以用已存在的空目录来创建项目：
+
+```bash
+mkdir hello-modern
+
+cd hello-modern
+
+npx @modern-js/create
+```
+
+也可以用新目录来创建项目：
+
+```bash
+npx @modern-js/create hello-modern
+
+cd hello-modern
+```
+
+`@modern-js/create` 是 Modern.js 生成器。不要全局安装 `@modern-js/create`，用 npx 按需运行，可以始终运行最新版。
+
+生成器会提供一个可交互的问答界面，根据后续的问答结果，按需运行不同的【 微生成器（micro-generator）】，在生成项目之后也会自动安装依赖、创建 git 仓库。
+
+:::info 微生成器（micro-generator）
+
+传统脚手架通常提供整个项目级别的生成器，基于模板，一用即抛，生成完项目之后，对后续的业务迭代没有帮助。
+
+微生成器关注的是项目的整个生命周期，既可以生成项目中各种粒度各种类型的文件模块（比如教程后面会提到的 entry、component、model 等），也可以生成抽象的业务逻辑（可能不创建新文件，而是在现有文件上做自动重构）。微生成器不是只在最初创建项目的时候使用的一次性工具，而是伴随项目后续迭代过程的工具箱。Modern.js 也可以支持业务项目添加自己业务专用的微生成器。
+
+Modern.js 生成器是基于微生成器和应用工程（Universal App，不需要多套模板）的项目生成器，会在问答过程中，按需加载不同的微生成器，动态生成不同的初始文件和代码或修改重组已有的文件和代码。在这种模式下，业务开发者可以方便地对 Modern.js 生成器进行定制，实现个性化的业务工程方案生成器。
+:::
+
+### 初始化项目
+
+Modern.js 生成器会通过交互式的问题获取一些必要信息，动态生成最合适的项目内容，我们先按以下选择创建：
+
+```bash
+# 请选择你想创建的工程类型
+❯ 应用
+  模块
+  Monorepo
+
+# 请选择开发语言
+  TS
+❯ ES6+
+
+# 请选择包管理工具
+❯ pnpm
+  Yarn
+
+# 是否需要支持以下类型应用
+❯ 不需要
+  Electron
+
+# 是否需要调整默认配置
+❯ 否
+  是
+```
+
+项目生成后，在项目根目录执行 `pnpm run dev` 就可以直接进行调试了：
+
+![vsc-alert](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/init.png)
+
+### 扩展项目
+
+如上所述，微生成器是伴随项目后续迭代过程中的工具箱，可以使用 `pnpm run new` 在需要的时候来扩展项目。
+
+执行 `pnpm run new` 后，我们按照以下选择，开启可选的 Tailwind CSS 支持：
+
+```bash
+# 请选择你想要的操作
+  创建工程元素
+❯ 启用可选功能
+
+# 启用可选功能
+❯ 启用 Tailwind CSS 支持
+  ...
+```
+
+选择 **启用 Tailwind CSS 支持**，等待命令运行结束，可以看到在 `package.json` 中新增了 `@modern-js/plugin-tailwindcss` 依赖，并且依赖已经完成安装。

package/zh/tutorials/first-app/c02-generator-and-studio/2.2-boilerplates.md

@@ -0,0 +1,28 @@
+---
+title: 样板文件
+---
+
+生成的项目结构：
+
+```md
+.
+├── .vscode/
+├── src/
+│   ├── .eslintrc.json
+│   ├── App.css
+│   └── App.jsx
+├── .editorconfig
+├── .gitignore
+├── .npmrc
+├── .nvmrc
+├── README.md
+├── package.json
+└── pnpm-lock.yaml
+```
+
+和上一章节手动创建出来的项目一样，仍然是零配置、极简和轻量的，但功能更完整，最佳实践开箱即用，比如：
+
+1. 提供了 IDE 相关支持，下一节会详细介绍。
+2. 集成了 Modern.js Lint 规则集，按照最佳实践启用，省去很多配置工作。
+3. 声明了 Node.js 版本。如果你按照[上一节的推荐](../c01-getting-started/1.1-prerequisites.md)，在系统里启用了[自动切换 node 版本的脚本](https://github.com/nvm-sh/nvm#automatically-call-nvm-use)，进入项目目录时，nvm 会自动安装和切换到项目声明的 Node.js 版本。
+4. 包含 Modern.js 框架的全套命令。

package/zh/tutorials/first-app/c02-generator-and-studio/2.3-configuration.md

@@ -0,0 +1,21 @@
+---
+title: ​配置项目
+---
+
+通过命令行工具创建的 Modern.js 项目，在 `package.json` 文件中，存在 `modernConfig` 字段。
+
+我们也可以创建 `modern.config.js` 配置文件。
+
+这两处都可以进行 Modern.js 项目的配置，并且 `modernConfig` 字段中的配置优先级高于 `modern.config.js` 中相同的内容。
+
+:::info 注
+
+如果配置为函数，则必须使用 `modern.config.js`。
+
+:::
+
+我们可以在 `modernConfig` 或 `modern.config.js` 中配置诸如 Server Port、Document 元信息、Webpack 选项等。
+
+---
+
+> 本章节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c02/hello-modern)。

package/zh/tutorials/first-app/c02-generator-and-studio/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "2: 自动创建应用工程"
+}

package/zh/tutorials/first-app/c03-ide/3.1-setting-up.md

@@ -0,0 +1,55 @@
+---
+title: ​初始化 IDE​​​​
+---
+
+上一章节中，我们已经创建了一个新的 Modern.js 应用工程。
+
+在开始写代码之前，我们将会在这一章节里先确认 IDE 相关功能。
+
+Modern.js 框架默认提供了对 VS Code 和 WebStorm 的支持，本章以 VS Code 为例。
+
+## 用 VS Code 打开项目根目录
+
+```bash
+cd hello-modern/
+code .
+```
+
+![vsc-alert](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/vsc-mwa.png)
+
+:::info 补充信息
+必须打开项目根目录，不能打开其他子目录或父目录，否则 IDE 支持不会生效。
+:::
+
+## 安装插件
+
+点击左侧栏上的插件（Extensions）面板，过滤 `@recommended` 列表，可以看到这里分为工作区推荐插件（Workspace Recommendations）和其他推荐插件（Other Recommendations）。
+
+![vsc-alert](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/vsc-plugin.png)
+
+点击工作区推荐插件顶部的下载按钮，安装当前仓库推荐的（也就是 Modern.js 框架推荐的）所有 VS Code 插件，等待全部安装成功，重启 VS Code 让插件生效。
+
+如果 VS Code 弹出这个确认框，点击 Allow 即可：
+
+![vsc-alert](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/vsc-alert.png)
+
+也可以检查 VS Code 底栏右侧显示的 ESLint 状态，或 VS Code 的 Problem 面板，比如如果有下面这样的提示：
+
+![vsc-bottom-bar](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/vsc-bottom-bar.png)
+
+点击底栏上的 ESLint 就会弹出上面的对话框。
+
+到这里，不需要做任何配置，IDE 就已经准备就绪，可以开始写代码了。
+
+:::info 注
+这些 VS Code 插件不会影响性能，如果实在不想一键安装所有插件，至少要安装以下插件：
+
+- editorconfig
+- eslint
+- vscode-styled-components
+- language-postcss
+- eslint-disable-snippets
+:::
+
+本章节接下来的步骤，也起到检查 IDE 功能的作用，任一步骤不符合描述，都说明有问题。
+