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

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

@@ -2,65 +2,59 @@
 title: IDE 中的自动提示
 ---
 
-打开任意 JS/TS 文件（比如 `src/App.jsx`），底部状态栏右侧应该有显示 ESLint，点击可以看到运行 log，应该没有报错。
+打开任意 JS/TS 文件（比如 `src/routes/page.tsx`），底部状态栏右侧应该有显示 ESLint，点击可以看到运行 log，应该没有报错。
 
-接下来对 `App.jsx` 代码做如下修改（修改过程中不要保存），增加无用的函数参数、去掉换行、单引号改成双引号、增加缩进（可以直接复制下面的代码替换 App.jsx 的内容），注意修改过程中**先不要保存文件**。
+接下来对 `page.jsx` 代码做如下修改（修改过程中不要保存），增加无用的函数参数、去掉换行、单引号改成双引号、增加缩进（可以直接复制下面的代码替换 App.jsx 的内容），注意修改过程中**先不要保存文件**。
 
 ```js
-import { Switch, Route } from '@modern-js/runtime/router';
+import './index.css';
 
-import './App.css';
-
-const App = (a) => (
-  <Switch>
-    <Route exact={true} path="/">
+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/App.tsx</code>
-          </p>
-          <div className="grid">
-            <a href="#" className="card">
-              <h2>Quick Start</h2>
-            </a>
-            <a href="#" className="card">
-              <h2>Handbook</h2>
-            </a>
-            <a href="#" className="card">
-              <h2>API Reference </h2>
-            </a>
-            <a
-              href="#"
-              target="_blank"
-              rel="noopener noreferrer"
-              className="card">
-              <h2>Community </h2>
-            </a>
-          </div>
-        </main>
-        <footer className="footer">
-          <a href="#" target="_blank" rel="noopener noreferrer">
-            Powered by Modern.JS
-          </a>
-        </footer>
+    <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>
-    </Route>
-    <Route path="*">
-      <div>404</div>
-    </Route>
-  </Switch>
+    </main>
+    <footer className="footer">
+      <a href="https://modernjs.dev" target="_blank" rel="noopener noreferrer">
+        Powered by Modern.js
+      </a>
+    </footer>
+  </div>
 );
 
-export default App;
+export default Index;
+
+
 ```
 
 可以在 VS Code 中看到修改过的代码出现了问题提示，点击底部界面中的 Problems 一栏，可以看到问题列表。
 
-![vsc-with-error](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/vsc-with-error.png)
+![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

@@ -6,6 +6,6 @@ title: IDE 中的自动修复
 
 只剩下**无用的函数参数**问题，需要人工修复：
 
-![vsc-how-to-fix](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/vsc-how-to-fix.png)
+![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

@@ -7,10 +7,10 @@ title: 命令行中的自动修复
 我们添加一段可自动修复的问题代码（如果在 VS Code 里添加，保存时会自动修复，所以用 CLI 来添加）：
 
 ```bash
-echo ';' >> src/App.jsx
+echo ';' >> src/routes/page.jsx
 ```
 
-打开 `App.jsx`，可以看到末尾多了一个 ';'，有问题提示。
+打开 `page.tsx`，可以看到末尾多了一个 ';'，有问题提示。
 
 提交代码：
 
@@ -24,7 +24,7 @@ git status
 手动把参数 a 的问题修复（删除 a），再次添加 ';'，提交代码：
 
 ```bash
-echo ';' >> src/App.jsx
+echo ';' >> src/routes/page.jsx
 git commit -am "test: 再次测试准入检查"
 git log HEAD --stat --graph --name-status
 ```
@@ -43,7 +43,7 @@ git log HEAD --stat --graph --name-status
 如果要对整个仓库的所有文件做 lint 检查和自动修复，可以手动执行 `lint` 命令，比如：
 
 ```bash
-echo ';' >> src/App.jsx
+echo ';' >> src/routes/page.jsx
 pnpm run lint
 ```
 

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

@@ -6,22 +6,9 @@ title: 使用 ES6+ 语法
 
 这一章节中，我们沿用上一章节的项目和编码环境，实现一个最简单的联系人列表。
 
-Modern.js 支持 `src` 目录下直接使用 ES6+（ES2015+）语法，原则上包括：
+Modern.js 支持 `src` 目录下直接使用 ES6+（ES2015+）语法。
 
-1. 已经进入 [Stage 4（完成阶段）](https://github.com/tc39/proposals/blob/master/finished-proposals.md)的语法，包括 ES2015（ES6）到 ES2020（ES11）以及后续版本。
-2. 部分很有用且确定性较强（重构也容易）的 [Stage 1（提案阶段）](https://github.com/tc39/proposals/blob/master/stage-1-proposals.md)、[Stage 2（草案阶段）](https://github.com/tc39/proposals#stage-2)、[Stage 3（候选阶段）](https://github.com/tc39/proposals#stage-3)语法，比如：
-
-     - [Decorators](https://babeljs.io/docs/en/babel-plugin-proposal-decorators)（默认使用 legacy 提案，可通过 `output.enableLatestDecorators` 使用新版提案）
-     - [Class Public Properties](https://babeljs.io/docs/en/babel-plugin-proposal-class-properties)
-     - [Class Private Properties](https://babeljs.io/docs/en/babel-plugin-proposal-private-property-in-object)、[Class Private Methods](https://babeljs.io/docs/en/babel-plugin-proposal-private-methods)
-     - [Pipeline Operator](https://babeljs.io/docs/en/babel-plugin-proposal-pipeline-operator)（默认为 minimal 提案）
-     - [Partial Application](https://babeljs.io/docs/en/babel-plugin-proposal-partial-application)
-     - [Bind Operator](https://babeljs.io/docs/en/babel-plugin-proposal-function-bind)
-     - [export default from](https://babeljs.io/docs/en/babel-plugin-proposal-export-default-from), [export namespace from](https://babeljs.io/docs/en/babel-plugin-proposal-export-namespace-from)
-     - [Optional Catch Binding](https://babeljs.io/docs/en/babel-plugin-proposal-optional-catch-binding)
-     - [Numeric Separator](https://babeljs.io/docs/en/babel-plugin-proposal-numeric-separator)
-
-我们把 `src/App.jsx` 改成：
+我们把 `routes/page.jsx` 改成：
 
 ```js
 const getAvatar = users =>
@@ -30,18 +17,18 @@ const getAvatar = users =>
     avatar: `https://avatars.dicebear.com/v2/identicon/${user.name}.svg`,
   }));
 
-const mockData =
-  [
+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' },
-  ] |> getAvatar;
+  ]);
 
-function App() {
+function Index() {
   return (
     <ul>
-      {mockData.map(({ name, avatar, email }) => (
+      {getMockData().map(({ name, avatar, email }) => (
         <li key={name}>
           <img src={avatar} width={60} height={60} /> ---
           <span>{name}</span> ---
@@ -52,7 +39,7 @@ function App() {
   );
 }
 
-export default App;
+export default Index;
 ```
 
 可以看到其中使用了多种 ES6+ 语法（注意生成 mockData 过程中使用了 [Pipeline Operator](https://babeljs.io/docs/en/babel-plugin-proposal-pipeline-operator) 语法），都不需要做任何配置。

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

@@ -15,7 +15,10 @@ import TabItem from '@theme/TabItem';
 <TabItem value="macOS" label="macOS" default>
 
 ```bash
-mv src/App.jsx src/App.tsx
+mv src/routes/layout.jsx src/routes/layout.tsx
+mv src/routes/page.jsx src/routes/page.tsx
+mv modern.config.js modern.config.ts
+touch src/modern-app-env.d.ts
 
 pnpm add typescript @types/react @types/react-dom @types/node -D
 
@@ -26,7 +29,10 @@ touch tsconfig.json
 <TabItem value="Windows" label="Windows">
 
 ```bash
-mv src/App.jsx src/App.tsx
+mv src/routes/layout.jsx src/routes/layout.tsx
+mv src/routes/page.jsx src/routes/page.tsx
+mv modern.config.js modern.config.ts
+ni src/modern-app-env.d.ts
 
 pnpm add typescript @types/react @types/react-dom @types/node -D
 
@@ -57,28 +63,46 @@ ni tsconfig.json
 }
 ```
 
-打开 `src/App.tsx`，把代码改成以下内容：
+`modern.config.ts` 内容修改如下：
 
 ```ts
-import React from 'react';
+import { defineConfig } from '@modern-js/app-tools';
 
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+  },
+});
+```
+
+`modern-app-env.d.ts` 内容如下
+
+```ts
+/// <reference types='@modern-js/app-tools/types' />
+```
+
+打开 `src/routes/page.tsx`，把代码改成以下内容：
+
+```ts
 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' },
-]);
+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 App() {
+function Index() {
   return (
     <ul>
-      {mockData.map(({ name, avatar, email }) => (
+      {getMockData().map(({ name, avatar, email }) => (
         <li key={name}>
           <img src={avatar} width={60} height={60} /> ---
           <span>{name}</span> ---
@@ -89,7 +113,7 @@ function App() {
   );
 }
 
-export default App;
+export default Index;
 ```
 
 可以看到，跟 ES6+ 的代码相比有以下不同：

package/zh/tutorials/first-app/c05-component/5.1-use-ui-library.md

@@ -14,26 +14,16 @@ title: 使用主流组件库
 pnpm add antd
 ```
 
-之前章节介绍过，Modern.js 支持在项目创建后继续为项目增加功能，我们执行 `pnpm run new`，进行如下选择，开启 Less 支持。
-
-```bash
-# 启用可选功能
-  启用 Tailwind CSS 支持
-❯ 启用 Less 支持
-  启用 Sass 支持
-  ...
-```
-
-修改 `src/App.tsx`，在顶部导入组件:
+修改 `src/routes/page.tsx`，在顶部导入组件:
 
 ```js
 import { List } from 'antd';
 ```
 
-修改 App 组件的实现：
+修改 Index 组件的实现：
 
 ```ts
-function App() {
+function Index() {
   return (
     <div>
       <List

package/zh/tutorials/first-app/c05-component/5.2-use-standalone-component.md

@@ -12,7 +12,7 @@ title: 使用独立开源组件
 pnpm add react-ladda ladda
 ```
 
-在 `src/App.tsx` 里导入组件，同时手动导入需要的 CSS：
+在 `src/routes/page.tsx` 里导入组件，同时手动导入需要的 CSS：
 
 ```ts
 import LaddaButton, { S, SLIDE_UP } from 'react-ladda';
@@ -46,26 +46,6 @@ import 'ladda/dist/ladda.min.css';
 
 `react-ladda` 组件库没有提供 types 文件，我们添加一个 `.d.ts` 文件：
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-touch src/modern-app-env.d.ts
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```bash
-ni src/modern-app-env.d.ts
-```
-
-</TabItem>
-</Tabs>
-
 在 `modern-app-env.d.ts` 中添加模块定义：
 
 ```ts

package/zh/tutorials/first-app/c06-css-and-component/6.1-css-in-js.md

@@ -21,7 +21,7 @@ Modern.js 开箱即用的支持 CSS Modules，但我们更推荐优先采用 CSS
 
 Modern.js 同样开箱即用的支持 styled-components，既不需要安装依赖，也不需要做任何配置。
 
-在 `src/App.tsx` 里修改顶部的代码：
+在 `src/routes/page.tsx` 里修改顶部的代码：
 
 ```js
 import styled from '@modern-js/runtime/styled';
@@ -63,30 +63,30 @@ import TabItem from '@theme/TabItem';
 <TabItem value="macOS" label="macOS" default>
 
 ```bash
-mkdir -p src/components/Avatar
-touch src/components/Avatar/index.tsx
+mkdir -p src/routes/components/Avatar
+touch src/routes/components/Avatar/index.tsx
 ```
 
 </TabItem>
 <TabItem value="Windows" label="Windows">
 
 ```powershell
-mkdir -p src/components/Avatar
-ni src/components/Avatar/index.tsx
+mkdir -p src/routes/components/Avatar
+ni src/routes/components/Avatar/index.tsx
 ```
 
 </TabItem>
 </Tabs>
 
-把 `src/App.tsx` 里的 Avatar 实现删掉，改成：
+把 `src/routes/page.tsx` 里的 Avatar 实现删掉，改成：
 
-```js
+```ts
 import Avatar from './components/Avatar';
 ```
 
-`src/components/Avatar/index.tsx` 的内容：
+`src/routes/components/Avatar/index.tsx` 的内容：
 
-```js
+```ts
 import styled from '@modern-js/runtime/styled';
 
 const Avatar = styled.img`

package/zh/tutorials/first-app/c06-css-and-component/6.2-utility-class.md

@@ -21,15 +21,10 @@ Modern.js 集成了主流、轻量、通用的 Utility Class 工具库 [Tailwind
 ```bash
 # 启用可选功能
 ❯ 启用 Tailwind CSS 支持
-  启用 Sass 支持
   ...
 ```
 
-:::info 注
-因为我们之前已经开启了 Less 支持，所以再次添加可选功能时，不再有这个选项。
-:::
-
-在 `src/App.tsx` 顶部引入 Tailwind CSS 的 css 文件，就可以开始快速实现专业的 UI：
+在 `src/routes/page.tsx` 顶部引入 Tailwind CSS 的 css 文件，就可以开始快速实现专业的 UI：
 
 ```js
 import 'tailwindcss/base.css';
@@ -46,22 +41,22 @@ import TabItem from '@theme/TabItem';
 <TabItem value="macOS" label="macOS" default>
 
 ```bash
-mkdir -p src/components/Item
-touch src/components/Item/index.tsx
+mkdir -p src/routes/components/Item
+touch src/routes/components/Item/index.tsx
 ```
 
 </TabItem>
 <TabItem value="Windows" label="Windows">
 
 ```powershell
-mkdir -p src/components/Item
-ni src/components/Item/index.tsx
+mkdir -p src/routes/components/Item
+ni src/routes/components/Item/index.tsx
 ```
 
 </TabItem>
 </Tabs>
 
-修改 `src/App.tsx`，把 `List` 的 `render` 实现交给 `Item` 组件：
+修改 `src/routes/page.tsx`，把 `List` 的 `render` 实现交给 `Item` 组件：
 
 ```js
 import { List } from 'antd';
@@ -83,7 +78,7 @@ const mockData = getAvatar([
   { name: 'Davis', email: '"t.kqkoj@utlkwnpwk.nu' },
 ]);
 
-function App() {
+function Index() {
   return (
     <div className="container lg mx-auto">
       <List
@@ -94,12 +89,12 @@ function App() {
   );
 }
 
-export default App;
+export default Index;
 ```
 
 在父容器的上使用了 [Utility Class](https://tailwindcss.com/docs/container) ，快速实现了最基本的 [RWD](https://tailwindcss.com/docs/responsive-design)（最大宽度、居中）。
 
-接下来实现 `src/components/Item/index.tsx`：
+接下来实现 `src/routes/components/Item/index.tsx`：
 
 ```tsx
 import Avatar from '../Avatar';

package/zh/tutorials/first-app/c06-css-and-component/6.3-postcss.md

@@ -17,28 +17,28 @@ import TabItem from '@theme/TabItem';
 <TabItem value="macOS" label="macOS" default>
 
 ```bash
-mkdir -p src/styles
-touch src/styles/utils.css
+mkdir -p src/routes/styles
+touch src/routes/styles/utils.css
 ```
 
 </TabItem>
 <TabItem value="Windows" label="Windows">
 
 ```powershell
-mkdir -p src/styles
-ni src/styles/utils.css
+mkdir -p src/routes/styles
+ni src/routes/styles/utils.css
 ```
 
 </TabItem>
 </Tabs>
 
-在 `src/App.tsx` 里导入 `utils.css`：
+在 `src/routes/page.tsx` 里导入 `utils.css`：
 
 ```js
 import './styles/utils.css';
 ```
 
-在 `src/styles/utils.css` 里实现一个叫作 `custom-text-gray` 的 Utility Class。
+在 `src/routes/styles/utils.css` 里实现一个叫作 `custom-text-gray` 的 Utility Class。
 
 ```css
 :root {
@@ -54,7 +54,7 @@ import './styles/utils.css';
 Modern.js 集成了 [PostCSS](/docs/guides/basic-features/css/postcss)，支持现代 CSS 语法特性，比如 [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*)。
 :::
 
-在 `src/components/Item/index.tsx` 里使用，把：
+在 `src/routes/components/Item/index.tsx` 里使用，把：
 
 ```js
 <div className="ml-4 flex-1 flex justify-between">

package/zh/tutorials/first-app/c06-css-and-component/6.4-design-system.md

@@ -61,7 +61,7 @@ export default defineConfig({
 });
 ```
 
-修改 `src/Item/index.tsx` 的 button 组件代码
+修改 `src/routes/components/Item/index.tsx` 的 button 组件代码
 
 ```js
 <button

package/zh/tutorials/first-app/c06-css-and-component/6.5-storybook.md

@@ -32,14 +32,14 @@ import TabItem from '@theme/TabItem';
 <TabItem value="macOS" label="macOS" default>
 
 ```bash
-touch src/components/Avatar/index.stories.tsx
+touch src/routes/components/Avatar/index.stories.tsx
 ```
 
 </TabItem>
 <TabItem value="Windows" label="Windows">
 
 ```powershell
-ni src/components/Avatar/index.stories.tsx
+ni src/routes/components/Avatar/index.stories.tsx
 ```
 
 </TabItem>

package/zh/tutorials/first-app/c06-css-and-component/6.6-testing.md

@@ -20,14 +20,14 @@ import TabItem from '@theme/TabItem';
 <TabItem value="macOS" label="macOS" default>
 
 ```bash
-touch src/components/Item/index.test.tsx
+touch src/routes/components/Item/index.test.tsx
 ```
 
 </TabItem>
 <TabItem value="Windows" label="Windows">
 
 ```powershell
-ni src/components/Item/index.test.tsx
+ni src/routes/components/Item/index.test.tsx
 ```
 
 </TabItem>
@@ -39,16 +39,16 @@ ni src/components/Item/index.test.tsx
 <TabItem value="macOS" label="macOS" default>
 
 ```bash
-mkdir -p src/components/Item/__tests__/
-touch src/components/Item/__tests__/index.tsx
+mkdir -p src/routes/components/Item/__tests__/
+touch src/routes/components/Item/__tests__/index.tsx
 ```
 
 </TabItem>
 <TabItem value="Windows" label="Windows">
 
 ```powershell
-mkdir -p src/components/Item/__tests__/
-ni src/components/Item/__tests__/index.tsx
+mkdir -p src/routes/components/Item/__tests__/
+ni src/routes/components/Item/__tests__/index.tsx
 ```
 
 </TabItem>
@@ -81,12 +81,6 @@ describe('Item', () => {
 });
 ```
 
-在之前章节创建的 `modern-app-env.d.ts` 文件 **顶部**（[`///` 语法只在文件顶部生效](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html#:~:text=Triple-slash%20directives%20are%20only%20valid%20at%20the%20top%20of%20their%20containing%20file.)） 加上类型定义：
-
-```ts
-/// <reference types="@modern-js/plugin-testing/type" />
-```
-
 :::info 注
 更多相关内容可以查看 [Test API](/docs/apis/app/runtime/testing/render)。
 :::
@@ -96,15 +90,12 @@ describe('Item', () => {
 ```bash
 > modern test
 
- PASS  src/components/Item/index.test.tsx
-  Item
-    ✓ should have contents (27 ms)
+ PASS  src/routes/components/Item/index.test.tsx
 
 Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
-Time:        1.048 s, estimated 2 s
-Ran all test suites.
+Time:        1.708 s
 ```
 
 ---