@modern-js/main-doc 0.0.0-next-1685369216913 → 0.0.0-next-1685418932858

package/docs/zh/apis/app/hooks/config/public.mdx

@@ -4,13 +4,13 @@ sidebar_position: 3
 ---
 # public/
 
-`public/` 目录中可以放置任意格式的静态资源文件，文件会被 Serve 在 Web 应用域名下。
+`public/` 目录中可以放置任意格式的静态资源文件，文件会被服务端部署到对应的应用域名下。
 
 ## 说明
 
-被 Serve 的文件路由基于目录结构的约定，其中，`public/` 为根目录，对应 Web 应用根路径。
+文件路由基于目录结构的约定，其中，`public/` 为根目录，对应 Web 应用根路径。
 
-例如 `config/public/sdk/index.js` 文件，在部署后将会被 Serve 在 `${domain}/sdk/index.js` 下。
+例如 `config/public/sdk/index.js` 文件，在部署后将会被部署在 `${domain}/sdk/index.js` 下。
 
 ## 场景
 

package/docs/zh/apis/app/hooks/config/upload.mdx

@@ -14,7 +14,7 @@ sidebar_position: 4
 
 ## 场景
 
-例如 `google-analysis.js` 等项目自用的 SDK（通常需要 http 缓存）。
+例如 `google-analysis.js` 等项目自用的 SDK（通常需要 HTTP 缓存）。
 
 图片、字体文件、通用 CSS 等。
 

package/docs/zh/apis/app/hooks/modern-config.mdx

@@ -1,9 +1,9 @@
 ---
-title: modern.config.js
+title: modern.config.[tj]s
 sidebar_position: 8
 ---
-# modern.config.js
+# modern.config.[tj]s
 
 Modern.js 配置文件, 通过该文件可以对当前项目的各个方面进行个性化配置。
 
-了解配置的具体用法，请参考 [配置使用](/configure/app/usage)。
+了解配置的具体用法，请参考[配置使用](/configure/app/usage)。

package/docs/zh/apis/app/hooks/server/index_.mdx

@@ -4,11 +4,6 @@ sidebar_position: 1
 ---
 # index.[tj]s
 
-扩展 Modern.js Web Server 的文件，在此文件中可以给应用工程启动的 Web Server 添加 Hook 或 Middleware。
+扩展 Modern.js Web Server 的文件，在此文件中可以给应用工程启动的 Web Server 添加 [Hook](/apis/app/runtime/web-server/hook) 或 [Middleware](/apis/app/runtime/web-server/middleware)。
 
 可以对请求和响应进行拦截处理，鉴权与角色、请求预处理、异常兜底等。也可在内置处理逻辑（包括路由匹配、资源寻址、头部注入、页面渲染，静态 Web 托管）插入特定的业务逻辑。
-
-:::info
-具体使用示例可查看 [Hook](/apis/app/runtime/web-server/hook) & [Middleware](/apis/app/runtime/web-server/middleware)。
-
-:::

package/docs/zh/apis/app/hooks/shared.mdx

@@ -4,4 +4,4 @@ sidebar_position: 5
 ---
 # shared/
 
-共享源码目录。当项目在 `api/`、`server/`、`src/` 下有公共代码时，可将这些代码放到 shared 目录下，而不是直接引用。
+共享源码目录。当项目在 `api/`、`server/`、`src/` 下有公共代码时，可将这些代码放到 `shared` 目录下，而不是直接引用。

package/docs/zh/apis/app/hooks/src/app.mdx

@@ -4,46 +4,36 @@ sidebar_position: 1
 ---
 # App.[tj]sx
 
-应用使用自控路由时的入口标识符。
+应用使用[自控路由](/guides/basic-features/routes.html#self-controlled-routing)时的入口标识符。
 
 `App.[tj]sx` 并不是实际的应用入口，Modern.js 会自动生成真正的构建打包的入口文件, 内容大致如下：
 
 ```js
 import React from 'react';
+import ReactDOM from 'react-dom/client';
 import { createApp, bootstrap } from '@modern-js/runtime';
 // App.[jt]sx
 import App from '@_modern_js_src/App';
-import { state } from '@modern-js/runtime/plugins';
-import {
-  immer,
-  effects,
-  autoActions,
-  devtools,
-} from '@modern-js/runtime/model';
-
-const createStatePlugins = config => {
-  const plugins = [];
-  plugins.push(immer(config['immer']));
-  plugins.push(effects(config['effects']));
-  plugins.push(autoActions(config['autoActions']));
-  plugins.push(devtools(config['devtools']));
-  return plugins;
-};
+// runtime plugin
+import { router } from '@modern-js/runtime/plugins';
+
+const IS_BROWSER = typeof window !== 'undefined' && window.name !== 'nodejs';
+const MOUNT_ID = 'root';
+
 let AppWrapper = null;
+
 function render() {
   AppWrapper = createApp({
     plugins: [
-      state({
-        ...{ plugins: createStatePlugins(true) },
-        ...App?.config?.state,
-      }),
-    ],
-  })(App);
+     router({...{"serverBase":["/"]}, ...App.config?.router}),
+    ]
+  })(App)
   if (IS_BROWSER) {
-    bootstrap(AppWrapper, MOUNT_ID);
+    bootstrap(AppWrapper, MOUNT_ID, null, ReactDOM);
   }
-  return AppWrapper;
+  return AppWrapper
 }
+
 AppWrapper = render();
 export default AppWrapper;
 ```

package/docs/zh/apis/app/hooks/src/index_.mdx

@@ -4,13 +4,13 @@ sidebar_position: 4
 ---
 # index.[tj]s
 
-应用项目入口标识。
+应用使用自定义 `bootstrap` 时的入口标识。
 
-通常情况下 [`src/App.[tj]sx, src/[entry]/App.[tj]sx`](/apis/app/hooks/src/app) 钩子文件已经能满足我们的需求，当我们需要在 `bootstrap` 之前添加自定义行为或者完全接管 webpack 打包入口时，可以在 `src` 或者入口目录下放置 `index.[tj]s`。 下面有分两种情况进行讨论:
+通常情况下 [`App.[tj]sx`](/apis/app/hooks/src/app) 钩子文件已经能满足我们的需求，当我们需要在 `bootstrap` 之前添加自定义行为或者完全接管 webpack 打包入口时，可以在 `src` 或者入口目录下放置 `index.[tj]s`。 下面有分两种情况进行讨论：
 
-1. 在 bootstrap 之前添加自定义行为：
+## 在 bootstrap 之前添加自定义行为
 
-只需要 `src/index.[tj]s` 默认导出函数:
+只需要 `src/index.[tj]s` 默认导出函数：
 
 ```js title=src/index.js
 import ReactDOM from 'react-dom/client';
@@ -22,9 +22,9 @@ export default (App: React.ComponentType) => {
 };
 ```
 
-2. 完全接管 webpack 入口:
+## 完全接管 webpack 入口
 
-当 `src/index.[tj]sx?` 下没有默认导出函数时，该文件即为真正的 webpack 打包入口文件, 可以直接像使用 create-react-app 等脚手架一样组织代码:
+当 `src/index.[tj]sx?` 下没有默认导出函数时，该文件即为真正的 webpack 打包入口文件, 可以直接像使用 create-react-app 等脚手架一样组织代码：
 
 ```js title=src/index.jsx
 import React from 'react';

package/docs/zh/apis/app/hooks/src/pages.mdx

@@ -4,9 +4,13 @@ sidebar_position: 3
 ---
 # pages/
 
-应用使用基于文件系统路由时的入口标识。
+应用使用 [`Pages` 入口](https://modernjs.dev/v1/docs/guides/usages/entries#pages-%E5%85%A5%E5%8F%A3)时的入口标识。
 
-当项目结构为 `Pages 入口` 类型时， 会分析 `src/pages` 目录下的文件得到客户端路由配置。
+:::info
+兼容 Modern.js 1.0 `Pages` 入口，推荐使用[约定式路由](guides/basic-features/routes.html#约定式路由)。
+:::
+
+当项目结构为 `Pages 入口`类型时， 会分析 `src/pages` 目录下的文件得到客户端路由配置。
 
 举例说明，例如以下目录结构：
 
@@ -20,7 +24,7 @@ sidebar_position: 3
         └── info.jsx
 ```
 
-对应生成的路由配置为:
+对应生成的路由配置为：
 
 ```bash
 [

package/docs/zh/apis/app/hooks/src/routes.mdx

@@ -4,13 +4,13 @@ sidebar_position: 2
 ---
 # routes/
 
-应用使用基于文件系统路由时的入口标识。
+应用使用[约定式路由](guides/basic-features/routes.html#约定式路由)时的入口标识。
 
-当项目结构为 `Routes 入口` 类型时， 会分析 `src/routes` 目录下的文件得到客户端路由配置。具体用法请查看[约定式路由](/guides/basic-features/routes)
+约定式路由以 `routes/` 为约定的入口， 会分析 `src/routes` 目录下的文件得到客户端路由配置。
 
 任何在 `src/routes` 下的 `layout.[tj]sx` 和 `page.[tj]sx` 都会作为应用的路由：
 
-```bash {3}
+```bash {3,4}
 .
 └── routes
     ├── layout.tsx
@@ -54,7 +54,7 @@ sidebar_position: 2
 
 在组件中，可以通过 [useParams](/apis/app/runtime/router/router#useparams) 获取对应命名的参数。
 
-在 loader 中，params 会作为 [loader](/guides/basic-features/data-fetch#loader-函数) 的入参，通过 `params` 的属性可以获取到对应的参数。
+在使用 [loader](/guides/basic-features/data-fetch#loader-函数) 函数获取数据时，`params` 会作为 `loader` 函数的入参，通过 `params` 的属性可以获取到对应的参数。
 
 ## 布局组件
 

package/docs/zh/apis/app/hooks/src/stories.mdx

@@ -8,7 +8,7 @@ sidebar_position: 7
 
 可以在项目源码目录 `src/` 下创建 `*.stories.[tj]sx` 格式的文件作为 Storybook 的调试文件。
 
-在项目下执行 dev story 命令，支持使用这些文件在 Storybook 中对相关内容进行调试。
+在项目下执行 `npm run dev story` 命令，支持使用这些文件在 Storybook 中对相关内容进行调试。
 
 :::info
 使用 Storybook 需要提前在项目下执行 new 命令启用「Visual Testing (Storybook)」模式。

package/docs/zh/guides/basic-features/routes.mdx

@@ -449,7 +449,7 @@ export const init = (context: RuntimeContext) => {
 在约定式路由下， Modern.js 会根据路由，自动地对路由进行分片，当用户访问具体的路由时，会自动加载对应的分片，这样可以有效地减少首屏加载的时间。但这也带来了一个问题，当用户访问一个路由时，如果该路由对应的分片还未加载完成，就会出现白屏的情况。
 这种情况下你可以通过定义 `Loading` 组件，在静态资源加载完成前，展示一个自定义的 `Loading` 组件。
 
-为了进一步提升用户体验，减少 loading 的时间，Modern.js 支持在 Link 组件上定义 `prefetch` 属性，可以提前对静态资源和数据进行加载， `prefetch` 属性有三个可选值：
+为了进一步提升用户体验，减少 loading 的时间，Modern.js 支持在 Link 组件上定义 `prefetch` 属性，可以提前对静态资源和数据进行加载：
 
 ```tsx
 <Link prefetch="intent" to="page">
@@ -461,6 +461,8 @@ export const init = (context: RuntimeContext) => {
 
 :::
 
+`prefetch` 属性有三个可选值：
+
 - `none`， 默认值，不会做 prefetch，没有任何额外的行为。
 - `intent`，这是我们推荐大多数场景下使用的值，当你把鼠标放在 Link 上时，会自动开始加载对应的分片和 Data Loader 中定义的数据，当鼠标移开时，会自动取消加载。在我们的测试中，即使是快速点击，也能减少大约 200ms 的加载时间。
 - `render`，当 Link 组件渲染时，就会加载对应的分片和 Data Loader 中定义的数据。
@@ -505,8 +507,6 @@ export default () => {
 Modern.js 默认对约定式路由做了一系列资源加载及渲染上的优化，并且提供了开箱即用的 SSR 能力，而这些能力，在使用自控路由时，都需要开发者自行封装，推荐开发者使用约定式路由。
 :::
 
-使用自控式路由时，如果开发者关闭了 [`runtime.router`](/configure/app/runtime/router) 配置，并直接使用 `react-router-dom`，那还需要根据 React Router 文档自行包裹 `Provider`。
-
 ## 其他路由方案
 
 默认情况下，Modern.js 会开启内置的路由方案，即 React Router。
@@ -519,7 +519,9 @@ export default defineConfig({
 });
 ```
 
-Modern.js 从 `@modern-js/runtime/router` 命名空间暴露了 React Router 的 API 供开发者使用，保证开发者和 Modern.js 中使用同一份代码。另外，这种情况下，React Router 的代码会被打包到 JS 产物中。如果项目已经有自己的路由方案，或者不需要使用客户端路由，可以关闭这个功能。
+如上述配置，当开启 [`runtime.router`](/configure/app/runtime/router) 配置时，Modern.js 会从 `@modern-js/runtime/router` 命名空间导出 React Router 的 API 供开发者使用，保证开发者和 Modern.js 中使用同一份代码，并自动根据 router 配置包裹 `Provider` 组件。另外，这种情况下，React Router 的代码会被打包到 JS 产物中。
+
+如果项目已经有自己的路由方案，或者不需要使用客户端路由，可以关闭这个功能。
 
 ```js
 export default defineConfig({
@@ -529,5 +531,6 @@ export default defineConfig({
 });
 ```
 
+如上述配置， 如果关闭了 [`runtime.router`](/configure/app/runtime/router) 配置，并直接使用 `react-router-dom` 进行项目路由管理时，还需要根据 React Router 文档自行包裹 `Provider`。
 
 

package/package.json

@@ -15,13 +15,13 @@
     "modern",
     "modern.js"
   ],
-  "version": "0.0.0-next-1685369216913",
+  "version": "0.0.0-next-1685418932858",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "0.0.0-next-1685369216913"
+    "@modern-js/builder-doc": "0.0.0-next-1685418932858"
   },
   "devDependencies": {
     "classnames": "^2",
@@ -33,9 +33,9 @@
     "fs-extra": "^10",
     "@types/node": "^16",
     "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "0.0.0-next-1685369216913",
-    "@modern-js/doc-tools": "0.0.0-next-1685369216913",
-    "@modern-js/doc-plugin-auto-sidebar": "0.0.0-next-1685369216913"
+    "@modern-js/builder-doc": "0.0.0-next-1685418932858",
+    "@modern-js/doc-tools": "0.0.0-next-1685418932858",
+    "@modern-js/doc-plugin-auto-sidebar": "0.0.0-next-1685418932858"
   },
   "scripts": {
     "dev": "modern dev",

package/docs/en/apis/app/hooks/api/framework/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "框架写法",
-  "position": 2
-}

package/docs/en/apis/app/hooks/api/framework/lambda.mdx

@@ -1,57 +0,0 @@
----
-title: lambda/*.[tj]s
-sidebar_position: 1
----
-# lambda/*.[tj]s
-
-Declaring API routing in BFF framework mode. Except [some files](/apis/app/hooks/api/framework/lambda#allow-list), files in `api/` are registered as routes.
-
-:::info
-use `api/` need execute new command to enable the 「BFF」 feature.
-
-:::
-
-:::tip
-this file supports the use `js` or `ts`, but the functions must be exported using the ESM syntax.
-
-:::
-
-## Routing Rule
-
-### Default Route
-
-The files named `index` will be upper level routing:
-
-- `api/lambda/index.ts` -> `$BASENAME/`
-- `api/lambda/user/index.ts` -> `$BASENAME/user`
-
-### Multi Level Route
-
-The routing system also supports parsing multiple levels of files. and if you create a folder, the files will still be automatically parsed in the same way.
-
-- `api/lambda/hello.ts` -> `$BASENAME/hello`
-- `api/lambda/user/list.ts` -> `$BASENAME/user/list`
-
-### Dynamic Route
-
-Dynamic named routing parameters can be supported by creating folders or files with `[xxx]`.
-
-- `api/lambda/user/[username]/info.ts` -> `$BASENAME/user/:username/info`
-- `api/lambda/user/[username]/delete.ts` -> `$BASENAME/user/:username/delete`
-- `api/lambda/article/[id]/info.ts` -> `$BASENAME/article/:id/info`
-
-the `$BASENAME` can be configured in `modern.config.js`, the default value is `/api`.
-
-### Allow List
-
-By default, all files in the `api/` will be parsed as BFF function. but we also set a allow list, and these files will not be parsed:
-
-- file name start with `_`, for example: `_utils.ts`.
-- files in directory that name start with `_`, for example: `_utils/index.ts`、`_utils/cp.ts`.
-- test files, for example: `foo.test.ts`.
-- TypeScript define files, for example: `hello.d.ts`.
-- files in `node_module`.
-
-## Define Function
-
-the same as [Define Function](/apis/app/hooks/api/functions/api#define-function).

package/docs/en/apis/app/hooks/api/functions/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "函数写法",
-  "position": 1
-}

package/docs/en/apis/app/hooks/api/functions/api.mdx

@@ -1,81 +0,0 @@
----
-title: '**/*.[tj]s'
-sidebar_position: 1
----
-# **/*.[tj]s
-
-Declaring API routing in BFF function mode. Except [some files](/apis/app/hooks/api/functions/api#allow-list), files in `api/` are registered as routes.
-
-:::info
-use `api/` need execute new command to enable the 「BFF」 feature.
-
-:::
-
-:::tip
-this file supports the use `js` or `ts`, but the functions must be exported using the ESM syntax.
-
-:::
-
-## Routing Rule
-
-### Default Route
-
-The files named `index` will be upper level routing:
-
-- `api/index.ts` -> `$BASENAME/`
-- `api/user/index.ts` -> `$BASENAME/user`
-
-### Multi Level Route
-
-The routing system also supports parsing multiple levels of files. and if you create a folder, the files will still be automatically parsed in the same way.
-
-- `api/hello.ts` -> `$BASENAME/hello`
-- `api/user/list.ts` -> `$BASENAME/user/list`
-
-### Dynamic Route
-
-Dynamic named routing parameters can be supported by creating folders or files with `[xxx]`.
-
-- `api/user/[username]/info.ts` -> `$BASENAME/user/:username/info`
-- `api/user/[username]/delete.ts` -> `$BASENAME/user/:username/delete`
-- `api/article/[id]/info.ts` -> `$BASENAME/article/:id/info`
-
-the `$BASENAME` can be configured in `modern.config.js`, the default value is `/api`.
-
-### Allow List
-
-By default, all files in the `api/` will be parsed as BFF function. but we also set a allow list, and these files will not be parsed:
-
-- file name start with `_`, for example: `_utils.ts`.
-- files in directory that name start with `_`, for example: `_utils/index.ts`、`_utils/cp.ts`.
-- test files, for example: `foo.test.ts`.
-- TypeScript define files, for example: `hello.d.ts`.
-- files in `node_module`.
-
-## Define Function
-
-In addition to the above routing rules, the function definition and export in the code also have conventions.
-
-function need named exports, and the name of the exported function is the HTTP Method:
-
-```ts
-export const get = async () => {
-  return {
-    name: 'Modern.js',
-    desc: 'Modern web Solutions',
-  };
-};
-```
-
-Export the function like above will generate a `POST` interface.
-
-App support 9 Method definitions: `GET`、`POST`、`PUT`、`DELETE`、`CONNECT`、`TRACE`、`PATCH`、`OPTION`、`HEAD`. so App can use these name as function export nane.
-
-The name is insensitive, whaterver `get`、`Get`、`GEt`、`GET`, can be accurately identified. And default export, `export default xxx` will be `Get` method.
-
-because `delete` is a keyword in JavaScript, use `del` or `DELETE` instead.
-
-Multiple functions of different Methods can be defined in one file, but if multiple functions of the same Method are defined, only the first can work.
-
-:::info
-It should be noted that the defined functions should be asynchronous, which is related to the type when the function is called.

package/docs/en/apis/app/hooks/api/functions/app.mdx

@@ -1,12 +0,0 @@
----
-title: _app.[tj]s
-sidebar_position: 3
----
-# _app.[tj]s
-
-in BFF function mode, this file can add middleware before [BFF 函数](/apis/app/hooks/api/functions/api).
-
-:::note
-For detail, see [hook](/apis/app/runtime/bff/hook)
-
-:::

package/docs/en/apis/app/hooks/api/functions/common.mdx

@@ -1,9 +0,0 @@
----
-title: '**/_*.[tj]s, _*/**'
-sidebar_position: 2
----
-# **/_*.[tj]s, _*/**
-
-under BFF function mode, these files are not registered as routes.
-
-Any files that not routes, but required in the project can be named in this way.

package/docs/zh/apis/app/hooks/api/framework/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "Framework Mode",
-  "position": 2
-}

package/docs/zh/apis/app/hooks/api/functions/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "Function Mode",
-  "position": 1
-}

package/docs/zh/apis/app/hooks/api/functions/app.mdx

@@ -1,12 +0,0 @@
----
-title: _app.[tj]s
-sidebar_position: 3
----
-# _app.[tj]s
-
-在函数写法下，该文件可以为 [BFF 函数](/apis/app/hooks/api/functions/api)添加前置中间件。
-
-:::note
-具体示例请参考 [hook](/apis/app/runtime/bff/hook)
-
-:::

package/docs/zh/apis/app/hooks/api/functions/common.mdx

@@ -1,9 +0,0 @@
----
-title: '**/_*.[tj]s, _*/**'
-sidebar_position: 2
----
-# **/_*.[tj]s, _*/**
-
-在 BFF 函数写法下，这些文件不会注册为路由。
-
-你可以在这种目录或文件下放任意项目中需要的代码，文件等。