@modern-js/main-doc 2.66.0 → 2.66.1-alpha.1

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

@@ -1,44 +1,30 @@
----
-title: App.[tj]sx
-sidebar_position: 1
----
 # App.[tj]sx
 
-The identifier for the entry points when the application uses [Self-controlled Routing](/guides/concept/entries.html#self-controlled-routing).
+The entry identifier when using [Self-controlled Routing](/guides/concept/entries.html#self-controlled-routing) in the application.
 
-`App.[tj]sx` is not the actual entry. Modern.js will generate the real entry for application. The content is roughly as follows:
+`App.[tj]sx` is not the actual application entry; Modern.js will automatically generate the real entry file, which is roughly as follows:
 
 ```js
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import { createApp, bootstrap } from '@modern-js/runtime';
-// App.[jt]sx
+// runtime-global-context
+import { setGlobalContext } from '@modern-js/runtime/context';
 import App from '@_modern_js_src/App';
-// 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: [
-     router({...{"serverBase":["/"]}, ...App.config?.router}),
-    ]
-  })(App)
-  if (IS_BROWSER) {
-    bootstrap(AppWrapper, MOUNT_ID, null, ReactDOM);
-  }
-  return AppWrapper
-}
-
-AppWrapper = render();
-export default AppWrapper;
+
+setGlobalContext({
+  App,
+});
+
+// index.tsx
+import './runtime-global-context';
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+render(<ModernRoot />, 'root');
 ```
 
-:::note
-In the multi-entry scenario, each entry can have its own `App.[jt]sx`. See [Entries](/guides/concept/entries) for details.
+When `createRoot` is executed, it will retrieve the registered Global App and generate the actual React component.
 
+:::note
+In scenarios with multiple entry points, each entry can have its own independent `App.[jt]sx`. For more details, see [Entry Points](/guides/concept/entries).
 :::

package/docs/en/apis/app/hooks/src/modern.runtime.mdx

@@ -0,0 +1,9 @@
+---
+title: modern.runtime.[tj]s
+sidebar_position: 4
+---
+# modern.runtime.[tj]s
+
+The Modern.js Runtime configuration file allows for personalized configuration of the Runtime capabilities for the current project.
+
+For specific usage of the configuration, please refer to [Runtime Configuration](/configure/app/runtime/0-intro.html).

package/docs/en/apis/app/runtime/app/define-config.mdx

@@ -3,8 +3,14 @@ title: defineConfig
 ---
 # defineConfig
 
+:::warning
+
+Soon to be deprecated. It is recommended to use `src/modern.runtime.ts` to define Runtime configurations, which supports both static and dynamic configurations. Please refer to the plugin [Runtime Configuration](/configure/app/runtime/0-intro.html).
+
 For dynamically configuring applications runtime features.
 
+:::
+
 ## Usage
 
 ```ts

package/docs/en/apis/app/runtime/web-server/hook.mdx

@@ -6,6 +6,11 @@ title: Hook
 
 Used to extend Modern.js built-in Web Server, all page requests are handled by these hooks.
 
+:::warning
+It is recommended to use [UnstableMiddleware](/apis/app/runtime/web-server/unstable_middleware) to handle page requests.
+
+:::
+
 :::note
 For more detail, see [Extend Web Server](/guides/advanced-features/web-server).
 

package/docs/en/apis/app/runtime/web-server/middleware.mdx

@@ -6,9 +6,9 @@ title: Middleware
 
 Used to extend the built-in Web Server of Modern.js, unlike [Hook](/apis/app/runtime/web-server/hook), Middleware can directly operate Node's origin request and response, and can be extended using the framework plugin.
 
-:::note
+:::warning
 
-In the next major release, Modern.js will use new middleware to replace this approach.
+Middleware will be removed in the next major version.
 
 It is recommended to use [UnstableMiddleware](/apis/app/runtime/web-server/unstable_middleware) to handle page requests.
 
@@ -118,24 +118,3 @@ export const Middleware = () => async (ctx, next) => {
   ctx.response.locals.rpc = createRpcInstance();
 };
 ```
-
-### Framework Extension
-
-Middleware can also use runtime framework extensions like BFF.
-
-When using framework runtime extensions, type information is exported from `@modern-js/runtime/{namespace}`. Middleware can use framework syntax, such as framework middleware writing, the following is pseudo-code:
-
-```ts
-import { SomeType } from '@modern-js/runtime/{namespace}';
-
-export const middleware: SomeType = (ctx, next) => {
-  console.log(ctx.url);
-  next();
-};
-```
-
-By default, the framework extension capability of Web Server is turned off after installing the framework extension plugin. If you want to use the framework extension, you can turn it on through ['server.enableFrameworkExt'](/configure/app/server/enable-framework-ext.html).
-
-:::info
-The type name exported by the framework extension may not 'Middleware', but is named by the framework extension plugin.
-:::

package/docs/en/components/enable-micro-frontend.mdx

@@ -1,13 +1,30 @@
-```js title="modern.config.ts"
+```ts title="modern.config.ts"
 import { appTools, defineConfig } from '@modern-js/app-tools';
 import { garfishPlugin } from '@modern-js/plugin-garfish';
 
 export default defineConfig({
   runtime: {
     router: true,
-    state: true,
-    masterApp: true,
   },
   plugins: [appTools(), garfishPlugin()],
 });
+
+```
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+export default defineRuntimeConfig({
+  masterApp: {
+    apps: [{
+      name: 'Table',
+      entry: 'http://localhost:8081',
+      // activeWhen: '/table'
+    }, {
+      name: 'Dashboard',
+      entry: 'http://localhost:8082'
+      // activeWhen: '/dashboard'
+    }]
+  },
+});
 ```

package/docs/en/components/micro-runtime-config.mdx

@@ -1,18 +1,17 @@
-```js title="src/App.tsx"
-import { defineConfig } from '@modern-js/runtime';
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
 
-defineConfig(App, {
+export default defineRuntimeConfig({
   masterApp: {
-    apps: [
-      {
-        name: 'DashBoard',
-        entry: 'http://127.0.0.1:8081/',
-      },
-      {
-        name: 'TableList',
-        entry: 'http://localhost:8082',
-      },
-    ],
+    apps: [{
+      name: 'Table',
+      entry: 'http://localhost:8081',
+      // activeWhen: '/table'
+    }, {
+      name: 'Dashboard',
+      entry: 'http://localhost:8082'
+      // activeWhen: '/dashboard'
+    }]
   },
 });
 ```

package/docs/en/components/reduck-notify.mdx

@@ -0,0 +1,27 @@
+:::warning
+Starting from `MAJOR_VERSION.67.0`, Modern.js no longer provides Reduck state management capabilities by default. If you need to use Reduck, you must install and register the state plugin.
+
+**Installation Steps**
+
+1. Install the `@modern-js/plugin-state` dependency:
+
+```bash
+pnpm add @modern-js/plugin-state
+```
+
+2. Register the state plugin:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import { statePlugin } from '@modern-js/plugin-state';
+
+export default defineConfig({
+  ...,
+  plugins: [
+    ...,
+    statePlugin(),
+  ],
+});
+```
+
+:::

package/docs/en/configure/app/runtime/0-intro.mdx

@@ -1,119 +1,95 @@
----
-title: Overview
-sidebar_position: 1
----
+# Introduce
 
-# Overview
+Modern.js runtime configuration should be centralized in the `src/modern.runtime.ts` file.
 
-This section describes configuration of the Runtime plugin.
-
-## Configuration
-
-### runtime
-
-- **Type:** `Object`
-
-The runtime is configured as follows:
+:::info
+If this file doesn't exist in your project yet, create it with the following command:
 
-#### Base
+```bash
+touch src/modern.runtime.ts
+```
+:::
 
-Configure in `modern.config.ts`:
+## Basic Configuration
 
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
+```tsx
+import { defineRuntimeConfig } from '@modern-js/runtime';
 
-export default defineConfig({
-  runtime: {
-    state: true,
-    router: true,
+export default defineRuntimeConfig({
+  router: {
+    // Router configuration
+  },
+  state: {
+    // State management configuration
   },
+  // Other runtime modules...
 });
 ```
 
-#### DefineConfig
-
-Configure using [`defineConfig`](/apis/app/runtime/app/define-config) API:
-
-:::info
-When there is a function in the runtime configuration, it can only be configured this way.
-
-:::
+## Multi-Entry Configuration
 
-import { Tabs, Tab as TabItem } from "@theme";
+For multi-entry applications, `defineRuntimeConfig` can accept a function that returns specific configurations based on the entry name:
 
-<Tabs>
-  <TabItem value="layout" label="Conventional Routing" default>
+```tsx
+import { defineRuntimeConfig } from '@modern-js/runtime';
 
-```tsx title="src/routes/layout.tsx"
-import type { AppConfig } from '@modern-js/runtime';
-
-export const config = (): AppConfig => {
-  return {
-    router: {
-      supportHtml5History: false
-    }
+export default defineRuntimeConfig((entryName) => {
+  if (entryName === 'main') {
+    return {
+      router: {
+        // Router configuration for "main" entry
+      },
+      state: {
+        // State management configuration for "main" entry
+      },
+    };
   }
-};
-```
-
-  </TabItem>
-
-  <TabItem value="app" label="Self-controlled Routing">
-
-```ts title="src/App.tsx"
-import { defineConfig } from '@modern-js/runtime';
-
-const App = () => {
-  /** */
-};
 
-defineConfig(App, {
-  router: {
-    supportHtml5History: false,
-  },
+  // Configuration for other entries
+  return {
+    masterApp: {
+      // Micro-frontend configuration example
+    },
+  };
 });
-
-export default App;
 ```
+:::tip
+Using the `src/modern.runtime.ts` configuration approach does not support exporting asynchronous functions, which is related to the rendering method of Modern.js. If you need to add asynchronous logic, please use the **[Runtime Plugin](/plugin/introduction.html#runtime-plugin)**.
+:::
 
-  </TabItem>
-</Tabs>
-
-:::info
-Using runtime configuration, you can solve the problem that runtime plugin configuration needs to be at runtime to get specific content.
+:::warning
+Using the `src/modern.runtime.ts` configuration approach requires Modern.js version **MAJOR_VERSION.66.0** or higher.
+:::
 
-Runtime plugin runtime configuration and configuration directly in `modern.config.ts` are merged by default, and runtime configuration takes precedence.
+import RuntimeCliConfig from '@site-docs/components/runtime-cli-config';
 
-:::
+<RuntimeCliConfig />
 
-:::warning
-The `defineConfig` API only accepts the specific configuration of Runtime plugins. Enabling the plugin is determined through `modern.config.ts` configuration."
+## Configuration Evolution
 
-:::
+Before MAJOR_VERSION.66.0, runtime configurations were scattered across multiple locations:
 
-### runtimeByEntries
+1. The `runtime` and `runtimeByEntries` fields in `modern.config.ts`
+2. The `App.config` or the `config` function exported from `layout` files for each entry
 
-- **Type:** `Object`
+To improve maintainability, Modern.js introduced the unified `src/modern.runtime.ts` configuration entry.
 
-#### Introduction
+### Legacy Configuration (Compatible but Not Recommended)
 
-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
+// modern.config.ts
+export default {
+  runtime: { /* ... */ },
+  runtimeByEntries: { /* ... */ },
+};
 
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
+// App.config
+App.config = {/* ... */}
 
-export default defineConfig({
-  runtime: {
-    state: false,
-  },
-  runtimeByEntries: {
-    entry1: {
-      state: true, // { state: true }
-    },
-    entry2: {
-      // { state: false, router: true }
-      router: true,
-    },
-  },
-});
+// layout file
+export const config = () => { /* Dynamic configuration logic */ };
 ```
+
+### Migration Recommendation
+
+We strongly recommend migrating all runtime configurations to `src/modern.runtime.ts`. Although the legacy configuration approach is still compatible, it is planned to be gradually deprecated in future versions. A unified configuration entry prevents scattered configurations and significantly improves project maintainability.