@modern-js/main-doc 2.1.0 → 2.2.0

package/en/configure/app/runtime/intro.mdx

@@ -0,0 +1,95 @@
+---
+sidebar_label: Overview
+sidebar_position: 1
+---
+
+# Overview
+
+This section describes the configuration of the Runtime plugin.
+
+## Configuration
+
+### runtime
+
+- Type: `Object`
+
+The runtime is configured as follows:
+
+#### Base
+
+Configure in `modern.config.ts`:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  runtime: {
+    state: true,
+    router: true,
+  },
+});
+```
+
+#### DefineConfig
+
+Configure use [`defineConfig`](/apis/app/runtime/app/define-config) API:
+
+:::info
+When there is a function in the runtime configuration, it can only be configured in this way.
+
+:::
+
+```ts title="src/App.tsx"
+import { defineConfig } from '@modern-js/runtime';
+
+const App = () => {
+  /** */
+};
+
+defineConfig(App, {
+  router: {
+    supportHtml5History: false,
+  },
+});
+
+export default App;
+```
+
+:::info
+Using runtime configuration, you can solve the problem that runtime plugin configuration needs to be at runtime to get specific content.
+
+Runtime plugin runtime configuration and configuration directly in `modern.config.ts` are merged by default, and runtime configuration takes precedence.
+
+:::
+
+:::warning
+defineConfig 中只能定义 Runtime 插件的具体配置内容，确认是否开启插件还需要通过 `package.json` 中的 `modernConfig` 或者 `modern.config.ts` 中的配置决定。
+
+:::
+
+### runtimeByEntries
+
+- Type: `Object`
+
+#### Introduce
+
+Add the runtime configuration according to the entry. The option attribute is consistent with the runtime. The specified value will be replaced and merged with the content of the runtime attribute.
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  runtime: {
+    state: false,
+  },
+  runtimeByEntries: {
+    entry1: {
+      state: true, // { state: true }
+    },
+    entry2: {
+      // { state: false, router: true }
+      router: true,
+    },
+  },
+});
+```

package/en/configure/app/runtime/master-app.mdx

@@ -0,0 +1,41 @@
+---
+sidebar_label: masterApp
+---
+
+# runtime.masterApp
+
+- Type： `Object`
+
+:::info
+First you need to enable the "micro frontend" function using [new command](/apis/app/commands/new).
+
+:::
+
+## Example
+
+import EnableMicroFrontend from "@site-docs-en/components/enable-micro-frontend";
+import MasterManifestAppConfig from "@site-docs-en/components/micro-master-manifest-config";
+
+<EnableMicroFrontend />
+<MasterManifestAppConfig />
+
+### apps
+
+When `apps` is an object, it represents the information of the child application module `Array<AppInfo>`.
+
+```ts
+interface AppInfo {
+  name: string;
+  entry: string;
+  activeWhen?: string | ()=> boolean;
+}
+```
+
+- name: The name of the module.
+- entry: The entry of the module.
+
+### Other Config
+
+Under the `masterApp` configuration, developers can pass through the configuration items of Garfish.
+
+All supported configuration items [see here](https://garfishjs.org/api/run/#%E5%8F%82%E6%95%B0).

package/en/configure/app/runtime/router.mdx

@@ -0,0 +1,33 @@
+---
+sidebar_label: router
+---
+
+import RouterLegacyTip from "@site-docs-en/components/router-legacy-tip"
+
+<RouterLegacyTip />
+
+# runtime.router
+
+- Type: `boolean | Object`
+- Default: `false`
+
+When `router` is enabled, routing management of conventional routes provided by Modern.js is supported. Based on [React Router 6](https://reactrouter.com/).
+
+## basename
+
+- Type: `string`
+- Default: ``
+
+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`, `BrowserRouter` would be used, otherwise `HashRouter` would be used. `BrowserRouter` is recommended.
+
+:::warning
+When SSR is enabled, `supportHtml5History` is not supported.
+
+:::

package/en/configure/app/runtime/state.mdx

@@ -0,0 +1,54 @@
+---
+sidebar_label: state
+---
+
+# runtime.state
+
+- Type:`boolean | object`
+- Default: `false`
+
+Once `state` is enabled, you can use [Model](/guides/topic-detail/model/quick-start) for state management.
+
+The specific configuration items are as follows:
+
+## 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
+
+- 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
+
+- Type:`boolean`
+- Default: `true`
+
+Whether to enable the auto-generated actions feature, it is enabled by default, and set to `false` if you want to disable it.
+
+## devtools
+
+- Type:`boolean | EnhancerOptions`
+- Default: `true`
+
+Whether to enable devtools, it is enabled by default, and all parameters of [redux-devtools-extension](https://github.com/zalmoxisus/redux-devtools-extension/blob/master/docs/API/Arguments.md) are supported at the same time. If you want to disable it, set it to `false`.

package/en/configure/app/server/enable-framework-ext.mdx

@@ -0,0 +1,49 @@
+---
+sidebar_label: enableFrameworkExt
+---
+
+# server.enableFrameworkExt
+
+- Type: `boolean`
+- Default: `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.
+
+```ts 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/configure/app/server/routes.mdx

@@ -0,0 +1,90 @@
+---
+sidebar_label: routes
+---
+
+# server.routes
+
+- Type: `Object`
+- Default: Automatic generation of server-level routing rules based on file conventions: One routing rule is generated per file of the application,and the default route is the same as the entry name.
+
+This configuration option only applies to server-level routing, and can customize the service access configuration of the application entry.
+
+## Custom access routing
+
+The `key` of the object is the entry name of the current application, and the value can be `string | Array<string>`.
+
+When the value type is `string`, the current value represents the name of the route to access the entry.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    routes: {
+      // The default route is /entryName1, /p/test1 after customization
+      entryName1: '/p/test1'
+      // Support dynamic server-level routing configuration
+      entryName2: '/detail/:id'
+    }
+  }
+});
+```
+
+Multiple access routes can also be set for entries using the `Array<string>`:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    routes: {
+      'page-a': [`/a`, '/b'],
+    },
+  },
+});
+```
+
+At this point, the '`page-a` entry can be accessed through both `/a` and `/b` routes.
+
+After executing the `dev` command, you can see in `dist/route.json` that there are two routing records in the entry `page-a`:
+
+```json
+{
+  "routes": [
+    {
+      "urlPath": "/a",
+      "entryName": "page-a",
+      "entryPath": "html/page-a/index.html",
+      "isSPA": true,
+      "isSSR": false
+    },
+    {
+      "urlPath": "/b",
+      "entryName": "page-a",
+      "entryPath": "html/page-a/index.html",
+      "isSPA": true,
+      "isSSR": false
+    }
+  ]
+}
+```
+
+## Custom response header
+
+The response header can be set by configuring the resHeaders of the entry:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    routes: {
+      'page-a': {
+        route: ['/a', '/b'],
+        resHeaders: {
+          'x-modern-test': '1',
+        },
+      },
+    },
+  },
+});
+```
+
+:::note
+This configuration takes effect in both the production environment and the development environment, and can set different response headers according to the NODE_ENV. But if you only need to set response headers in the development environment, `tools.devServer.headers` is recommended.
+
+:::

package/en/configure/app/server/ssr-by-entries.mdx

@@ -0,0 +1,29 @@
+---
+sidebar_label: ssrByEntries
+---
+
+# server.ssrByEntries
+
+- Type: `Object`
+- Default: `undefined`
+
+Set the ssr option according to the entry. The attributes in the option are the same as [ssr](./ssr.md). The specified value will be replaced and merged with the content of the ssr attribute. For example:
+
+:::info
+The "entry name" defaults to the directory name. In a few cases, when the entry is customized by `source.entries`, the entry name `source.entries` the `key` of the object.
+
+:::
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    ssr: true,
+    ssrByEntries: {
+      // page-a does not enable ssr
+      'page-a': false,
+    },
+  },
+});
+```
+
+As configured above, the project has ssr enabled as a whole, but the ssr rendering capability is turned off for the entry `page-a`.

package/en/configure/app/source/config-dir.mdx

@@ -0,0 +1,24 @@
+---
+title: source.configDir
+sidebar_label: configDir
+---
+# configDir
+
+- Type: `string`
+- Default: `./config`
+
+Modern.js supports placing some files in the `./config` folder to customize HTML templates, icons, static resources, etc. For details, please refer to [File Convention](/apis/app/hooks/config/html).
+
+This option allows you to customize the directory of configuration files.
+
+For example, adjust the resource file directory to the `resources` directory:
+
+```js title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    configDir: './resources',
+  },
+});
+```