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

package/zh/guides/get-started/quick-start.md

@@ -5,25 +5,9 @@ sidebar_position: 1
 
 ## 环境准备
 
-### Node.js
+import Prerequisites from '@site-docs/components/prerequisites.md'
 
-需要 [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/gallium` 的 `.nvmrc` 文件，进入这个仓库时就会自动安装或切换到正确的 Node.js 版本。
-
-### pnpm
-
-推荐使用 [pnpm](https://pnpm.io/installation) 来管理依赖：
-
-```bash
-npm install -g pnpm
-```
-
-:::note
-Modern.js 同样支持使用 `yarn`、`npm` 进行依赖管理。
-:::
+<Prerequisites />
 
 ## 安装
 
@@ -44,72 +28,16 @@ npx @modern-js/create myapp
 
 ## 初始化项目
 
-Modern.js 生成器会提供一个可交互的问答界面，根据结果初始化项目，按照默认的选择进行初始化：
 
-```bash
-? 请选择你想创建的工程类型 应用
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
-```
-
-在生成项目后，Modern.js 会自动安装依赖、创建 git 仓库。
-
-```bash
-[INFO] 依赖自动安装成功
-[INFO] git 仓库初始化成功
-[INFO] 创建成功！
-可在新项目的目录下运行以下命令：
-pnpm run dev          # 按开发环境的要求，运行和调试项目
-pnpm run build        # 按产品环境的要求，构建项目
-pnpm run start        # 按产品环境的要求，运行项目
-pnpm run lint         # 检查和修复所有代码
-pnpm run new          # 继续创建更多项目要素，比如应用入口
-```
+import InitApp from '@site-docs/components/init-app.md'
 
-:::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
-```
+<InitApp />
 
 ## 启动项目
 
-在项目中执行 `pnpm run dev` 即可启动项目：
-
-```bash
-$ pnpm run dev
-
-> modern dev
-
-info    Starting dev server...
-info    App running at:
-
-  > Local:    http://localhost:8080/
-  > Network:  http://10.94.58.87:8080/
-  > Network:  http://10.254.68.105:8080/
-
- Client ✔ done in 76.10ms
-```
-
-在浏览器中打开 `http://localhost:8000/`，能看到以下内容：
+import DebugApp from '@site-docs/components/debug-app.md'
 
-![dev](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/dev.png)
+<DebugApp />
 
 ## 使用配置
 

package/zh/guides/get-started/upgrade.md

@@ -16,28 +16,28 @@ $ pnpm run upgrade
 
 [INFO] [项目类型]: 应用
 [INFO] [Modern.js 最新版本]: 2.0.0
-[INFO] [当前项目 Modern.js 依赖已经为最新版本]: 2.0.0
+[INFO] 已更新 Modern.js 依赖至最新版本!
 ```
 
-可以看到项目 `package.json` 中的依赖已经更改到最新，执行 `pnpm install` 重新安装即可。
+可以看到项目 `package.json` 中的依赖已经更改到最新。
 
 ## 指定版本升级
 
-Modern.js 所有的官方包目前都使用统一版本号进行发布。
+Modern.js 所有的官方包目前都使用**统一版本号**进行发布。
 
 根据官网 Release Note，开发者也可以手动将项目升级到想要的版本。
 
 :::tip
-对所有 Modern.js 官方提供的包做统一升级，而不是升级单个依赖。
+当升级时，需要对 Modern.js 官方提供的所有包做统一升级，而不是升级单个依赖。
 :::
 
 ## 锁定子依赖
 
 当项目某个子依赖出现问题，而 Modern.js 无法立即更新时，可以使用包管理器锁定子依赖版本。
 
-### Pnpm
+### pnpm
 
-对于使用 Pnpm 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `pnpm i`：
+对于使用 pnpm 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `pnpm install`：
 
 ```json
 {
@@ -51,7 +51,7 @@ Modern.js 所有的官方包目前都使用统一版本号进行发布。
 
 ### Yarn
 
-对于使用 Yarn 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `yarn i`：
+对于使用 Yarn 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `yarn install`：
 
 ```json
 {
@@ -63,7 +63,7 @@ Modern.js 所有的官方包目前都使用统一版本号进行发布。
 
 ### Npm
 
-对于使用 Npm 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `npm i`：
+对于使用 Npm 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `npm install`：
 
 ```json
 {

package/zh/guides/topic-detail/model/quick-start.md

@@ -81,7 +81,7 @@ export default countModel;
 
 接下来，我们演示如何在组件中使用 Model。
 
-新建一个组件 Counter，在组件内通过 `useModel` API 使用 countModel：
+新建一个组件 Counter，在组件内通过 `useModel` API 使用 `countModel`：
 
 ```js
 import { useModel } from '@modern-js/runtime/model';

package/zh/guides/topic-detail/model/test-model.md

@@ -8,8 +8,8 @@ title: 测试 Model
 使用测试功能，需要先开启该功能。在项目根目录下，执行 `pnpm run new`，进行如下选择：
 
 ```bash
-? 请选择你想要的操作： 启用可选功能
-? 启用可选功能： 启用「单元测试 / 集成测试」功能
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用「单元测试 / 集成测试」功能
 ```
 
 即可开启测试功能支持。

package/zh/guides/topic-detail/monorepo/intro.md

@@ -2,7 +2,7 @@
 sidebar_position: 1
 ---
 
-# 简介
+# Monorepo 工程介绍
 
 Modern.js 提供了对于 Monorepo 工程方案的支持，其主要通过 `@modern-js/monorepo-tools` 来提供功能。
 

package/zh/guides/troubleshooting/dependencies.md

@@ -4,75 +4,6 @@ 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` 命令来查看项目里依赖的版本。

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

@@ -1,5 +1,5 @@
 {
-  "label": "创建第一个应用",
+  "label": "联系人列表应用",
   "position": 2,
   "collapsed": false
 }

package/zh/tutorials/first-app/c01-start.md

@@ -0,0 +1,94 @@
+---
+title: 创建项目
+---
+
+从这一章节开始，我们将进入实战教程部分。在实战教程中，我们将会从环境准备开始，从简单到复杂，一步一步搭建一个真实的项目。
+
+## 环境准备
+
+import Prerequisites from '@site-docs/components/prerequisites.md'
+
+<Prerequisites />
+
+## 初始化项目
+
+我们创建新的目录，通过命令行工具初始化项目：
+
+```bash
+mkdir myapp && cd myapp
+npx @modern-js/create
+```
+
+import InitApp from '@site-docs/components/init-app.md'
+
+<InitApp />
+
+## 调试项目
+
+import DebugApp from '@site-docs/components/debug-app.md'
+
+<DebugApp />
+
+## 修改代码
+
+我们将原本的示例代码删除，替换成一个简单的联系人列表：
+
+```tsx title="src/routes/page.tsx"
+const getAvatar = (users: Array<{ name: string; email: string }>) =>
+  users.map(user => ({
+    ...user,
+    avatar: `https://avatars.dicebear.com/v2/identicon/${user.name}.svg`,
+  }));
+
+const mockData = 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 App() {
+  return (
+    <ul>
+      {mockData.map(({ name, avatar, email }) => (
+        <li key={name}>
+          <img src={avatar} width={60} height={60} /> ---
+          <span>{name}</span> ---
+          <span>{email}</span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+export default App;
+```
+
+因为框架默认支持 [HMR](https://webpack.js.org/concepts/hot-module-replacement/)，可以看到 `http://localhost:8080/` 里的内容会自动变成 Hello Modern.js。
+
+删除多余的 css 文件，保持目录没有多余的文件：
+
+```bash
+rm src/routes/index.css
+```
+
+## 使用配置
+
+接下来，我们修改项目中的 `modern.config.ts`，开启 SSR 能力：
+
+```ts
+import { defineConfig } from '@modern-js/app-tools';
+
+// https://modernjs.dev/docs/apis/app/config
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+  },
+  server: {
+    ssr: true,
+  },
+});
+```
+
+重新执行 `pnpm run dev`，可以发现项目已经在服务端完成了页面渲染。

package/zh/tutorials/first-app/{c05-component/5.1-use-ui-library.md → c02-component.md}

@@ -1,29 +1,27 @@
 ---
-title: 使用主流组件库
+title: 编写 UI 组件
 ---
 
-上一章节中，我们学习了如何使用 ES6+ 与 TypeScript 语法编写 Modern.js 应用。
+上一章节中，我们学习了如何初始化项目，并使用配置修改 Modern.js 的默认行为。
 
-这一章节中，我们继续沿用上一章节的项目代码（注意是 TS 代码，不是 ES6+ 代码），继续完善联系人列表。
+这一章节中，我们继续沿用上一章节的项目代码，继续完善联系人列表。
 
-为了做更好的 UI 展示和交互，我们引入主流的组件库 Ant Design 来开发，使用 List 组件来代替原始的列表。
-
-先添加依赖:
+为了做更好的 UI 展示和交互，我们引入组件库 [Antd](https://ant.design/index-cn) 来开发，使用 `<List>` 组件来代替原始的列表。先添加依赖：
 
 ```bash
 pnpm add antd
 ```
 
-修改 `src/routes/page.tsx`，在顶部导入组件:
+修改 `src/routes/page.tsx`，在顶部导入组件：
 
-```js
+```ts
 import { List } from 'antd';
 ```
 
-修改 Index 组件的实现：
+修改 `<App>` 组件的实现：
 
-```ts
-function Index() {
+```tsx
+function App() {
   return (
     <div>
       <List
@@ -45,7 +43,7 @@ function Index() {
 
 执行 `pnpm run dev`，查看运行结果：
 
-![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/05/result.png)
+![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c02-antd-result.png)
 
 可以看到 Ant Design 导出的组件，已经具备了完整的样式。
 
@@ -53,6 +51,6 @@ function Index() {
 Modern.js 会[自动按需导入 Ant Design 组件需要的 CSS](https://github.com/ant-design/babel-plugin-import)。
 :::
 
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c05/hello-modern)。
+:::note
+我们也可以使用其他组件库来实现同样的功能，例如 [Arco Design](https://arco.design/)。
+:::