@modern-js/main-doc 2.0.3-alpha.0 → 2.2.0

package/zh/guides/topic-detail/monorepo/publish.mdx

@@ -0,0 +1,69 @@
+---
+sidebar_position: 4
+---
+
+# 可复用模块的发布
+
+在 Monorepo 中有时会需要把多个模块项目发布到 [NPM](https://www.npmjs.com/) 上，本章将要介绍如果在 Monorepo 中对子项目进行版本更新以及发布。
+
+## 准备工作
+
+接着 [子项目联调](/guides/topic-detail/monorepo/sub-project-interface) 章节的例子，我们对 `components` 模块进行发布。
+
+## 生成变更记录
+
+在开发阶段，当某个模块的功能开完完成之后，一般需要提交代码（例如提交到 [GitHub](https://github.com/) 上）并需要记录本次修改的内容。在 Modern.js 的 Monorepo 工程中，我们可以在 monorepo 根目录执行命令：
+
+```
+pnpm run change
+```
+
+然后根据提示选择变更或者将要发布的包以及选择包升级的版本，并填写变更信息。变更信息的内容可以包含此次开发的功能、修复的问题等。
+
+那么对于上面的例子，我们选择变更的项目为 `components`，并填写此次变更的内容：
+
+```
+$ modern change
+🦋  Which packages would you like to include? · components
+🦋  Which packages should have a major bump? · No items were selected
+🦋  Which packages should have a minor bump? · components
+🦋  Please enter a summary for this change (this will be in the changelogs). Submit empty line to open external editor
+🦋  Summary · add features
+🦋  === Releasing the following packages ===
+🦋  [Minor]
+🦋    components
+🦋  ╔════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
+🦋  ║                                                      ========= 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 /Users/demo/modern-js/official/monorepo-pnpm/.changeset/silent-tigers-run.md
+```
+
+该命令完成后，在 `.changeset` 中会有新的 `silent-tigers-run.md` 文件生成，其中包含了刚刚填写的信息，这些新生成的文件将用于后面发布流程中使用。**因此在提交代码的时候，需要将`.changeset` 目录下的文件一并提交**。
+
+## 版本更新
+
+在模块发布之前，还需要将模块的版本进行更新。。在 Modern.js 的 Monorepo 工程中，可以在 Monorepo 项目根目录下执行：
+
+```
+pnpm run bump
+```
+
+该命令会根据之前生成在 `.changeset` 目录下的文件自动更新对应模块的版本号和 CHANGELOG 信息，执行成功后会看到：
+
+```
+🦋  All files have been updated. Review them and commit at your leisure
+```
+
+## 发布
+
+最后执行 `pnpm run prepare --filter {./packages} && pnpm run release`，便可以发布对应的模块了。
+
+:::info 补充信息
+在上面的命令中 --filter \{./packages\} 用于筛选位于 `./packages` 目录下的子项目，可以通过 [PNPM Filtering](https://pnpm.io/filtering) 来了解更多它的使用。
+
+:::

package/zh/guides/topic-detail/monorepo/sub-project-interface.mdx

@@ -0,0 +1,179 @@
+---
+sidebar_position: 3
+---
+
+# 子项目联调
+
+本章将要介绍如何在 Monorepo 下进行子项目之间的联调使用。
+
+## 准备工作
+
+按照 [「创建子项目」](/guides/topic-detail/monorepo/create-sub-project) 章节的介绍（如果还没有看过，可以先了解一下），我们首先创建以下三个子项目：
+
+- 一个「应用」子项目
+- 一个「模块（内部）」子项目
+- 一个「模块」子项目
+
+执行 `pnpm run new`，并按照如下进行选择：
+
+**「应用」子项目：**
+
+```
+? 请选择你想创建的工程类型 应用
+? 请填写子项目名称 app
+? 请填写子项目目录名称 app
+? 请选择开发语言 TS
+```
+
+**「模块（内部）」子项目：**
+
+```
+? 请选择你想创建的工程类型 模块（内部）
+? 请填写子项目名称 internal-lib
+? 请填写子项目目录名称 internal-lib
+? 请选择开发语言 TS
+```
+
+**「模块」子项目：**
+
+```
+? 请选择你想创建的工程类型 模块
+? 请填写子项目名称 components
+? 请填写子项目目录名称 components
+? 请选择开发语言 TS
+```
+
+创建成功后，会得到以下项目：
+
+- `./apps/app`
+- `./packages/components`
+- `./features/internal-lib`
+
+然后修改一下默认的代码和新增文件：
+
+**重命名 `./pakcages/components/src/index.tsx`**
+
+```tsx
+import './index.css';
+
+export default function ({ text }: { text: string }) {
+  return (
+    <div>
+      This is UI Components Log: <p className="log">{text}</p>
+    </div>
+  );
+}
+```
+
+**新增 `./pakcages/components/src/index.css`**
+
+```css
+.log {
+  color: gray;
+}
+```
+
+**修改 `./features/internal-lib/src/index.ts`**
+
+```tsx
+export default function (text: string) {
+  return text.toUpperCase();
+}
+```
+
+**修改 `./apps/app/src/App.tsx`**
+
+```tsx
+import { Switch, Route } from '@modern-js/runtime/router';
+import formatString from 'internal-lib';
+import Comp from 'components';
+
+import './App.css';
+
+const App = () => (
+  <Switch>
+    <Route exact={true} path="/">
+      <div className="container-box">
+        <Comp text={formatString('hello world')} />
+        {/* 省略... */}
+      </div>
+    </Route>
+    <Route path="*">
+      <div>404</div>
+    </Route>
+  </Switch>
+);
+
+export default App;
+```
+
+到此为止我们创建了一个可以被发布到外部的组件项目、一个转换字符串的内部模块项目以及一个使用组件和内部模块的应用项目，如果直接运行应用项目还暂时无法正常使用。接下来将要介绍如何让它们能够互相联调使用，成功的使应用子项目 `apps/app` 正常运行。
+
+:::info 注
+启动 `apps/app` 项目之前需要先构建（`pnpm run build`） `packages/component`。
+
+:::
+
+由于 Modern.js 支持 pnpm 与 Yarn 的 Monorepo 工程，接下来会从这两个方面分别介绍。
+
+## 在使用 pnpm 的 Monorepo 中进行项目联调
+
+在 pnpm 的 Monorepo 项目中，我们通过在 `apps/app` 子项目下分别执行：
+
+```
+pnpm add components
+```
+
+以及
+
+```
+pnpm add internal-lib -D
+```
+
+:::info 注
+注意这里将 internal-lib 作为 `apps/app` 项目的开发依赖，因为在构建环境会被打包到构建产物中。
+
+:::
+
+将 `packages/components` 与 `features/internal-lib` 子项目加入到应用的依赖列表当中。
+
+执行成功后，在 `apps/app/package.json` 会发生如下变化：
+
+```json
+{
+  "dependencies": {
+++  "components": "workspace:^0.1.0"
+  },
+  "devDependencies": {
+++  "internal-lib": "workspace:^0.1.0"
+  },
+}
+```
+
+:::info 补充信息
+`workspace:^0.1.0` 是一种 PNPM 提供的 [Workspace 协议](https://pnpm.io/workspaces#workspace-protocol-workspace)。
+
+:::
+
+当依赖安装成功之后，我们还需要将 `packages/components` 进行构建，因为需要使用其构建产物。
+
+到此为止，`app/apps` 应用子项目可以正常的运行了。在修改 `features/internal-lib` 的源码，或者修改 `packages/components` 的源码并构建之后都会触发应用子项目的热更新。
+
+## 在使用 Yarn 的 Monorepo 中进行项目联调
+
+在 Yarn 的 Monorepo 项目中，默认情况下可以直接在 `apps/app` 应用项目中直接使用组件项目和内部模块项目。
+
+:::info 补充信息
+之所以可以直接在应用中使用使用组件项目和内部模块项目，是因为 Yarn 将这些子项目模块提升到了顶层的 `node_modules`内。
+
+:::
+
+但是由于组件 `components` 是非内部模块，因此建议在 `apps/app/package.json` 中进行依赖声明：
+
+```json
+{
+  "dependencies": {
+++  "components": "0.1.0"
+  },
+}
+```

package/zh/guides/troubleshooting/cli.mdx

@@ -0,0 +1,63 @@
+---
+sidebar_position: 2
+---
+
+# 命令行问题
+
+### 使用 pnpm 时无法正确传递命令行参数？
+
+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/index.md

@@ -0,0 +1,4 @@
+---
+pageType: home
+---
+# index

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

@@ -0,0 +1,100 @@
+---
+title: 创建项目
+---
+# 创建项目
+
+从这一章节开始，我们将进入实战教程部分。在实战教程中，我们将会从环境准备开始，从简单到复杂，一步一步搭建一个真实的项目。
+
+## 环境准备
+
+import Prerequisites from "@site-docs/components/prerequisites"
+
+<Prerequisites />
+
+## 初始化项目
+
+我们创建新的目录，通过命令行工具初始化项目：
+
+```bash
+mkdir myapp && cd myapp
+npx @modern-js/create
+```
+
+import InitApp from "@site-docs/components/init-app"
+
+<InitApp />
+
+## 调试项目
+
+import DebugApp from "@site-docs/components/debug-app"
+
+<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;
+```
+
+删除多余的 css 文件，保持目录没有多余的文件：
+
+```bash
+rm src/routes/index.css
+```
+
+因为框架默认支持 [HMR](https://webpack.js.org/concepts/hot-module-replacement/)，可以看到 `http://localhost:8080/` 里的内容会自动更新为：
+
+![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvt/ljhwZthlaukjlkulzlp/screenshot-20221214-141909.png)
+
+此刻的页面还没有样式。下一章节将展开这部分的内容。
+
+## 开启 SSR
+
+接下来，我们修改项目中的 `modern.config.ts`，开启 SSR 能力：
+
+```ts
+import appTools, { defineConfig } from '@modern-js/app-tools';
+
+// https://modernjs.dev/docs/apis/app/config
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+  },
+  server: {
+    ssr: true,
+  },
+  plugins: [appTools()],
+});
+```
+
+重新执行 `pnpm run dev`，可以发现项目已经在服务端完成了页面渲染。

package/zh/tutorials/first-app/c02-component.mdx

@@ -0,0 +1,59 @@
+---
+title: 编写 UI 组件
+---
+# 编写 UI 组件
+
+上一章节中，我们学习了如何初始化项目，并使用配置修改 Modern.js 的默认行为。
+
+这一章节中，我们继续沿用上一章节的项目代码，继续完善联系人列表。
+
+为了做更好的 UI 展示和交互，我们引入组件库 [Antd](https://ant.design/index-cn) 来开发，使用 `<List>` 组件来代替原始的列表。先添加依赖：
+
+```bash
+pnpm add antd
+```
+
+修改 `src/routes/page.tsx`，在顶部导入组件：
+
+```ts
+import { List } from 'antd';
+```
+
+修改 `<App>` 组件的实现：
+
+```tsx
+function App() {
+  return (
+    <div>
+      <List
+        dataSource={mockData}
+        renderItem={({ name, email, avatar }) => (
+          <List.Item key={name}>
+            <List.Item.Meta
+              avatar={<img alt="avatar" src={avatar} width={60} height={60} />}
+              title={name}
+              description={email}
+            />
+          </List.Item>
+        )}
+      />
+    </div>
+  );
+}
+```
+
+执行 `pnpm run dev`，查看运行结果：
+
+![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c02-antd-result.png)
+
+可以看到 Ant Design 导出的组件，已经具备了完整的样式。
+
+:::info 注
+Modern.js 会[自动按需导入 Ant Design 组件需要的 CSS](https://github.com/ant-design/babel-plugin-import)。
+
+:::
+
+:::note
+我们也可以使用其他组件库来实现同样的功能，例如 [Arco Design](https://arco.design/)。
+
+:::