@modern-js/main-doc 2.4.0 → 2.6.0

package/zh/guides/topic-detail/model/model-communicate.mdx

@@ -88,7 +88,7 @@ export default function App() {
 ```
 
 :::info 补充信息
-Modern.js 默认开启 [自动生成 actions](./auto-actions.md)，所以 `stepModel` 中虽然没有手动定义 Actions，但可以使用自动生成的 `setState`。
+Modern.js 默认开启 [自动生成 actions](./auto-actions.mdx)，所以 `stepModel` 中虽然没有手动定义 Actions，但可以使用自动生成的 `setState`。
 
 :::
 

package/zh/guides/troubleshooting/_category_.json

@@ -1,5 +1,5 @@
 {
   "label": "常见问题",
-  "position": 6,
-  "collapsed": true
+  "position": 10,
+  "collapsed": false
 }

package/zh/index.md

@@ -1,4 +1,4 @@
 ---
 pageType: home
 ---
-# index
+# Modern.js - 基于 React 的渐进式现代 Web 开发框架

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

@@ -1,5 +1,5 @@
 {
-  "label": "联系人列表应用",
+  "label": "实战教程",
   "position": 2,
   "collapsed": false
 }

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

@@ -81,10 +81,9 @@ rm src/routes/index.css
 
 接下来，我们修改项目中的 `modern.config.ts`，开启 SSR 能力：
 
-```ts
+```ts title="modern.config.ts"
 import appTools, { defineConfig } from '@modern-js/app-tools';
 
-// https://modernjs.dev/docs/apis/app/config
 export default defineConfig({
   runtime: {
     router: true,

package/zh/tutorials/first-app/c03-css.mdx

@@ -124,7 +124,6 @@ Modern.js 集成了主流、轻量、通用的 Utility Class 工具库 [Tailwind
 import appTools, { defineConfig } from '@modern-js/app-tools';
 import tailwindcssPlugin from '@modern-js/plugin-tailwindcss';
 
-// https://modernjs.dev/docs/apis/app/config
 export default defineConfig({
   runtime: {
     router: true,
@@ -294,7 +293,7 @@ import '../styles/utils.css';
 ```
 
 :::info
-Modern.js 集成了 [PostCSS](/guides/basic-features/css/postcss)，支持现代 CSS 语法特性，比如 [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)。
+Modern.js 集成了 [PostCSS](/guides/css/postcss)，支持现代 CSS 语法特性，比如 [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)。
 
 :::
 

package/zh/tutorials/first-app/c06-model.mdx

@@ -10,8 +10,8 @@ title: 添加业务模型（状态管理）
 
 因此会开始编写一些跟 UI 完全无关的业务逻辑，如果继续写在组件代码中，会产生越来越多的面条式代码。为此，我们引入了一种叫做 **业务模型（Model）** 的代码模块，将这些业务逻辑和 UI 解耦。
 
-:::info意
-使用状态管理相关 API，需要先启用配置项 [runtime.state](/docs/configure/app/runtime/state)：
+:::info 注意
+使用状态管理相关 API，需要先启用配置项 [runtime.state](/configure/app/runtime/state)：
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';

package/zh/tutorials/first-app/c07-container.mdx

@@ -255,28 +255,28 @@ export default Index;
 ├── package.json
 ├── pnpm-lock.yaml
 ├── src
-│   ├── components
-│   │   ├── Avatar
-│   │   │   └── index.tsx
-│   │   └── Item
-│   │       └── index.tsx
-│   ├── containers
-│   │   └── Contacts.tsx
-│   ├── models
-│   │   └── contacts.ts
-│   ├── modern-app-env.d.ts
-│   ├── routes
-│   │   ├── archives
-│   │   │   └── page.tsx
-│   │   ├── layout.tsx
-│   │   └── page.tsx
-│   └── styles
-│       └── utils.css
+│   ├── components
+│   │   ├── Avatar
+│   │   │   └── index.tsx
+│   │   └── Item
+│   │       └── index.tsx
+│   ├── containers
+│   │   └── Contacts.tsx
+│   ├── models
+│   │   └── contacts.ts
+│   ├── modern-app-env.d.ts
+│   ├── routes
+│   │   ├── archives
+│   │   │   └── page.tsx
+│   │   ├── layout.tsx
+│   │   └── page.tsx
+│   └── styles
+│       └── utils.css
 └── tsconfig.json
 ```
 
 `components/` 里的**视图组件**，都是目录形式，如 `Avatar/index.tsx`。而 `containers/` 里的**容器组件**，都是单文件形式，如 `contacts.tsx`。**这是我们推荐的一种最佳实践**。
 
-在 ​ [添加 UI 组件（Component）](./c02-component.md) 章节提到过，视图组件用目录形式，是因为视图组件负责实现 UI 展示和交互细节，可以演变的复杂。用目录形式，可以方便增加子文件，包括专用的资源（图片等）、专用子组件、CSS 文件等。在这个目录内部可以随意重构，只考虑最小局部。
+在 ​ [添加 UI 组件（Component）](./c02-component.mdx) 章节提到过，视图组件用目录形式，是因为视图组件负责实现 UI 展示和交互细节，可以演变的复杂。用目录形式，可以方便增加子文件，包括专用的资源（图片等）、专用子组件、CSS 文件等。在这个目录内部可以随意重构，只考虑最小局部。
 
 而容器组件只负责连接，是一个胶水层，复杂的业务逻辑和实现细节都交给 View 层和 Model 层去实现。容器组件自己应该保持简单清晰，不应该包含复杂实现细节，所以不应该有内部结构。采用单文件形式不但更简洁，也能起到约束作用，提醒开发者不要把容器组件写复杂。

package/zh/tutorials/first-app/c08-entries.mdx

@@ -29,29 +29,29 @@ title: 添加应用入口
 ├── package.json
 ├── pnpm-lock.yaml
 ├── src
-│   ├── modern-app-env.d.ts
-│   ├── landing-page
-│   │   └── routes
-│   │       ├── index.css
-│   │       ├── layout.tsx
-│   │       └── page.tsx
-│   └── myapp
-│       ├── components
-│       │   ├── Avatar
-│       │   │   └── index.tsx
-│       │   └── Item
-│       │       └── index.tsx
-│       ├── containers
-│       │   └── Contacts.tsx
-│       ├── models
-│       │   └── contacts.ts
-│       ├── routes
-│       │   ├── archives
-│       │   │   └── page.tsx
-│       │   ├── layout.tsx
-│       │   └── page.tsx
-│       └── styles
-│           └── utils.css
+│   ├── modern-app-env.d.ts
+│   ├── landing-page
+│   │   └── routes
+│   │       ├── index.css
+│   │       ├── layout.tsx
+│   │       └── page.tsx
+│   └── myapp
+│       ├── components
+│       │   ├── Avatar
+│       │   │   └── index.tsx
+│       │   └── Item
+│       │       └── index.tsx
+│       ├── containers
+│       │   └── Contacts.tsx
+│       ├── models
+│       │   └── contacts.ts
+│       ├── routes
+│       │   ├── archives
+│       │   │   └── page.tsx
+│       │   ├── layout.tsx
+│       │   └── page.tsx
+│       └── styles
+│           └── utils.css
 └── tsconfig.json
 ```
 
@@ -91,13 +91,12 @@ mv src/myapp src/contacts
 
 我们可以在 Modern.js 配置文件里，自己写代码来控制项目的配置。
 
-现在，修改 `modern.config.ts` 里面添加内容：
+现在，修改 `modern.config.ts`，添加内容：
 
-```ts
+```ts title="modern.config.ts"
 import appTools, { defineConfig } from '@modern-js/app-tools';
 import tailwindcssPlugin from '@modern-js/plugin-tailwindcss';
 
-// https://modernjs.dev/docs/apis/app/config
 export default defineConfig({
   runtime: {
     router: true,

package/zh/tutorials/foundations/introduction.mdx

@@ -2,44 +2,29 @@
 title: 介绍
 sidebar_position: 1
 ---
+
 # 介绍
 
 欢迎来到 Modern.js 教程！
 
 阅读本栏目后，你将初步理解 Modern.js，并使用 Modern.js 创建第一个应用。
 
-:::note 关注
-加入我们的飞书群，咨询相关问题，了解最新动态。
-
-:::
-
 ## Modern.js 是什么
 
-**Modern.js** 是基于 React 的渐进式现代 Web 开发框架。
-
-框架内置多种开箱即用的开发工具，拥有极致的构建性能，支持零配置的渲染范式切换，一体化的 API 调用。并从三种工程方案出发（应用工程方案、模块工程方案，Monorepo 工程方案），支持全链路的前端研发。
-
-Modern.js 是字节跳动的底层前端研发框架，已经直接或间接的服务上千个应用，包括中后台、PC Web、H5 等多种应用场景。框架覆盖完整的生命周期，拥有完善的插件体系，提供高度定制能力。支持通过生成器插件自定义业务线专属的工程方案，定制各种功能扩展和业务需求，帮助开发者更快速的搭建应用。
-
-## 为什么使用 Modern.js
-
-Modern.js 能为开发者提供极致的**开发体验（Development Experience）**，让应用拥有更好的**用户体验（User Experience）**。
-
-在开发 React 应用过程中，开发者通常需要去为某些功能去设计实现方案，或是使用其他的库、框架来解决这些问题。Modern.js 支持 React 应用所需要的所有配置和工具，并内置**额外的功能和优化**。开发者可以使用 React 构建应用的 UI，然后逐步采用 Modern.js 的功能来解决常见的应用需求，如路由、数据获取、状态管理等。
-
-它主要包含以下特点：
-
-- 🪜 **渐进式**：使用最精简的模板创建项目，通过生成器逐步开启插件功能，定制解决方案。
-- 🏠 **一体化**：开发与生产环境 Web Server 唯一，CSR 和 SSR 同构开发，函数即接口的 API 服务调用。
-- 📦 **开箱即用**：默认 TS 支持，内置构建、ESLint、调试工具，全功能可测试。
-- 🌏 **周边生态**：自研状态管理、微前端、模块打包、Monorepo 方案等周边需求。
-- 🕸 **多种路由模式**：包含自控路由、基于文件约定的路由（嵌套路由）等。
-- 🚀 **独立构建核心**：支持多种打包工具，深度优化构建产物。
+如果你对 Modern.js 还不了解，可以先阅读 [Modern.js 介绍](/guides/get-started/introduction)。
 
-## 下一步
+## 实战教程
 
-{/* 如果你是前端初学者，可能会觉得这些概念有些复杂。我们提供了一些 [JavaScript 和 React](/tutorials/foundations/basic) 的学习资料，你可以先对它们做些了解。
+我们准备了一个创建「联系人列表应用」的实战教程，你可以按照教程一步步创建一个应用，并了解到 Modern.js 中的以下实践：
 
-如果你是有经验的开发者，希望了解如何使用 Modern.js，你可以尝试[创建第一个应用](/tutorials/first-app/c01-start)，或是阅读[指南](/guides/get-started/quick-start)。  */}
+- 创建项目
+- 使用 antd 组件库
+- 集成 Tailwind CSS
+- 客户端路由
+- 数据获取
+- 状态管理
+- 容器组件
+- 新建入口
+- ...
 
-如果你希望了解如何使用 Modern.js，可以尝试[创建第一个应用](/tutorials/first-app/c01-start)，或是阅读[指南](/guides/get-started/quick-start)。
+下面就让我们从 [创建项目](tutorials/first-app/c01-start) 开始吧！

package/en/apis/app/commands/_category_.json

@@ -1,8 +0,0 @@
-{
-  "label": "Commands",
-  "position": 0,
-  "link": {
-    "type": "doc",
-    "id": "apis/app/commands/index"
-  }
-}

package/en/apis/app/commands/build.mdx

@@ -1,39 +0,0 @@
----
-sidebar_position: 5
----
-# build
-
-```bash
-Usage: modern build [options]
-
-build application
-
-Options:
-  -c --config <config>  configuration file path, which can be a relative path or an absolute path
-  -h, --help            show command help
-  --analyze             analyze the bundle and view size of each module
-```
-
-`modern build` command will by default build production in `dist/`.
-
-you can configure the [`output.distPath`](/configure/app/output/dist-path) specifies the output directory for the product.
-
-## Analyze Bundle
-
-execute `npx modern build --analyze` command，can produce an HTML file that analyzes the volume of the bundle while packaging the production code:
-
-```
-Bundle Analyzer saved report to /example/dist/report.html
-File sizes after production build:
-
-  122.35 KB  dist/static/js/885.1d4fbe5a.js
-  2.3 KB     dist/static/js/main.4b8e8d64.js
-  761 B      dist/static/js/runtime-main.edb7cf35.js
-  645 B      dist/static/css/main.0dd3ecc1.css
-```
-
-Open the above HTML file in the browser, you can see the tile diagram of the packaged product, and perform package volume analysis and optimization:
-
-<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/mwa-build-analyze-8784f762c1ab0cb20935829d5f912c4c.png" />
-
-> this features based on [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer).

package/en/apis/app/commands/dev.mdx

@@ -1,61 +0,0 @@
----
-sidebar_position: 1
----
-
-# dev / start
-
-```bash
-Usage: modern dev / modern start [options]
-
-Development commands
-
-Options:
-  -e --entry <entry>    compiler by entry
-  -c --config <config>  configuration file path, which can be a relative path or an absolute path
-  -h, --help            show command help
-  --analyze             analyze the bundle and view size of each module
-  --api-only            only start API service
-```
-
-`modern dev` start a development server，watch file change，default support React Fast Refresh:
-
-`modern start` is an alias of `modern dev` command, the usage of the two are exactly the same.
-
-```bash
-$ modern dev
-
-info    Starting dev server...
-info    App running at:
-
-  > Local:    http://localhost:8080/
-  > Network:  http://192.168.0.1:8080/
-```
-
-## Compile Partial Pages
-
-In multi-page (MPA) projects, the `--entry` option can be added to specify one or more pages to compile. In this way, only part of the code in the project will be compiled, and the dev startup speed will be faster.
-
-For example, execute `modern dev --entry`, the entry selector will be displayed in the command line interface:
-
-```bash
-$ modern dev --entry
-
-? Please select the entry that needs to be built
-❯ ◯ foo
-  ◯ bar
-  ◯ baz
-```
-
-For example, if you select the `foo` entry, only the code related to the `foo` entry will be compiled, and the code of other pages will not be compiled.
-
-### Specify the page by parameter
-
-You can also specify the page name through parameters after `--entry`, and the names of multiple pages can be separated by commas.
-
-```bash
-# Compile foo page
-modern dev --entry foo
-
-# Compile foo and bar pages
-modern dev --entry foo,bar
-```

package/en/apis/app/commands/index.mdx

@@ -1,7 +0,0 @@
----
-type: ref
----
-
-# Commands
-
-This section covers all commands.

package/en/apis/app/commands/inspect.mdx

@@ -1,61 +0,0 @@
----
-sidebar_position: 7
----
-# inspect
-
-```
-Usage: modern inspect [options]
-
-Options:
-  --env <env>           view the configuration in the target environment (default: "development")
-  --output <output>     Specify the path to output in the dist (default: "/")
-  --verbose             Show the full function in the result
-  -c --config <config>  configuration file path, which can be a relative path or an absolute path
-  -h, --help            show command help
-```
-
-`modern inspect` command used to view the [Modern.js Builder config](https://modernjs.dev/builder/en/guide/basic/builder-config.html) and webpack config of the project.
-
-After executing the command `npx modern inspect` in the project root directory, the following files will be generated in the `dist` directory of the project:
-
-- `builder.config.js`: The Modern.js Builder config to use at build time.
-- `webpack.config.web.js`: The webpack config used by to use at build time.
-
-```bash
-➜ npx modern inspect
-
-Inspect config succeed, open following files to view the content:
-
-  - Builder Config: /root/my-project/dist/builder.config.js
-  - Webpack Config (web): /root/my-project/dist/webpack.config.web.js
-```
-
-## Configuration Env
-
-By default, the inspect command will output the development configs, you can use the `--env production` option to output the production configs:
-
-```bash
-modern inspect --env production
-```
-
-## Verbose content
-
-By default, the inspect command will omit the function content in the config object, you can use the `--verbose` option to output the full content of the function:
-
-```bash
-modern inspect --verbose
-```
-
-### SSR Configuration
-
-If the project has enabled SSR, an additional `webpack.config.node.js` file will be generated in the `dist/`, corresponding to the webpack configuration at SSR build time.
-
-```bash
-➜ npx modern inspect
-
-Inspect config succeed, open following files to view the content:
-
-  - Builder Config: /root/my-project/dist/builder.config.js
-  - Webpack Config (web): /root/my-project/dist/webpack.config.web.js
-  - Webpack Config (node): /root/my-project/dist/webpack.config.node.js
-```

package/en/apis/app/commands/lint.mdx

@@ -1,19 +0,0 @@
----
-sidebar_position: 4
-title: lint
----
-# lint
-
-```bash
-Usage: modern lint [options] [...files]
-
-lint and fix source files
-
-Options:
-  --no-fix    disable auto fix source file
-  -h, --help  display help for command
-```
-
-Run ESLint to check the syntax of the code. Normally, only the part of the code modified by this commit needs to be checked by `lint-staged` during the `git commit` phase.
-
-- `--no-fix` close auto fix by lint.

package/en/apis/app/commands/new.mdx

@@ -1,54 +0,0 @@
----
-sidebar_position: 2
----
-# new
-
-```bash
-Usage: modern new [options]
-
-Execution Generator in App
-
-Options:
-  -d, --debug            using debug mode to log something (default: false)
-  -c, --config <config>  set default generator config(json string)
-  --dist-tag <tag>       use specified tag version for its generator
-  --registry             set npm registry url to run npm command
-  -h, --help             show command help
-```
-
-The `modern new` command is used to enable features to an existing project.
-
-For example, add application entry, enable some optional features such as Tailwind CSS, micro frontend, etc.
-
-### Add Entry
-
-In the project, execute the `new` command to add entries as follows:
-
-```bash
-$ npx modern new
-? 请选择你想要的操作 创建工程元素
-? 创建工程元素 新建「应用入口」
-? 请填写入口名称 entry
-```
-
-### Enable Features
-
-In the project, execute the `new` command to enable features as follows:
-
-```bash
-$ npx modern new
-? 请选择你想要的操作 启用可选功能
-? 启用可选功能 (Use arrow keys)
-❯ 启用 Tailwind CSS 支持
-  启用「BFF」功能
-  启用「微前端」模式
-  启用「单元测试 / 集成测试」功能
-  启用「Visual Testing (Storybook)」模式
-```
-
-:::caution
-The `--config` parameter needs to use a JSON string.
-
-pnpm does not support the use of JSON strings as parameter values currently. Use `npm new` to turn on.【[Relate Issue](https://github.com/pnpm/pnpm/issues/3876)】
-
-:::

package/en/apis/app/commands/serve.mdx

@@ -1,27 +0,0 @@
----
-sidebar_position: 6
----
-# serve
-
-```bash
-Usage: modern serve [options]
-
-run server
-
-Options:
-  -c --config <config>  configuration file path, which can be a relative path or an absolute path
-  -h, --help            show command help
-  --api-only            only run API service
-```
-
-Usually use the `modern serve` command to enable project run in the production environment, and you need to execute the [`build'](/apis/app/commands/build) command in advance to build the product.
-
-By default, the project will run in `localhost:8080`, you can modify the Server port number with `server.port`:
-
-```js
-export default defineConfig({
-  server: {
-    port: 8081,
-  },
-});
-```

package/en/apis/app/commands/test.mdx

@@ -1,35 +0,0 @@
----
-sidebar_position: 3
----
-# test
-
-```bash
-Usage: modern test [options]
-
-Options:
-  -h, --help  show command help
-```
-
-:::caution
-`modern test` command need to execute the `new` command in advance to enable the `unit test/integration test`.
-
-:::
-
-`modern test` command will automatically run the test cases, the effect is as follows:
-
-```bash
-$ npx modern test
- PASS  src/tests/index.test.ts
-  The add method
-    ✓ should work fine. (2ms)
-
-Test Suites: 1 passed, 1 total
-Tests:       1 passed, 1 total
-Snapshots:   0 total
-Time:        0.994 s, estimated 1 s
-```
-
-:::info
-files match `*.test.(js|ts)` in `api/` or `src/` will be recognized as test cases by default。
-
-:::

package/en/apis/app/commands/upgrade.mdx

@@ -1,18 +0,0 @@
----
-sidebar_position: 8
----
-# upgrade
-
-```
-Usage: modern upgrade [options]
-
-upgrade Modern.js to latest version.
-
-Options:
-  --registry <registry>  specify npm registry (default: "")
-  -d,--debug             using debug mode to log something (default: false)
-  --cwd <cwd>            app directory (default: "")
-  -h, --help             show command help
-```
-
-Execute the command `npx modern upgrade` in the project, by default, dependencies in the `package.json` are updated to the latest version.

package/en/apis/app/hooks/index.mdx

@@ -1,7 +0,0 @@
----
-type: ref
----
-
-# Convention
-
-This section covers all documentation conventions.

package/en/apis/app/runtime/index.mdx

@@ -1,7 +0,0 @@
----
-type: ref
----
-
-# Runtime
-
-This section covers all APIs using `@modern-js/runtime`.

package/en/guides/advanced-features/index.mdx

@@ -1,7 +0,0 @@
----
-type: ref
----
-
-# Advanced Features
-
-This section covers advanced features of Modern.js.

package/en/guides/basic-features/css/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "CSS Solutions",
-  "position": 4
-}

package/zh/apis/app/commands/_category_.json

@@ -1,8 +0,0 @@
-{
-  "label": "命令",
-  "position": 0,
-  "link": {
-    "type": "doc",
-    "id": "apis/app/commands/index"
-  }
-}