@modern-js/main-doc 2.3.0 → 2.5.0

package/en/guides/basic-features/proxy.mdx

@@ -6,7 +6,7 @@ sidebar_position: 5
 
 ## Local Proxy
 
-Modern.js provides a way to configure the development proxy in ['tools.devServer'] (/docs/configure/app/tools/dev-server). For example, to proxy the local interface to an online address:
+Modern.js provides a way to configure the development proxy in [tools.devServer](/configure/app/tools/dev-server). For example, to proxy the local interface to an online address:
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
@@ -28,7 +28,7 @@ export default defineConfig({
 when access `http://localhost:8080/go/api`, the response content is returned from [http://www.example.com/](http://www.example.com/).
 
 :::info
-For more detail, see [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)。
+For more detail, see [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware).
 
 :::
 

package/en/guides/basic-features/routes.mdx

@@ -132,7 +132,35 @@ With a file directory named `[]`, the generated route will be used as a dynamic
 
 The `routes/[id]/page.tsx` file is converted to the `/:id` route. Except for the `/blog` route that exactly matches, all other `/xxx` will match this route.
 
-In component, you can get the corresponding named parameters through [useParams](/apis/app/runtime/router/#useparams).
+In component, you can get the corresponding named parameters through [useParams](/apis/app/runtime/router/router#useparams).
+
+### Catch all routing
+
+If a `$.tsx` file is created in the routes directory, this file will act as a wildcard route component that will be rendered when there is no matching route.
+
+:::note
+`$.tsx` can be thought of as a special `page` routing component that renders `$.tsx` as a child of `layout` when there is a `layout` component in the current directory.
+:::
+
+For example, the following directory structure:
+
+```
+└── routes
+    ├── $.tsx
+    ├── blog
+    │   └── page.tsx
+    └── page.tsx
+```
+
+The `routes/$.tsx` component is rendered when accessing any path that does not match, and again, the remainder of the url can be captured in `$.tsx` using [useParams](/apis/app/runtime/router/router#useparams).
+
+```ts title="$.tsx"
+import { useParams } from '@modern-js/runtime/router';
+// When the path is `/aaa/bbb`
+const params = useParams();
+params['*']  // => 'aaa/bbb'
+```
+
 
 ### Layout with No Path
 
@@ -207,7 +235,7 @@ When the component exists in a routing directory, the component render error is
 
 {/* Todo API 路由 */}
 
-Within the `<ErrorBoundary>` component, you can use [useRouteError](/apis/app/runtime/router/#useparams) to get the specific information of the error:
+Within the `<ErrorBoundary>` component, you can use [useRouteError](/apis/app/runtime/router/router#useparams) to get the specific information of the error:
 
 ```tsx
 import { useRouteError } from '@modern-js/runtime/router';
@@ -267,19 +295,17 @@ export default () => {
 When working with SSR, the browser side can get the data returned by `init` during SSR, and the developer can decide whether to retrieve the data on the browser side to overwrite the SSR data, for example:
 
 ```tsx title="src/routes/layout.tsx"
-import {
-  RuntimeContext,
-} from '@modern-js/runtime';
+import { RuntimeContext } from '@modern-js/runtime';
 
 export const init = (context: RuntimeContext) => {
-  if (process.env.JUPITER_TARGET === 'node') {
+  if (process.env.MODERN_TARGET === 'node') {
     return {
       message: 'Hello World By Server',
     }
   } else {
     const { context } = runtimeContext;
     const data = context.getInitData();
-    // 如果没有获取到期望的数据
+    // If do not get the expected data
     if (!data.message) {
       return {
         message: 'Hello World By Client'

package/en/guides/concept/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Core Concept",
+  "position": 2,
+  "collapsed": false
+}

package/en/guides/{basic-features → concept}/builder.mdx

@@ -1,12 +1,12 @@
 ---
-title: Builder
 sidebar_position: 2
 ---
+
 # Builder
 
 **Modern.js uses [Modern.js Builder](https://modernjs.dev/builder) to build your Web App.**
 
-Modern.js Builder is one of the core components of Modern.js. It is a build engine for Web development and can be used independently of Modern.js. Modern.js Builder supports multiple bundlers such as webpack and rspack, and it uses webpack by default.
+Modern.js Builder is one of the core components of Modern.js. It is A Build Engine for web development. and can be used independently of Modern.js. Modern.js Builder supports multiple bundlers such as webpack and rspack, and it uses webpack by default.
 
 ## Build Architecture
 

package/en/guides/concept/entries.mdx

@@ -1,7 +1,7 @@
 ---
-title: Entries
-sidebar_position: 2
+sidebar_position: 1
 ---
+
 # Entries
 
 Entries are Modern.js default file convention, and each entry in the project is a separate page, corresponding to a server level route.
@@ -15,11 +15,11 @@ Modern.js initialization project is a single entry, the project structure is as
 ```
 .
 ├── src
-│   ├── modern-app-env.d.ts
-│   └── routes
-│       ├── index.css
-│       ├── layout.tsx
-│       └── page.tsx
+│   ├── modern-app-env.d.ts
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
 ├── package.json
 ├── modern.config.ts
 ├── pnpm-lock.yaml
@@ -41,10 +41,10 @@ After execution, the `src/` directory will become the following structure:
 .
 ├── modern-app-env.d.ts
 ├── myapp
-│   └── routes
-│       ├── index.css
-│       ├── layout.tsx
-│       └── page.tsx
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
 └── new-entry
     └── routes
         ├── index.css

package/en/guides/css/_category_.json

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

package/en/guides/{basic-features/css → css}/less-sass.mdx

@@ -12,6 +12,6 @@ sidebar_position: 4
 - If you need to customize the configuration of [sass-loader](https://github.com/webpack-contrib/sass-loader), please refer to the [tools.less](/configure/app/tools/sass).
 
 :::tip
-CSS files pre-compiled by Less and Sass will still undergo Modern.js build-in [PostCSS](https://postcss.org/) conversion, which has good browser compatibility. For related content, please refer to [[PostCSS](/guides/basic-features/css/postcss)].
+CSS files pre-compiled by Less and Sass will still undergo Modern.js build-in [PostCSS](https://postcss.org/) conversion, which has good browser compatibility. For related content, please refer to [[PostCSS](/guides/css/postcss)].
 
 :::

package/en/guides/get-started/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Start",
+  "position": 1,
+  "collapsed": false
+}

package/en/guides/get-started/introduction.mdx

@@ -0,0 +1,34 @@
+---
+title: Introduction
+sidebar_position: 1
+---
+# Introduction
+
+## Modern.js Introduction
+
+**Modern.js** is a progressive modern web development framework based on React.
+
+The framework has a variety of built-in out-of-the-box tools, excellent build performance, zero-configuration rendering paradigm switching, and integrated API calls. Starting from three solutions (Application solutions, Module solutions, Monorepo solutions), it supports front-end research and development of a complete period.
+
+Modern.js is ByteDance's underlying front-end framework, which has directly or indirectly served thousands of applications, including middle and back-end, PC Web, H5 and other application scenarios. The framework covers a full life cycle, has a complete plugin system, and provides a high degree of customization capabilities. Support custom solutions exclusive to business lines through generator plugin, customize various functional extensions and business requirements, and help developers build applications faster.
+
+## Why Modern.js
+
+Modern.js can provide developers with the ultimate **Development Experience**，make the app better **User Experience**.
+
+In the process of developing React applications, developers often need to design implementations for certain functions, or use other libraries and frameworks to solve these problems.
+
+Modern.js support all the configuration and tools required by React applications, and have built-in **additional functions and optimizations**. Developers can use React to build the UI of the application, and then gradually adopt Modern.js functions to solve common application requirements, such as routing, data fetch, state management, etc.
+
+It mainly contains the following features:
+
+- 🪜 **Progressive**：Create projects with the most streamlined templates, gradually turn on plugin capabilities through generators, and customize solutions.
+- 🏠 **Integration**：The development is unique to the production environment Web Server, CSR and SSR are isomorphic development, and the function as the API service call.
+- 📦 **Out Of The Box**：Default TS support, built-in build core, ESLint, debugging tools, full functionality can be tested.
+- 🌏 **Ecology**：Self-developed state management, micro frontend, module packaging, Monorepo solution and other peripheral requirements.
+- 🕸 **Routing Modes**：Contains controlled routing, routing based on file conventions (nested routing), configurable routing, etc.
+- 🚀 **Independently Build Core**：Support a variety of packaging tools, deep optimization bundle.
+
+## Next
+
+If you want to know how to use Modern.js, you can try [Create your first app](/tutorials/first-app/c01-start), or read [Quick Start](/guides/get-started/quick-start).

package/en/guides/get-started/quick-start.mdx

@@ -1,7 +1,8 @@
 ---
 title: Quick Start
-sidebar_position: 1
+sidebar_position: 2
 ---
+
 # Quick Start
 
 ## Environment
@@ -81,7 +82,6 @@ Features can be enabled through the configuration file, or the default behavior
 ```ts
 import { defineConfig } from '@modern-js/app-tools';
 
-// https://modernjs.dev/docs/apis/app/config
 export default defineConfig({
   runtime: {
     router: true,

package/en/guides/get-started/upgrade.mdx

@@ -1,7 +1,8 @@
 ---
 title: Upgrade
-sidebar_position: 2
+sidebar_position: 3
 ---
+
 # Upgrade
 
 ## Upgrade with command

package/en/guides/topic-detail/_category_.json

@@ -1,5 +1,5 @@
 {
   "label": "Topic Detail",
-  "position": 5,
-  "collapsed": true
+  "position": 6,
+  "collapsed": false
 }

package/en/guides/topic-detail/framework-plugin/hook.mdx

@@ -76,7 +76,7 @@ pipeline.run(5); // 6
 
 上面的例子就是以 Pipeline 为例描述的，这里就不赘述了，在 Pipeline 这个大类中，提供了两个小类：Sync 和 Async，顾名思义，它们的区别就是管理的函数的类型是 Sync 的还是 Async 的。
 
-:::info 注
+:::info
 当 Pipeline 中没有函数或者所有函数都调用了 `next` 函数，则就需要在运行的时候提供：
 
 ```ts

package/en/guides/topic-detail/generator/config/{mwa.mdx → app.mdx}

@@ -2,7 +2,7 @@
 sidebar_position: 2
 ---
 
-# MWA
+# Web App
 
 ## Project creation
 

package/en/guides/topic-detail/generator/plugin/api/hook/onForged.mdx

@@ -28,7 +28,7 @@ The onForged parameter is a callback function, and the function parameters are `
 
 ### api
 
-A list of supported functions in `onForged` time to live, specifically viewable [File API] (/docs/guides/topic-detail/generator/plugin/api/file/introduce) and [Enable function API] (/docs/guides/topic-detail/generator/plugin/api/new/introduce).
+A list of supported functions in `onForged` time to live, specifically viewable [File API](/guides/topic-detail/generator/plugin/api/file/introduce) and [Enable function API](/guides/topic-detail/generator/plugin/api/new/introduce).
 
 ### inputData
 

package/en/guides/topic-detail/generator/plugin/api/new/createElement.mdx

@@ -30,4 +30,4 @@ Project element type, supports entry and server.
 
 ## params
 
-For other parameters of creating elements, please refer to[MWA New Command](/guides/topic-detail/generator/config/mwa).
+For other parameters of creating elements, please refer to[App New Command](/guides/topic-detail/generator/config/app).

package/en/guides/topic-detail/generator/plugin/api/new/enableFunc.mdx

@@ -41,4 +41,4 @@ The function name is passed according to the functions supported by the differen
 
 ## params
 
-For other parameters when the function is enabled, please refer to[MWA New Command](/guides/topic-detail/generator/config/mwa)和[Module New Command](/guides/topic-detail/generator/config/module).
+For other parameters when the function is enabled, please refer to [App New Command](/guides/topic-detail/generator/config/app) and [Module New Command](/guides/topic-detail/generator/config/module).

package/en/guides/topic-detail/generator/plugin/api/new/introduce.mdx

@@ -8,7 +8,7 @@ The three engineering solutions provided by the Modern.js support executing the
 
 Different engineering solutions to support new operations:
 
-- [MWA](/guides/topic-detail/generator/config/mwa)
+- [Web App](/guides/topic-detail/generator/config/app)
 
 - [Module](/guides/topic-detail/generator/config/module)
 

package/en/guides/topic-detail/generator/plugin/develop.mdx

@@ -23,7 +23,7 @@ Different plugin types will ask different questions. You can choose the plugin t
 ? Development Language TS
 ? Package Management Tool pnpm
 ? Plugin Type extend
-? Plugin Base Type MWA Solution
+? Plugin Base Type Web App Solution
 ```
 
 ### Customized type
@@ -35,7 +35,7 @@ Different plugin types will ask different questions. You can choose the plugin t
 ? Plugin Type custom
 ? Plugin Key mobile-app
 ? Plugin Show Name Mobile App
-? Plugin Base Type MWA Solution
+? Plugin Base Type Web App Solution
 ```
 
 After the execution of the create project command is completed, a project for developing the generator plugin will be generated accordingly, and the `meta` information will also be generated according to your selection in the `package.json`.
@@ -122,4 +122,4 @@ The `api` will provide some npm, Git and other methods, which can install depend
 
 `input` is the current user input, which can be used to obtain the current input information and configuration information of the user.
 
-The API functions supported in `afterForged` can also be found in [Generator Plugin API] (/docs/guides/topic-detail/generator/plugin/api/hook/afterForged).
+The API functions supported in `afterForged` can also be found in [Generator Plugin API](/guides/topic-detail/generator/plugin/api/hook/afterForged).

package/en/guides/topic-detail/micro-frontend/c02-development.mdx

@@ -10,19 +10,20 @@ title: 体验微前端
 - 微前端项目开发的基本流程。
 
 ## 创建应用
+目前支持两种路由模式
+- 自控式路由
+- 约定式路由
 
-在这次的实践中，我们需要创建三个应用，分别为 1 个主应用，2 个子应用：
+首先明确主应用的路由模式 [创建约定式路由主应用](#创建约定式路由主应用) 或 [创建自控式路由主应用](#创建自控式路由主应用)
 
-- main 主应用
-- dashboard 子应用
-- table 子应用
+在本次体验中我们会为主应用创建两个子应用 Table 和 Dashboard (Table 为约定式路由，Dashboard 为自控式路由)
 
-### 创建 main 主应用
+### 创建约定式路由主应用
 
 通过命令行工具初始化项目：
 
 ```bash
-mkdir main && cd main
+mkdir masterApp && cd masterApp
 npx @modern-js/create
 ```
 
@@ -43,16 +44,96 @@ import EnableMicroFrontend from "@site-docs/components/enable-micro-frontend";
 
 <EnableMicroFrontend />
 
-import MicroRuntimeConfig from "@site-docs/components/micro-runtime-config";
+然后我们在 routes 文件夹下新建两个目录
+- table (用于加载约定式路由子应用)
+- dashboard (用于加载自控式路由子应用)
 
-<MicroRuntimeConfig />
+在这两个目录下我们需要新建一个 `$.tsx` 文件作为主应用约定式路由的入口($ 代表模糊匹配，即 `/table` 和 `/table/test` 都会匹配到这个 `$.tsx` 作为该路由的入口文件，这会保证在微前端场景下正确加载子应用路由)
 
-### 创建 dashboard 子应用
+#### 加载约定式路由子应用
+```js title="src/routes/table/$.tsx"
+import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
+
+const Index = () => {
+  const { Table } = useModuleApps();
+
+  return (
+    <div>
+      <Table />
+    </div>
+  )
+}
+
+export default Index;
+```
+
+#### 加载自控式路由子应用
+```js title="src/routes/dashboard/$.tsx"
+import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
+
+const Index = () => {
+  const { Dashboard } = useModuleApps();
+
+  return (
+    <div>
+      <Dashboard />
+    </div>
+  )
+}
+
+export default Index;
+```
+#### 路由跳转
+此时主应用配置已经完成，通过路由即可加载子应用，修改主应用的 `layout.tsx` 来跳转路由
+```js title="src/route/layout.tsx"
+import { Outlet, Link } from '@modern-js/runtime/router';
+
+const Layout = () => (
+  <div>
+    <div><Link to={'/table'}>加载约定式路由子应用</Link></div>
+    <div><Link to={'/dashboard'}>加载自控式路由子应用</Link></div>
+    <div><Link to={'/'}>卸载子应用</Link></div>
+    <Outlet />
+  </div>
+);
+
+export default Layout;
+```
+
+### 创建自控式路由主应用
 
 通过命令行工具初始化项目：
 
 ```bash
-mkdir dashboard && cd dashboard
+mkdir masterApp && cd masterApp
+npx @modern-js/create
+```
+
+<DefaultMWAGenerate />
+
+完成项目创建后我们可以通过 `pnpm run new` 来开启 `微前端` 功能：
+
+```bash
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用「微前端」模式
+```
+
+接下来，让我们注册微前端插件并添加开启微前端主应用，并增加子应用列表：
+
+<EnableMicroFrontend />
+
+由于是自控式路由，我们删除掉 `routes` 文件夹并在 `src` 目录下增加 `App.tsx` 文件，此处如果使用的 `非 MApp` 组件，需要通过 `React Router v6` 的 `createBrowserRouter` API 来创建路由
+#### 加载子应用
+import CustomRouterMicroFrontend from "@site-docs/components/custom-router-micro-frontend";
+
+<CustomRouterMicroFrontend />
+
+### 创建约定式路由子应用
+
+通过命令行工具初始化项目：
+
+```bash
+mkdir table && cd table
 npx @modern-js/create
 ```
 
@@ -74,6 +155,9 @@ import appTools, { defineConfig } from '@modern-js/app-tools';
 import garfishPlugin from '@modern-js/plugin-garfish';
 
 export default defineConfig({
+  dev: {
+    port: 8081
+  },
   runtime: {
     router: true,
     state: true,
@@ -85,12 +169,23 @@ export default defineConfig({
 });
 ```
 
-### 创建 table 子应用
+添加 `src/routes/page.tsx` 代码
+```js title="src/routes/page.tsx"
+const Index = () => {
+  return (
+    <div className="container-box">subApp: 约定式路由的子应用的根路由</div>
+  )
+}
+
+export default Index;
+```
+
+### 创建自控式路由子应用
 
 通过命令行工具初始化项目：
 
 ```bash
-mkdir table && cd table
+mkdir dashboard && cd dashboard
 npx @modern-js/create
 ```
 
@@ -112,6 +207,9 @@ import appTools, { defineConfig } from '@modern-js/app-tools';
 import garfishPlugin from '@modern-js/plugin-garfish';
 
 export default defineConfig({
+  dev: {
+    port: 8082
+  },
   runtime: {
     router: true,
     state: true,
@@ -122,67 +220,36 @@ export default defineConfig({
   plugins: [appTools(), garfishPlugin()],
 });
 ```
+自控式路由需要删除掉 `routes` 文件夹并在 `src` 目录下新建 `App.tsx`
 
-## 添加代码
+并在 `src/App.tsx` 添加代码，注意需要从 `props` 中解析并传递 `basename` 给 `BrowserRouter`
 
-### main 主应用
+```js title="src/App.tsx"
+import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
 
-删除 `src/routers` 目录, 创建 `src/App.tsx`，并添加如下内容：
+export default (props: {basename: string}) => {
+  const { basename } = props;
 
-```tsx
-import { Link } from '@modern-js/runtime/router';
-import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
-
-const App = () => {
-  const { DashBoard, TableList } = useModuleApps();
   return (
-    <div>
-      <div>
-        <Link to="/dashboard">Dashboard</Link> &nbsp;
-        <Link to="/table">Table</Link>
-      </div>
-      <Route path="/dashboard">
-        <DashBoard />
-      </Route>
-      <Route path="/table">
-        <TableList />
-      </Route>
-    </div>
+    <BrowserRouter basename={basename}>
+      <Routes>
+        <Route index element={<div>自控式路由子应用根路由</div>} />
+        <Route path={'path'} element={<div>自控式路由子应用子路由</div>} />
+      </Routes>
+    </BrowserRouter>
   );
 };
-
-export default App;
-```
-
-### dashboard 子应用
-
-删除 `src/routers` 目录, 创建 `src/App.tsx`，并添加如下内容：
-
-```tsx
-export default () => <div>Dashboard Page</div>;
-```
-
-### table 子应用
-
-删除 `src/routers` 目录, 创建 `src/App.tsx`，并添加如下内容：
-
-```tsx
-export default () => <div>Table Page</div>;
 ```
 
 ## 调试
+按顺序在目录执行 `pnpm run dev` 命令启动应用：
+- masterApp 主应用 `http://localhost:8080`
+- table 子应用(约定式路由) `http://localhost:8081`
+- dashboard 子应用(自控式路由) `http://localhost:8082`
 
-按顺序在 `main`、 `dashboard`、 `table` 目录执行 `pnpm run dev` 命令启动应用：
-
-- main      - `http://localhost:8080`
-- dashboard - `http://localhost:8081`
-- table     - `http://localhost:8082`
-
-访问主应用地址 `http://localhost:8080`，效果如下：
-
-![demo](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/micro-demo.gif)
+访问主应用地址 `http://localhost:8080`
 
-在完成了微前端整体开发流程的体验后，你可以进一步了解如何 [开发主应用](./c03-main-app.md)
+在完成了微前端整体开发流程的体验后，你可以进一步了解如何 [开发主应用](/guides/topic-detail/micro-frontend/c03-main-app)
 
 ## 常见问题