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

package/en/docusaurus-plugin-content-docs/current/guides/concept/entries.md

@@ -0,0 +1,116 @@
+---
+title: Entries
+sidebar_position: 2
+---
+
+Entries are Modern.js default file convention, and each entry in the project is a separate page, corresponding to a server level route.
+
+Many configurations, such as HTML templates, Meta information, whether SSR is enabled, SSG, server level routing rules are divided by the entry dimension.
+
+## Single Entry and Multiple Entries
+
+Modern.js initialization project is a single entry, the project structure is as follows:
+
+```
+.
+├── src
+│   ├── modern-app-env.d.ts
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+├── package.json
+├── modern.config.ts
+├── pnpm-lock.yaml
+├── README.md
+└── tsconfig.json
+```
+
+Modern.js can easily switch from single entry to multiple entry. You can execute `pnpm run new` under the project to create entry through generator:
+
+```bash
+? Action: Create project element
+? Create project element: New "entry"
+? Entry name: new-entry
+```
+
+After execution, the `src/` directory will become the following structure:
+
+```
+.
+├── modern-app-env.d.ts
+├── myapp
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+└── new-entry
+    └── routes
+        ├── index.css
+        ├── layout.tsx
+        └── page.tsx
+```
+
+The original code was moved to the directory with the same name as the `name` in the `package.json`, and a new directory was created.
+
+After executing `pnpm run dev`, you can see that a `/new-entry` route has been added, and the migrated code route has not changed.
+
+:::note
+Modern.js will use the directory with the same name as the `name` in the `package.json` as the main entry, the default route is `/`, and the default route for other entries is `/{entryName}`.
+:::
+
+## Entry conditions
+
+By default, the Modern.js entry currently scans the file under `src/`, identifies the entry, and generates the corresponding server level route.
+
+:::tip
+You can change the entry directory to another directory by [source.entriesDir](/docs/configure/app/source/entries-dir).
+:::
+
+Not all first-level directories under `src/` will become project entrances. The directory where the entry is located must meet one of the following four conditions:
+
+
+1. Directory with `routes/`
+2. Has the `App.[jt]sx?` file
+3. With `index.[jt]sx?` file
+2. With `pages/` directory (compatible Modern.js 1.0)
+
+When the `src/` directory satisfies the entry feature, the Modern.js considers the current project to be a single entry application.
+
+:::tip
+Single entry The default entry name is `main`.
+:::
+
+When the project is not a single-entry application, Modern.js further look at the first-level directory under `src/`.
+
+## Difference between entries
+
+Entries to different conventions have different behaviors.
+
+### routes
+
+If the entry is the `routes/` convention, Modern.js will scan the files under `routes` at startup, and automatically generate the client route based on the file convention(react-router).
+
+For details, please refer to [Routing](/docs/guides/basic-features/routes).
+
+### App
+
+If the entry is the `App.[jt]sx?` convention, the developer can freely set the client route in this file, or not set the client route.
+
+For details, please refer to [Routing](/docs/guides/basic-features/routes).
+
+### Index
+
+Typically, the above two modes are sufficient, but when developers need to take over the React mount logic themselves, or take over the Webpack entry entirely, the `index.[jt]sx?`convention can be used.
+
+If the entry is the `index.[jt]sx?` convention, the Modern.js determines the build behavior based on whether the file has a default component export.
+
+For details, please refer to [customized App](/docs/guides/concept/entries#自定义-app).
+
+## configuration
+
+In Modern.js, you can manually configure the entry in `modern.config.[jt]s`, in addition to using the file convention to generate the entry.
+
+:::tip
+Details can be found in [source.entries](/docs/configure/app/source/entries).
+:::

package/en/docusaurus-plugin-content-docs/current/guides/get-started/quick-start.md

@@ -0,0 +1,162 @@
+---
+title: Quick Start
+sidebar_position: 1
+---
+
+## Environment
+
+### Node.js
+
+Requires [Node.js LTS](https://github.com/nodejs/Release) and ensures that the Node version is greater than or equal to 14.19.0, 16.x version is recommended.
+
+Modern.js recommend installing [nvm](https://github.com/nvm-sh/nvm#install--update-script) in the development environment and integrating [script to automatically switch node versions](https://github.com/nvm-sh/nvm#deeper-shell-integration) in the shell.
+
+Then there is a `.nvmrc` file with the content of `lts/fermium` or `lts/gallium` in the root directory of the repository, it will automatically install or switch to the correct Node.js version when entering the repository.
+
+### pnpm
+
+[pnpm](https://pnpm.io/installation) is recommended for package management.
+
+```bash
+npm install -g pnpm
+```
+
+:::note
+Modern.js also supports package management with `yarn` and `npm`.
+:::
+
+## Installation
+
+Modern.js provides the `@modern-js/create` tool to create projects. Don't install globally, use `npx` to run on demand.
+
+Projects can be created using an existing empty directory:
+
+```bash
+mkdir myapp && cd myapp
+npx @modern-js/create
+```
+
+Projects can also be created directly from the new directory:
+
+```bash
+npx @modern-js/create myapp
+```
+
+## Initialize
+
+import InitApp from '@site-docs/components/init-app.md'
+
+<InitApp />
+
+## Development
+
+Execute `pnpm run dev` in the project to start the project:
+
+```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
+```
+
+Open `http://localhost:8000/` in your browser and you will see the following:
+
+![dev](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/dev.png)
+
+## Configuration
+
+The `modern.config.ts` files exist in Modern.js projects created by the generator.
+
+Features can be enabled through the configuration file, or the default behavior of the coverage Modern.js. For example, add the following configuration to enable 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,
+  },
+});
+```
+
+Re-execute `pnpm run dev`, in the browser Network menu, you can find that the project has completed page rendering at the server level.
+
+## Build
+
+Execute `pnpm run build` in the project to build the project production environment product:
+
+```bash
+$ pnpm run build
+
+> modern build
+
+info    Create a production build...
+
+info    File sizes after production build:
+
+  File                                      Size         Gzipped
+  dist/static/js/lib-corejs.ffeb7fb8.js     214.96 kB    67.23 kB
+  dist/static/js/lib-react.09721b5c.js      152.61 kB    49.02 kB
+  dist/static/js/218.102e2f39.js            85.45 kB     28.5 kB
+  dist/static/js/lib-babel.a7bba875.js      11.93 kB     3.95 kB
+  dist/html/main/index.html                 5.84 kB      2.57 kB
+  dist/static/js/main.3568a38e.js           3.57 kB      1.44 kB
+  dist/static/css/async/304.c3c481a5.css    2.62 kB      874 B
+  dist/asset-manifest.json                  1.48 kB      349 B
+  dist/static/js/async/304.c45706bc.js      1.4 kB       575 B
+  dist/static/js/async/509.fcb06e14.js      283 B        230 B
+
+ Client ✔ done in 3.57s
+ ```
+
+The bundle is generated to `dist/` by default, and the directory structure is as follows:
+
+```
+.
+├── asset-manifest.json
+├── html
+│   └── main
+├── loader-routes
+│   └── main
+├── modern.config.json
+├── route.json
+└── static
+    ├── css
+    └── js
+```
+
+## Verify
+
+Execute `pnpm run serve` in the project to verify locally that the bundle is running correctly:
+
+```bash
+$ pnpm run serve
+
+> modern serve
+
+Starting the modern server...
+info    App running at:
+
+  > Local:    http://localhost:8080/
+  > Network:  http://10.94.58.87:8080/
+  > Network:  http://10.254.68.105:8080/
+```
+
+Open http://localhost:8000/ in the browser and the content should be the same as when `pnpm run dev`.
+
+## Deploy
+
+After the local verification is completed, the products under `dist/` can be organized into the structure required by the server for deployment.

package/en/docusaurus-plugin-content-docs/current/guides/get-started/upgrade.md

@@ -0,0 +1,78 @@
+---
+title: Upgrade
+sidebar_position: 2
+---
+
+## Upgrade with command
+
+Modern.js provides the `upgrade` command to support projects to upgrade to the latest  version.
+
+Execute `pnpm run upgrade` in the project:
+
+```bash
+$ pnpm run upgrade
+
+> modern upgrade
+
+[INFO] [Project Type]: Application
+[INFO] [Modern.js Latest Version]: 2.0.0
+[INFO] Upgrade Modern.js package version success!
+```
+
+You can see that the dependency in the project `package.json` has been changed to the latest.
+
+## Specify version upgrade
+
+Modern.js all packages are published using the **unified version number**.
+
+According to the website Release Note, developers can also manually upgrade the project to the desired version.
+
+:::tip
+When upgrading, you need to upgrade to all packages provided by the Modern.js, rather than upgrading a single dependency.
+:::
+
+## lock child dependency
+
+When there is a problem with one of the child dependencies of the project, and the Modern.js cannot be updated immediately, you can use the package manager to lock the child dependency version.
+
+### pnpm
+
+For projects using pnpm, add the following configuration to the `package.json` in the **project root directory** and re-execute `pnpm install`:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "package-name": "^1.0.0"
+    }
+  }
+}
+```
+
+### Yarn
+
+For projects using Yarn, add the following configuration to the `package.json` in the **project root directory** and re-execute `yarn install`:
+
+```json
+{
+  "resolutions": {
+    "package-name": "^1.0.0"
+  }
+}
+```
+
+### Npm
+
+For projects using Npm, add the following configuration to the `package.json` in the **project root directory** and re-execute `npm install`:
+
+```json
+{
+  "overrides": {
+    "package-name": "^1.0.0"
+  }
+}
+```
+
+:::info
+For Monorepo repositories, the dependency version can only be locked in the `package.json` in the project root directory, and all packages in Monorepo are affected.
+:::

package/{zh/tutorials/first-app → en/docusaurus-plugin-content-docs/current/guides}/overview.md

@@ -2,10 +2,10 @@
 sidebar_position: 0
 ---
 
-# 概览
+# Overview
 
 import OverviewNav from '@site/src/components/OverviewNav';
-import sidebarData from '@site/plugins/overview-loader!@site/plugins/overview-data.json'
-import Link from '@docusaurus/Link';
 
-<OverviewNav cards={sidebarData.docsSidebars.tutorialsSidebar[1].items}/>
+import sidebarData from '@site/plugins/overview-loader!@site/plugins/overview-data.json';
+
+<OverviewNav cards={sidebarData.docsSidebars.guidesSidebar} />

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/framework-plugin/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Custom Plugin",
+  "position": 6
+}

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/framework-plugin/lifecycle.md

@@ -0,0 +1,15 @@
+---
+title: Lifecycle
+sidebar_position: 1
+---
+
+Modern.js application has a complete lifecycle, including CLI, Server Side and Runtime three stages.
+
+Modern.js lifecycle is as follows:
+
+
+:::note
+The rectangle of the pink box represents the plugin hook provided by the Modern.js, and the light yellow base color ellipse represents the linkage point with the next stage.
+:::
+
+![lifecycle](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/life-cycle.svg)

package/en/docusaurus-plugin-content-docs/current/tutorials/foundations/introduction.md

@@ -40,4 +40,4 @@ It mainly contains the following features:
 
 If you are a front-end beginner, you may find these concepts a bit complicated. We provide some [JavaScript and React](/docs/tutorials/foundations/basic) learning materials, you can do some understanding of them first。
 
-If you are an experienced developer and want to know how to use Modern.js, you can try [Create your first app](/docs/tutorials/first-app/overview), or read [Guide](/docs/guides/overview).
+If you are an experienced developer and want to know how to use Modern.js, you can try [Create your first app](/docs/tutorials/first-app/c01-start), or read [Guide](/docs/guides/overview).

package/en/docusaurus-plugin-content-docs/current.json

@@ -4,7 +4,7 @@
     "description": "The label for version current"
   },
   "sidebar.tutorialsSidebar.category.基础": {
-    "message": "基础",
+    "message": "Basic",
     "description": "The label for category 基础 in sidebar tutorialsSidebar"
   },
   "sidebar.tutorialsSidebar.category.创建第一个应用": {
@@ -56,23 +56,23 @@
     "description": "The label for category 11: 添加容器组件 in sidebar tutorialsSidebar"
   },
   "sidebar.guidesSidebar.category.开始": {
-    "message": "开始",
+    "message": "Start",
     "description": "The label for category 开始 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.核心概念": {
-    "message": "核心概念",
+    "message": "Core Concept",
     "description": "The label for category 核心概念 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.基础功能": {
-    "message": "基础功能",
+    "message": "Basic Features",
     "description": "The label for category 基础功能 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.CSS 开发方案": {
-    "message": "CSS 开发方案",
+    "message": "CSS Development",
     "description": "The label for category CSS 开发方案 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.进阶功能": {
-    "message": "进阶功能",
+    "message": "Advanced Features",
     "description": "The label for category 进阶功能 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.BFF": {
@@ -80,15 +80,15 @@
     "description": "The label for category BFF in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.专题详解": {
-    "message": "专题详解",
+    "message": "Topic Detail",
     "description": "The label for category 专题详解 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.Reduck 状态管理": {
-    "message": "Reduck 状态管理",
+    "message": "Reduck State Manager",
     "description": "The label for category Reduck 状态管理 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.微前端": {
-    "message": "微前端",
+    "message": "Micro-frontend",
     "description": "The label for category 微前端 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.Monorepo": {
@@ -96,11 +96,11 @@
     "description": "The label for category Monorepo in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.包版本管理": {
-    "message": "包版本管理",
+    "message": "Package Version Manager",
     "description": "The label for category 包版本管理 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.自定义插件": {
-    "message": "自定义插件",
+    "message": "Customized plugins",
     "description": "The label for category 自定义插件 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.项目生成器": {

package/package.json

@@ -11,20 +11,20 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.0.0-beta.3",
+  "version": "2.0.0-beta.5",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "2.0.0-beta.3"
+    "@modern-js/builder-doc": "2.0.0-beta.4"
   },
   "devDependencies": {
+    "@modern-js/builder-doc": "2.0.0-beta.4",
     "ts-node": "^10",
     "fs-extra": "^10",
     "@types/node": "^16",
-    "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "2.0.0-beta.3"
+    "@types/fs-extra": "^9"
   },
   "scripts": {
     "build": "npx ts-node ./scripts/sync.ts"

package/zh/apis/app/commands/dev.md

@@ -2,10 +2,10 @@
 sidebar_position: 1
 ---
 
-# dev
+# dev / start
 
 ```bash
-Usage: modern dev [options]
+Usage: modern dev / modern start [options]
 
 本地开发命令
 
@@ -17,10 +17,15 @@ Options:
   --api-only            仅启动 API 接口服务
 ```
 
-`modern dev` 命令启动一个开发服务器，同时监听源文件变化，默认支持 React Fast Refresh：
+`modern dev` 命令用于启动一个本地开发服务器，对源代码进行开发环境编译，同时监听源文件变化，默认支持模块热更新和 React Fast Refresh。
+
+`modern start` 是 `modern dev` 命令的别名，两者的功能和用法完全一致。
 
 ```bash
-App running at:
+$ modern dev
+
+info    Starting dev server...
+info    App running at:
 
   > Local:    http://localhost:8080/
   > Network:  http://192.168.0.1:8080/

package/zh/apis/app/commands/inspect.md

@@ -5,35 +5,56 @@ sidebar_position: 7
 ```
 Usage: modern inspect [options]
 
-inspect internal webpack config
-
 Options:
   --env <env>           查看指定环境下的配置 (default: "development")
   --output <output>     指定在 dist 目录下输出的路径 (default: "/")
-  --no-console          不在终端中输出完整结果
   --verbose             在结果中展示函数的完整内容
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
   -h, --help            显示命令帮助
 ```
 
-`modern inspect` 命令，用于查看项目的 webpack 完整配置。
+`modern inspect` 命令，用于查看项目的 [Modern.js Builder 配置](https://modernjs.dev/builder/zh/guide/basic/builder-config.html) 以及 webpack 配置。
+
+在项目根目录下执行命令 `npx modern inspect` 后，会在项目的 `dist` 目录生成以下文件：
 
-在项目根目录下执行命令 `npx modern inspect`，会将 webpack 配置输出在终端界面，同时也会在项目的 `dist` 目录生成一份 `webpack.client.inspect.js` 文件，开发者可手动打开查看。
+- `builder.config.js`: 表示在构建时使用的 Modern.js Builder 配置。
+- `webpack.config.web.js`: 表示在构建时使用的 webpack 配置。
+
+```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 配置，可以使用 `env` 选项来输出生产环境的配置：
+默认情况下，inspect 命令会输出开发环境的配置，你可以添加 `--env production` 选项来输出生产环境的配置：
 
 ```bash
 modern inspect --env production
 ```
 
-## 配置类型
+## 完整内容
 
-### SSR 配置
+默认情况下，inspect 命令会省略配置对象中的函数内容，你可以添加 `--verbose` 选项来输出函数的完整内容：
 
-如果项目开启了 SSR 能力，则在 `dist` 目录会另外生成一份 `webpack.ssr.inspect.js` 文件，对应 SSR 构建时的 webpack 配置。
+```bash
+modern inspect --verbose
+```
 
-### Modern 配置
+## SSR 构建配置
 
-如果项目开启了 [enableModernMode](/docs/configure/app/output/enable-modern-mode) 选项，则在 `dist` 目录会另外生成一份 `webpack.modern.inspect.js` 文件，对应现代浏览器的 webpack 配置。
+如果项目开启了 SSR 能力，则在 `dist` 目录会另外生成一份 `webpack.config.node.js` 文件，对应 SSR 构建时的 webpack 配置。
+
+```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/zh/apis/app/commands/new.md

@@ -34,7 +34,7 @@ $ npx modern new
 ? 请填写入口名称 entry
 ```
 
-### 启用启用可选功能
+### 启用可选功能
 
 在应用工程中，执行 `new` 命令启用可选能力如下：
 

package/zh/apis/app/commands/{start.md → serve.md}

@@ -3,9 +3,9 @@ sidebar_position: 6
 ---
 
 ```bash
-Usage: modern start [options]
+Usage: modern serve [options]
 
-start server
+run server
 
 Options:
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
@@ -13,7 +13,7 @@ Options:
   --api-only            仅启动 API 接口服务
 ```
 
-通常使用 `modern start` 命令在生产环境下启用应用工程, 需要提前执行 [`build`](/docs/apis/app/commands/build) 命令构建出对应产物。
+通常使用 `modern serve` 命令在生产环境下启用应用工程, 需要提前执行 [`build`](/docs/apis/app/commands/build) 命令构建出对应产物。
 
 默认情况下，应用将会在 `localhost:8080` 启动，可以通过 `server.port` 修改 Server 端口号：
 

package/zh/apis/app/hooks/src/index_.md

@@ -12,11 +12,12 @@ sidebar_position: 3
 只需要 `src/index.[tj]s` 默认导出函数:
 
 ```js title=src/index.js
+import ReactDOM from 'react-dom/client';
 import { bootstrap } from '@modern-js/runtime';
 
-export default App => {
+export default (App: React.ComponentType) => {
   // do something before bootstrap...
-  bootstrap(App, 'root');
+  bootstrap(App, 'root', undefined, ReactDOM);
 };
 ```
 
@@ -28,8 +29,8 @@ export default App => {
 
 ```js title=src/index.jsx
 import React from 'react';
-import ReactDOM from 'react-dom';
+import ReactDOM from 'react-dom/client';
 import App from './App';
 
-ReactDOM.render(<App />, document.getElementById('root'));
+ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
 ```