@modern-js/main-doc 2.0.0-canary.0 → 2.0.0

package/en/docusaurus-plugin-content-docs/current/components/micro-master-manifest-config.md

@@ -0,0 +1,15 @@
+## manifest
+
+```ts
+interface Manifest {
+  getAppList?: ()=> Array<AppInfo>
+}
+```
+
+### getAppList?
+
+Through the `getAppList` configuration, you can customize how to get remote list data
+
+```ts
+type GetAppList = ()=> Promise<Array<AppInfo>>;
+```

package/en/docusaurus-plugin-content-docs/current/components/micro-runtime-config.md

@@ -0,0 +1,18 @@
+```javascript title="src/App.tsx"
+import { defineConfig } from '@modern-js/runtime';
+
+defineConfig(App, {
+  masterApp: {
+    apps: [
+      {
+        name: 'DashBoard',
+        entry: 'http://127.0.0.1:8081/',
+      },
+      {
+        name: 'TableList',
+        entry: 'http://localhost:8082',
+      },
+    ],
+  },
+});
+```

package/en/docusaurus-plugin-content-docs/current/components/router-legacy-tip.md

@@ -0,0 +1 @@
+

package/en/docusaurus-plugin-content-docs/current/configure/app/auto-load-plugin.md

@@ -0,0 +1,62 @@
+---
+title: autoLoadPlugins
+sidebar_position: 11
+---
+
+- Type: `boolean`
+- Default: `false`
+
+Used to configure whether Modern.js enables auto-registration of plugins.
+
+### Manual Registration Plugin
+
+By default, installing the plugin requires you to register the plugin manually in the `modern.config.ts`.
+
+```ts title="modern.config.ts"
+import AppToolsPlugin, { defineConfig } from '@modern-js/app-tools';
+import I18nPlugin from '@modern-js/plugin-i18n';
+
+default export defineConfig({
+  plugins: [AppToolsPlugin(), I18nPlugin()]
+})
+
+```
+
+### Auto Registration plugin
+
+In addition to means registration, Modern.js also provides a way to automatically register plugins: set the `autoLoadPlugin` configuration item to `true`.
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+default export defineConfig({
+  autoLoadPlugins: true
+})
+```
+
+Modern.js will help you automatically register the plugin by following these steps
+
+1. Modern.js maintains an official list of plugins internally.
+
+```js
+const InternalPlugins = ['@modern-js/app-tools', '@modern-js/plugin-i18n', ...];
+```
+
+2. Modern.js will read your `package.json` and collect the dependency information.
+
+```json title="package.json"
+"dependencies": {
+  "@modern-js/plugin-i18n": "x.x.x"
+  ...
+},
+"devDependencies": {
+  "@modern-js/app-tools": "x.x.x"
+  ...
+}
+```
+
+3. Modern.js observes that when you install dependencies such as `@modern-js/plugin-i18n` and `@modern-js/app-tools`, automatic plugin registration will be imported.
+
+You can notice that this approach is relatively black-box and you are not even aware of the process of loading the plugin. We want to expose more details to the developer and be able to let the developer control the process.
+
+**Therefore we recommend you to register the plugin manually.**

package/en/docusaurus-plugin-content-docs/current/configure/app/deploy/microFrontend.md

@@ -0,0 +1,54 @@
+---
+sidebar_label: microFrontend
+---
+
+# deploy.microFrontend
+
+* 类型：`object`
+* 默认值：`{enableHtmlEntry: true, externalBasicLibrary: false}`
+
+```ts
+interface MicroFrontend {
+  enableHtmlEntry?: boolean;
+  externalBasicLibrary?: boolean;
+  moduleApp?: string;
+}
+```
+
+Developers can use the `deploy.microFrontend` to configure micro-frontend sub-application information.
+
+:::caution
+Enable the "Micro Frontend" features through `pnpm run new` first.
+:::
+
+## Example
+
+```ts
+export default defineConfig({
+  deploy: {
+    microFrontend: {
+      enableHtmlEntry: true
+    }
+  }
+});
+```
+
+## Configuration
+
+### enableHtmlEntry
+
+* Type: `boolean`
+
+* Default: `true`
+
+* Whether to enable the html entry, the default is `true`, the sub-application is built into the `HTML` mode, Garfish supports the `html` entry, you can turn on the open option, experience the corresponding features, and directly point the sub-application entry to the HTML entry when it is the HTML entry. Just point to the html of the sub-application
+* set it to `false` to indicate that the sub-application is built as `js`. After the sub-application is built as `js`, it cannot run independently. When it is a `JS` entry, point the entry file of the sub-application to the `JS` of the sub-application.
+
+
+### externalBasicLibrary
+
+* Type: `boolean`
+
+* Default: `false`
+
+Whether the `external` base library, when set to `true`, the current child application will be `external`: `react`, `react-dom`, Modern.js main application will automatically `setExternal` these two base libraries, if other types of frameworks Please add `react`, `react-dom` dependencies through `Garfish.setExternal`.

package/en/docusaurus-plugin-content-docs/current/configure/app/output/ssg.md

@@ -0,0 +1,226 @@
+---
+sidebar_label: ssg
+---
+# output.ssg
+
+* 类型： `boolean` | `object` | `function`
+* 默认值： `undefined`
+
+Enable the SSG for **Self-controlled Routing** or **Conventional Routing**.
+
+:::info
+For more routes detail, see [routes](/docs/guides/basic-features/routes)。
+:::
+
+## Example
+
+### Single Entry
+
+When the configuration is set to `true`, the SSG of all entries will be enabled by default.
+
+For **self-controlled routing**, the root route of the entry will be rendered. For **convention routing**, every route in the entry will be rendered.
+
+For example, the `src/` directory has the following file structure that satisfies **conventional routing**:
+
+```bash
+.
+├── src
+│   └── routes
+│       ├── layout.tsx
+│       ├── page.tsx
+│       └── user
+│           ├── layout.tsx
+│           ├── page.tsx
+│           └── profile
+│               └── page.tsx
+```
+
+Make the following config in `modern.config.[tj]s`:
+
+```ts
+export default defineConfig({
+  output: {
+    ssg: true,
+  },
+});
+```
+
+After executing `pnpm build` to build the application. The `dist/` directory will generate three HTML for each of the three routes (only one HTML if SSG not enabled), and all HTML has been rendered.
+
+For example the following **self-controlled routing**:
+
+```tsx title="App.tsx"
+import { useRuntimeContext } from '@modern-js/runtime';
+import { Routes, Route, BrowserRouter } from '@modern-js/runtime/router';
+import { StaticRouter } from '@modern-js/runtime/router/server';
+
+const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
+
+export default () => {
+  const { context } = useRuntimeContext();
+  return (
+    <Router location={context.request.pathname}>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </Router>
+  );
+};
+```
+
+Also using the above configuration, after executing `pnpm run build`, only the entry route `/` will generate the rendered HTML.
+
+### Multi Entries
+
+`output.ssg` can also be configured according to the entries, and the rules that the configuration takes effect are also determined by the entries routing method.
+
+例如以下目录结构：
+
+```bash
+。
+├── src
+│   ├── entryA
+│   │   └── routes
+│   │       ├── layout.tsx
+│   │       ├── page.tsx
+│   │       └── user
+│   │           ├── layout.tsx
+│   │           ├── page.tsx
+│   │           └── profile
+│   │               └── page.tsx
+│   └── entryB
+│       └── App.tsx
+```
+
+By default, all entryA entrances are rendered at build time after setting `output.ssg` to `true`. You can configure `false` to cancel the default behavior of the specified entries. For example, to cancel the rendering of the `entryA` at build time:
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      entryA: true,
+      entryB: false,
+    },
+  },
+});
+```
+
+### Configure Route
+
+As mentioned above, **Self-Controlled Routing** only enables SSG configuration for entries route by default.
+
+Set specific routes in `output.ssg` can tell Modern.js to enable the SSG of these client side routes. For example, the content of the above `src/App.tsx` file is:
+
+```tsx title="src/App.tsx"
+import { useRuntimeContext } from '@modern-js/runtime';
+import { Routes, Route, BrowserRouter } from '@modern-js/runtime/router';
+import { StaticRouter } from '@modern-js/runtime/router/server';
+
+const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
+
+export default () => {
+  const { context } = useRuntimeContext();
+  return (
+    <Router location={context.request.pathname}>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </Router>
+  );
+};
+```
+
+When set like this in `modern.config.[jt]s`, the `/about` route will also enable SSG:
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      routes: ['/', '/about'],
+    },
+  },
+});
+```
+
+Modern.js will automatically concat the complete URL according to the entry and hand it over to the SSG plugin to complete the rendering.
+
+Request headers can also be configured for specific entries or routes, for example:
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      headers: {},
+      routes: [
+        '/',
+        {
+          url: '/about',
+          headers: {},
+        },
+      ],
+    },
+  },
+});
+```
+
+:::info
+The `headers` set in the route override the `headers` set in the entry.
+:::
+
+### Prevent Default
+
+By default, **Conventional Routing** all turn on SSG. Modern.js provides another field to prevent the default SSG behavior.
+
+For example, the following directory structure ，`/`、`/user` and `/user/profle` all have SSG enabled:
+
+```bash
+.
+├── src
+│   └── routes
+│       ├── layout.tsx
+│       ├── page.tsx
+│       └── user
+│           ├── layout.tsx
+│           ├── page.tsx
+│           └── profile
+│               └── page.tsx
+```
+
+You can set this to disable the default behavior of a client-side route:
+
+```js
+export default defineConfig({
+  output: {
+    preventDefault: ['/user'],
+  },
+});
+```
+
+### Dynamic Params
+
+Some routes may be dynamic, such as the `/user/:id` in a self-controlled route or the route generated by the `user/[id]/page.tsx` file in a conventional route.
+
+configure specific parameters in `output.ssg` to render the route of the specified parameters, for example:
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      routes: [
+        {
+          url: '/user/:id',
+          params: [
+            {
+              id: 'modernjs',
+            },
+          ],
+        },
+      ],
+    },
+  },
+});
+```
+
+The features of dynamic routing and SSG is useful when generating static pages in real time based on CMS system.

package/en/docusaurus-plugin-content-docs/current/configure/app/runtime/master-app.md

@@ -4,57 +4,38 @@ sidebar_label: masterApp
 
 # runtime.masterApp
 
-* 类型： `Object`
+* Type： `Object`
 
 :::info
 First you need to enable the "micro frontend" function using [new command](/docs/apis/app/commands/new).
 :::
 
-## `manifest`
+## Example
 
-The main application adds sub-application information.
+import EnableMicroFrontend from '@site-docs-en/components/enable-micro-frontend.md';
+import MasterManifestAppConfig from '@site-docs-en/components/micro-master-manifest-config.md';
 
-* Type: `modules: Array<{
-        name: string;
-        entry: string;
-        activeWhen?: string;
-      }> | string;`
-* Default: `null`
+<EnableMicroFrontend />
+<MasterManifestAppConfig />
 
-### `modules`
 
-When `modules` is an object type, it represents the information of the sub-application module.
+### apps
 
-- name: The name of the child application
-- entry: The entry of the child application
-- activeWhen?: The path of the child application
+When `apps` is an object, it represents the information of the child application module `Array<AppInfo>`.
 
-When  `modules` is `string`, it is a url address, and requesting this address can get the same data structure as the `modules` object format.
-
-## `LoadingComponent`
-
-* Type: `React.ComponentType | React.ElementType`
-* Default: `null`
-
-A transition animation to load when loading or switching child applications.
+```ts
+interface AppInfo {
+  name: string;
+  entry: string;
+  activeWhen?: string | ()=> boolean;
+}
+```
 
-`LoadingComponent` needs to be configured with [defineConfig](/docs/apis/app/runtime/app/define-config).
+- name: The name of the module.
+- entry: The entry of the module.
 
-```tsx
-import { defineConfig } from '@modern-js/runtime';
+### Other Config
 
-function App() {
-  ...
-}
+Under the `masterApp` configuration, developers can pass through the configuration items of Garfish.
 
-defineConfig(
-  App,
-  {
-    masterApp: {
-      LoadingComponent: () => {
-        return <div>loading...</div>
-      }
-    }
-  }
-)
-```
+All supported configuration items [see here](https://garfishjs.org/api/run/#%E5%8F%82%E6%95%B0).

package/en/docusaurus-plugin-content-docs/current/configure/app/runtime/router.md

@@ -2,18 +2,31 @@
 sidebar_label: router
 ---
 
+import RouterLegacyTip from '@site-docs/components/router-legacy-tip.md'
+
+<RouterLegacyTip />
+
 # runtime.router
 
 * Type: `boolean | Object`
 * Default: `false`。
 
-When `router` is enabled, routing management using conventional routes provided by Modern.js default is supported.
+When `router` is enabled, routing management of conventional routes provided by Modern.js is supported. Based on [React Router 6](https://reactrouter.com/).
+
+## basename
 
-## Configuration
+* Type: `string`
+* Default: ``
 
-### supportHtml5History
+The basename of the app for situations where you can't deploy to the root of the domain, but a sub directory.
+
+## supportHtml5History
 
 * Type: `Boolean`
 * Default: `true`
 
-If the value of `supportHtml5History` is `true`, the project will use `BrowserRouter`, otherwise `HashRouter`.
+If the value of `supportHtml5History` is `true`, `BrowserRouter` would be used, otherwise `HashRouter` would be used. `BrowserRouter` is recommended.
+
+:::warning
+When SSR is enabled, `supportHtml5History` is not supported.
+:::

package/en/docusaurus-plugin-content-docs/current/configure/app/runtime/state.md

@@ -11,21 +11,34 @@ Once `state` is enabled, you can use [Model](/docs/guides/topic-detail/model/qui
 
 The specific configuration items are as follows:
 
-## `immer`
+## models
+
+* Type：`Array<Model>`
+* Default：`[]`
+
+Register model objects that are mounted in advance, and these models will be mounted immediately after the Reduck store is created. Generally, there is no need to mount in advance.
+
+## initialState
+* Type: `Object`
+* Default：`{}`
+
+Used to set the initial state of the global store. Generally used for SSR to initialize data during the hydration phase.
+
+## immer
 
 * Type:`boolean`
 * Default: `true`
 
 Whether to enable to update the state with mutable, it is enabled by default, and set to `false` if you want to disable it.
 
-## `effects`
+## effects
 
 * Type:`boolean`
 * Default: `true`
 
 Whether to enable the side effect management feature, it is enabled by default, and set to `false` if you want to disable it.
 
-## `autoActions`
+## autoActions
 
 * Type:`boolean`
 * Default: `true`
@@ -33,7 +46,7 @@ Whether to enable the side effect management feature, it is enabled by default,
 Whether to enable the auto-generated actions feature, it is enabled by default, and set to `false` if you want to disable it.
 
 
-## `devtools`
+## devtools
 
 * Type:`boolean | EnhancerOptions`
 * Default: `true`

package/en/docusaurus-plugin-content-docs/current/configure/app/server/enable-framework-ext.md

@@ -0,0 +1,47 @@
+---
+sidebar_label: enableFrameworkExt
+---
+# server.enableFrameworkExt
+
+* 类型： `Boolean`
+* 默认值： `false`
+
+By default, with 【Custom Web Server](/docs/guides/advanced-features/web-server) enable, Middleware uses the syntax of the Modern.js itself.
+
+Enable `server.enableFrameworkExt` to use the syntax of framework extensions.
+
+```typescript title="modern.config.ts"
+export default defineConfig({
+  server: {
+    enableFrameworkExt: true,
+  }
+});
+```
+
+## Example
+
+Default usage:
+
+```ts title="server/index.ts"
+import { Middleware } from '@modern-js/runtime/server';
+
+export const middleware: Middleware = (ctx, next) => {
+  console.log(ctx.request.url);
+  next();
+};
+```
+
+When enabled, Middleware types will be exported from other namespaces and can the syntax of framework extensions:
+
+```ts title="server/index.ts"
+import { SomeType } from '@modern-js/runtime/{frameworknName}';
+
+export const middleware: SomeType = (...args) => {
+  console.log(args[0].url);
+  next();
+};
+```
+
+:::note
+The above code is pseudo-code, and the specific usage needs to refer to the corresponding framework extension.
+:::

package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/bff/frameworks.md

@@ -3,6 +3,8 @@ sidebar_position: 3
 title: Frameworks
 ---
 
+Modern.js's BFF supports different runtime frameworks, currently Modern.js's BFF supports two runtime frameworks[Express.js](https://expressjs.com/) 和 [Koa.js](https://koajs.com/).
+
 ## Function Writing
 
 Under the function writing, only the middleware writing method of various runtime frameworks is different, and other implementations are basically the same. Take Express as an example to introduce how to write a middleware by hand in the `api/_ app.ts` and add permission verification:

package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/bff/function.md

@@ -1,13 +1,15 @@
 ---
 sidebar_position: 1
-title: Integration
+title: Basic Usage
 ---
 
-Modern.js allow functions that meet certain conditions in the `api/` directory to be directly called in the React component, which is called **integration**.
+Applications developed with Modern.js can define API functions in the `api/` directory, which can be called by the front-end to send requests without writing front and back-end glue layer code, At the same time, it ensures the type safety of the front and back end
 
-:::note
-The use of integration calls requires the enable BFF first.
-:::
+## Enable BFF
+
+import EnableBFF from '@site-docs-en/components/enable-bff.md'
+
+<EnableBFF/>
 
 ## BFF Function
 
@@ -41,7 +43,9 @@ The functions import in `src/App.tsx` will be automatically converted into inter
 
 Execute `pnpm run dev`, then open `http://localhost:8080/` to see that the page has displayed the content returned by the BFF function. In Network, you can see that the page sent a request to `http://localhost:8080/api/hello`.
 
-## Function Route
+![Network](https://p6-piu.byteimg.com/tos-cn-i-8jisjyls3a/fd41750f8d414179a9b4ecb519919b36~tplv-8jisjyls3a-3:0:0:q75.png)
+
+## API Routes
 
 In Modern.js, the BFF function routing system is implemented based on the file system, and it is also a conventional routing system.
 

package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/ssg.md

@@ -19,11 +19,15 @@ import SSGPlugin from '@modern-js/plugin-ssg';
 // https://modernjs.dev/docs/apis/app/config
 export default defineConfig({
   ...,
+  output: {
+    ...,
+    ssg: true,
+  },
   plugins: [..., SSGPlugin()],
 });
 ```
 
-SSG in **Conventional Routing** and **Self-control Routing** has different usage.
+SSG in **Conventional Routing** and **Self-controlled Routing** has different usage.
 
 ### Conventional Routing
 
@@ -80,7 +84,7 @@ Using **Conventional Routing**, each route will generate a HTML file. Looking at
 
 After executing `pnpm run serve` to start the project, visit the page in the Network, view the document returned by the request. The document contains the complete page content rendered by the component.
 
-### Self-control Routing
+### Self-controlled Routing
 
 **Self-controlled routing** is a custom routing through component code, which requires the application to run to obtain accurate routing information. Therefore, the SSG function cannot be used out of the box. At this time, the user needs to inform the Modern.js framework in advance which routes need to enable the SSG.
 

package/en/docusaurus-plugin-content-docs/current/guides/basic-features/css/_category_.json

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

package/en/docusaurus-plugin-content-docs/current/guides/basic-features/data-fetch.md

@@ -427,7 +427,7 @@ export default () => {
     // No real request is sent here, just a hard coding data is returned.
     // In a real project, the data obtained from the remote end should be returned.
     return {
-      name: 'modern.js',
+      name: 'Modern.js',
     };
   });
 

package/en/docusaurus-plugin-content-docs/current/guides/basic-features/routes.md

@@ -243,8 +243,6 @@ export default () => {
 
 :::note
 Under self-controlled routing, if developers want to use the [Loader API](https://reactrouter.com/en/main/hooks/use-loader-data#useloaderdata) capabilities in React Router 6 in SSR will be relatively complicated, it is recommended to use conventional routing directly. Modern.js has already encapsulated everything for you.
-<!-- Todo 嵌套路由带来的优化可以补充下文档-->
-If the project only wants to upgrade to React Router 6 and does not want to use the optimizations brought by nested routing, then [useLoader](/docs/apis/app/runtime/core/use-loader) will still work under SSR.
 :::
 
 ## Other