@modern-js/main-doc 2.0.0-beta.3 → 2.0.0-beta.5

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

@@ -1,118 +0,0 @@
----
-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": "^2.0.0"
-  },
-  "devDependencies": {
-    "@modern-js/app-tools": "^2.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

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

@@ -1,47 +0,0 @@
----
-title: 启用 SSR
----
-
-上一小节我们学习了如何使用 Modern.js 调试项目，本小节我们将学习如何快速开启 SSR（服务端渲染）。
-
-在项目根目录下创建 `modern.config.js`：
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-touch modern.config.ts
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```bash
-ni modern.config.ts
-```
-
-</TabItem>
-</Tabs>
-
-在 `modern.config.ts` 中添加如下配置：
-
-```typescript title="modern.config.ts"
-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

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

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

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

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

@@ -1,79 +0,0 @@
----
-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
-```
-
-项目生成后，在项目根目录执行 `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

@@ -1,34 +0,0 @@
----
-title: 样板文件
----
-
-生成的项目结构：
-
-```md
-.
-├── .eslintrc.js
-├── .gitignore
-├── .husky
-├── .idea
-├── .npmrc
-├── .nvmrc
-├── .prettierrc
-├── .vscode
-├── README.md
-├── modern.config.js
-├── package.json
-├── src
-│   ├── .eslintrc.js
-│   └── routes
-│       ├── index.css
-│       ├── layout.jsx
-│       └── page.jsx
-└── 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

@@ -1,19 +0,0 @@
----
-title: ​配置项目
----
-
-通过命令行工具创建的 Modern.js 项目，会默认生成 `modern.config.js` 配置文件。
-
-Modern.js 也支持使用 `package.json` 文件中的 `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

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

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

@@ -1,55 +0,0 @@
----
-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/zq-uylkvT/ljhwZthlaukjlkulzlp/vsc-mwa.jpeg)
-
-:::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 功能的作用，任一步骤不符合描述，都说明有问题。
-

package/zh/tutorials/first-app/c03-ide/3.2-hints-in-ide.md

@@ -1,60 +0,0 @@
----
-title: IDE 中的自动提示
----
-
-打开任意 JS/TS 文件（比如 `src/routes/page.tsx`），底部状态栏右侧应该有显示 ESLint，点击可以看到运行 log，应该没有报错。
-
-接下来对 `page.jsx` 代码做如下修改（修改过程中不要保存），增加无用的函数参数、去掉换行、单引号改成双引号、增加缩进（可以直接复制下面的代码替换 App.jsx 的内容），注意修改过程中**先不要保存文件**。
-
-```js
-import './index.css';
-
-const Index = (a) => (
-      <div className="container-box">
-    <main>
-      <div className='logo'>
-        <img
-          src="https://lf3-static.bytednsdoc.com/obj/eden-cn/ylaelkeh7nuhfnuhf/modernjs-cover.png"
-          width="300"
-          alt="Modern.js Logo"
-        />
-      </div>
-      <p className="description">
-        Get started by editing <code className="code">src/routes/page.tsx</code>
-      </p>
-      <div className="grid">
-        <a href="https://modernjs.dev/docs/start" className="card">
-          <h2>Quick Start</h2>
-        </a>
-        <a href="https://modernjs.dev/docs/guides" className="card">
-          <h2>Handbook</h2>
-        </a>
-        <a href="https://modernjs.dev/docs/apis/app/overview" className="card">
-          <h2>API Reference </h2>
-        </a>
-        <a
-          href="https://modernjs.dev/blog"
-          target="_blank"
-          rel="noopener noreferrer"
-          className="card"
-        >
-          <h2>Blog</h2>
-        </a>
-      </div>
-    </main>
-    <footer className="footer">
-      <a href="https://modernjs.dev" target="_blank" rel="noopener noreferrer">
-        Powered by Modern.js
-      </a>
-    </footer>
-  </div>
-);
-
-export default Index;
-
-
-```
-
-可以在 VS Code 中看到修改过的代码出现了问题提示，点击底部界面中的 Problems 一栏，可以看到问题列表。
-
-![vsc-with-error](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/vsc-with-error.jpeg)

package/zh/tutorials/first-app/c03-ide/3.3-autofix-in-ide.md

@@ -1,11 +0,0 @@
----
-title: IDE 中的自动修复
----
-
-直接保存当前文件（CMD/Ctrl + S），应该会看到代码风格相关的问题都自动被修复了（有时每次保存只能修复一部分，需要多保存几次，直到没变化）。
-
-只剩下**无用的函数参数**问题，需要人工修复：
-
-![vsc-how-to-fix](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/vsc-how-to-fix.jpeg)
-
-问题提示中，显示了这个问题来自 ESLint 的 `no-unused-vars` 规则，带下划线的是 ESLint 规则名称，按住 CMD/Alt 键点击，可以打开这条规则的文档，查看问题的解释和解决方法。

package/zh/tutorials/first-app/c03-ide/3.4-autofix-in-cli.md

@@ -1,63 +0,0 @@
----
-title: 命令行中的自动修复
----
-
-提交前的自动准入检查，跟 VS Code 里的保存一样，会尽可能自动格式化代码和修复问题，只有遇到无法自动修复的问题，才会报错阻止提交。
-
-我们添加一段可自动修复的问题代码（如果在 VS Code 里添加，保存时会自动修复，所以用 CLI 来添加）：
-
-```bash
-echo ';' >> src/routes/page.jsx
-```
-
-打开 `page.tsx`，可以看到末尾多了一个 ';'，有问题提示。
-
-提交代码：
-
-```bash
-git commit -am "test: 再次测试准入检查"
-git status
-```
-
-可以看到虽然仍然提交失败，但新增的问题被自动修复了。
-
-手动把参数 a 的问题修复（删除 a），再次添加 ';'，提交代码：
-
-```bash
-echo ';' >> src/routes/page.jsx
-git commit -am "test: 再次测试准入检查"
-git log HEAD --stat --graph --name-status
-```
-
-可以看到提交成功了，新增的问题被自动修复，并且自动被 stage。
-
-:::info 注
-在真实项目的开发中，对于以下情况，可以在提交时增加 -n 或 --no-verify 参数，破例跳过准入检查：
-1. Hotfix
-2. merge 过程中解决了冲突，变更的文件里包含别人的代码
-3. 旧项目迁移到 Modern.js，最初做统一自动修复的提交
-:::
-
-提交前的自动准入检查，只会检查和修复这次提交中有变更的文件（已经 stage 的文件），也就是说，只会强制要求这次工作过程中修改过的文件没有问题，不会要求你去解决这次工作无关的文件的问题。
-
-如果要对整个仓库的所有文件做 lint 检查和自动修复，可以手动执行 `lint` 命令，比如：
-
-```bash
-echo ';' >> src/routes/page.jsx
-pnpm run lint
-```
-
-:::info 注
-上述命令速度慢，不常用。旧项目刚迁移到 Modern.js 框架的时候，可以用这个命令对所有代码做一次自动修复，单独提交。
-:::
-
-本章节中，我们完成了编程环境的初始化和检查，熟悉了相关功能。下一章节开始，我们就可以开始写代码了。
-
-:::info 注
-Modern.js 是用 [Modern Lint](/docs/guides/advanced-features/eslint) 规则集来实现上述能力， 集成了 ESLint、TypeScript 支持、Prettier 等主流工具和最佳实践。
-:::
-
----
-
-> 本章节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c03/hello-modern)。
-

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

@@ -1,3 +0,0 @@
-{
-  "label": "3: 确认编程环境"
-}

package/zh/tutorials/first-app/c04-es6-plus-and-ts/4.1-use-es6-plus.md

@@ -1,54 +0,0 @@
----
-title: 使用 ES6+ 语法
----
-
-上一章节中，我们确认了当前 IDE 的编程环境。
-
-这一章节中，我们沿用上一章节的项目和编码环境，实现一个最简单的联系人列表。
-
-Modern.js 支持 `src` 目录下直接使用 ES6+（ES2015+）语法。
-
-我们把 `routes/page.jsx` 改成：
-
-```js
-const getAvatar = users =>
-  users.map(user => ({
-    ...user,
-    avatar: `https://avatars.dicebear.com/v2/identicon/${user.name}.svg`,
-  }));
-
-const getMockData = () =>
-  getAvatar([
-    { name: 'Thomas', email: 'w.kccip@bllmfbgv.dm' },
-    { name: 'Chow', email: 'f.lfqljnlk@ywoefljhc.af' },
-    { name: 'Bradley', email: 'd.wfovsqyo@gpkcjwjgb.fr' },
-    { name: 'Davis', email: '"t.kqkoj@utlkwnpwk.nu' },
-  ]);
-
-function Index() {
-  return (
-    <ul>
-      {getMockData().map(({ name, avatar, email }) => (
-        <li key={name}>
-          <img src={avatar} width={60} height={60} /> ---
-          <span>{name}</span> ---
-          <span>{email}</span>
-        </li>
-      ))}
-    </ul>
-  );
-}
-
-export default Index;
-```
-
-可以看到其中使用了多种 ES6+ 语法（注意生成 mockData 过程中使用了 [Pipeline Operator](https://babeljs.io/docs/en/babel-plugin-proposal-pipeline-operator) 语法），都不需要做任何配置。
-
-运行 `pnpm run dev`，查看运行结果：
-
-![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/contacts.png)
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c04/hello-modern)。
-