@modern-js/main-doc 2.54.6 → 2.56.0

package/docs/en/guides/basic-features/data/data-fetch.mdx

@@ -247,7 +247,7 @@ In a multi-entry (MPA) scenario, the value of `routeId` needs to include the nam
 
 If you want to get the data returned by the `loader` in `entry1/routes/layout.tsx`, the value of `routeId` is `entry1_layout`.
 
-### (WIP)Loading UI
+### Loading UI (Experimental)
 
 :::info
 This feature is currently experimental and the API may change in the future.

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

@@ -290,7 +290,7 @@ When accessing the route, you will get the following UI layout:
 </RootLayout>
 ```
 
-### (WIP)Loading
+### Loading (Experimental)
 
 In each directory under `routes/`, developers can create a `loading.tsx` file that exports a `<Loading>` component by default.
 

package/docs/en/guides/concept/entries.mdx

@@ -82,12 +82,13 @@ By default, Modern.js scans the files under `src/` before starting the project,
 
 :::
 
-Not all top-level directories under `src/` become project entries. The directory where the entry is located must meet one of the following four conditions:
+Not all top-level directories under `src/` become project entries. The directory where the entry is located must meet one of the following five conditions:
 
 1. Has a `routes/` directory.
 2. Has an `App.[jt]sx?` file.
 3. Has an `index.[jt]sx?` file.
 4. Has a `pages/` directory (compatible with Modern.js 1.0).
+5. Has an `entry.[jt]sx?` file.
 
 When the `src/` directory meets the entry requirements, Modern.js considers the current project as a single entry application.
 
@@ -139,8 +140,46 @@ export default () => {
 
 For more information, please refer to [Self-controlled Routing](/guides/basic-features/routes.html#self-controlled-routing).
 
+#### Custom Entry
+
+If there is an `entry.[jt]sx` file in the entry, developers need to call the `createRoot` and `render` functions in the `entry.[jt]sx` file to complete the project's entry logic.
+
+:::info
+Using this file requires enabling [source.enableCustomEntry](/configure/app/source/enable-custom-entry).
+:::
+
+```tsx
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+render(<ModernRoot />);
+```
+
+For example, if some other operations need to be performed before render is executed, it can be implemented in this way:
+
+```tsx
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+async function beforeRender() {
+   // todo
+}
+
+beforeRender().then(() => {
+  render(<ModernRoot />);
+});
+```
+
 #### Custom Bootstrap
 
+:::warning
+Soon to be deprecated, it is recommended to use a custom entry.
+:::
+
 If there is an `index.[jt]sx` file in the entry, and the file exports a function by default, Modern.js will pass the default `bootstrap` function as a parameter and use the exported function to replace the default `bootstrap`. This way, developers can customize how components are mounted to DOM nodes or add custom behavior before mounting. For example:
 
 ```tsx
@@ -152,44 +191,19 @@ export default (App: React.ComponentType, bootstrap: () => void) => {
 };
 ```
 
-At this point, the generated file content of Modern.js is as follows:
-
-```js
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import customBootstrap from '@_modern_js_src/index.tsx';
-import App from '@_modern_js_src/App';
-import { router, state } 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({
-    // plugin parameters for runtime...
-  })(App);
-  if (IS_BROWSER) {
-    customBootstrap(AppWrapper);
-  }
-  return AppWrapper;
-}
-
-AppWrapper = render();
-
-export default AppWrapper;
-```
-
 ### Build Mode Entry
 
-Build mode refers to the mode where the entry point of the page is not automatically generated by Modern.js, but is fully defined by the developers themselves.
+Build mode refers to not using the Runtime capabilities provided by Modern.js, but rather having the developer define the entry of the page completely on their own.
+
+When the entry directory contains `index.[jt]sx` (soon to be deprecated) and does not export a function via `export default`, or when there is an `entry.[jt]sx` file in the entry directory and the `@modern-js/runtime` dependency is not installed, the corresponding file will be identified as the entry module of webpack or Rspack.
 
-When there is an `index.[jt]sx` file in the entry directory and it is not exported as a function using `export default`, this type of file will be recognized as the entry module for webpack or Rspack.
+:::info
+Using the `entry.[jt]sx` file requires enabling [source.enableCustomEntry](/configure/app/source/enable-custom-entry).
+:::
 
 In this case, Modern.js will not generate the entry code automatically. Therefore, you need to manually mount the component to the DOM node, for example:
 
-```js title=src/index.jsx
+```js title=src/entry.tsx
 import React from 'react';
 import ReactDOM from 'react-dom';
 import App from './App';
@@ -197,9 +211,9 @@ import App from './App';
 ReactDOM.render(<App />, document.getElementById('root'));
 ```
 
-This approach is equivalent to enabling the [source.entries.disableMount](/configure/app/source/entries) option in Modern.js. When you use this approach, **you will not be able to use the runtime capabilities of the Modern.js framework**, such as the `runtime` configuration in the modern.config.js file will no longer take effect.
+This approach is equivalent to enabling the [source.entries.disableMount](/configure/app/source/entries) option in Modern.js. When you use this approach, **you will not be able to use the runtime capabilities of the Modern.js framework**, such as the `runtime` configuration in the `modern.config.js` file will no longer take effect.
 
-## Custom Entries
+## Custom Entries Config
 
 In some cases, you may need to customize the entry configuration instead of using the entry conventions provided by Modern.js.
 
@@ -232,4 +246,4 @@ export default defineConfig({
 });
 ```
 
-Note that when you enable `disableMount`, **you won't be able to use the runtime capabilities of the Modern.js framework**, such as the `runtime` configuration in the modern.config.ts file.
+Note that when you enable `disableMount`, **you won't be able to use the runtime capabilities of the Modern.js framework**, such as the `runtime` configuration in the `modern.config.ts` file.

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

@@ -56,7 +56,9 @@ export default defineConfig({
   server: {
     ssr: true,
   },
-  plugins: [appTools()],
+  plugins: [appTools({
+      bundler: 'webpack', // Set to 'experimental-rspack' to enable rspack ⚡️🦀
+  }),],
 });
 ```
 
@@ -91,15 +93,27 @@ $ pnpm run build
 
 > modern build
 
-info    Staring production build...
-ready   Client compiled in 50 ms
+  Modern.js Framework v2.55.0
+
+info    Starting production build...
+info    Type checker is enabled. It may take some time.
+ready   Client compiled in 6.19 s
 info    Production file sizes:
 
-  File                                      Size         Gzipped
-  dist/static/js/lib-react.09721b5c.js      152.6 kB     49.0 kB
-  dist/html/main/index.html                 5.8 kB       2.5 kB
-  dist/static/js/main.3568a38e.js           3.5 kB       1.4 kB
-  dist/static/css/main.03221f72.css         1.4 kB       741 B
+  File                                       Size        Gzipped
+  dist/routes-manifest.json                  0.74 kB     0.28 kB
+  dist/static/css/async/page.d7915515.css    1.4 kB      0.69 kB
+  dist/static/js/main.5ae469e7.js            3.0 kB      1.3 kB
+  dist/html/main/index.html                  6.0 kB      2.6 kB
+  dist/static/js/async/page.ddc8a4c1.js      19.2 kB     6.7 kB
+  dist/static/js/34.171fffdb.js              21.3 kB     7.1 kB
+  dist/static/js/lib-router.8995a55e.js      55.3 kB     18.1 kB
+  dist/static/js/lib-lodash.53ec3384.js      71.4 kB     24.8 kB
+  dist/static/js/lib-react.b5856db9.js       140.0 kB    45.2 kB
+  dist/static/js/lib-polyfill.86c452b3.js    213.3 kB    69.9 kB
+
+  Total size:  531.8 kB
+  Gzipped size:  176.7 kB
 ```
 
 By default, the build artifacts are generated in `dist/`, with the following directory structure:
@@ -127,6 +141,8 @@ $ pnpm run serve
 
 > modern serve
 
+  Modern.js Framework v2.55.0
+
 info    Starting production server...
 
   > Local:    http://localhost:8080/

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

@@ -420,13 +420,13 @@ export const myPlugin = (): CliPlugin<AppTools> => ({
   },
 });
 ```
+{/*
+### `checkEntryPoint`
 
-### `modifyEntryImports`
-
-- Function: Used for modifying or adding `import` statements in the generated entry files.
+- Function: Used for increasing entry types.
 - Execution stage: Executed before generating the entry files, triggered during the [`prepare`](#prepare) stage.
 - Hook model: `AsyncWaterfall`
-- Type: `AsyncWaterfall<{ imports: ImportStatement[]; entrypoint: Entrypoint; }>`
+- Type: `AsyncWaterfall<{ path: string; entry: false | string; }>`
 - Example:
 
 ```ts
@@ -435,57 +435,20 @@ import type { CliPlugin, AppTools } from '@modern-js/app-tools';
 export const myPlugin = (): CliPlugin<AppTools> => ({
   setup(api) {
     return {
-      modifyEntryImports({ entrypoint, imports }) {
-        // add `import React from 'React'`
-        imports.push({
-          value: 'react',
-          specifiers: [
-            {
-              imported: 'unmountComponentAtNode',
-            },
-          ],
-        });
-
-        return { entrypoint, imports };
-      },
+      checkEntryPoint({ path, entry }) {
+        return { path, entry: entry || isNewEntry(path) };
+      }
     };
   },
 });
 ```
 
-### `modifyEntryExport`
+### `modifyEntrypoints`
 
-- Function: used to modify the `export` statement in the generated entry file
+- Function: Used for modifying the entry information, for the newly added entries of the plugin, the corresponding entrypoint information can be modified through this hook.
 - Execution stage: Before the entry file is generated, the [`prepare`](#prepare) phase triggers
 - Hook model: `AsyncWaterfall`
-- Type: `AsyncWaterfall<{ entrypoint: Entrypoint; exportStatement: string; }>`
-- Example:
-
-```ts
-import type { CliPlugin, AppTools } from '@modern-js/app-tools';
-
-export const myPlugin = (): CliPlugin<AppTools> => ({
-  setup(api) {
-    return {
-      modifyEntryExport({ entrypoint, exportStatement }) {
-        return {
-          entrypoint,
-          exportStatement: [`export const foo = 'test'`, exportStatement].join(
-            '\n',
-          ),
-        };
-      },
-    };
-  },
-});
-```
-
-### `modifyEntryRuntimePlugins`
-
-- Function: Used for adding or modifying [Runtime plugins](#Runtime) in the generated entry files.
-- Execution stage: Executed before generating the entry files, triggered during the [`prepare`](#prepare) stage.
-- Hook model: `AsyncWaterfall`
-- Type: `AsyncWaterfall<{ entrypoint: Entrypoint; plugins: RuntimePlugin[]; }>`
+- Type: `AsyncWaterfall<{ entrypoints: Entrypoint[]; }>`
 - Example:
 
 ```ts
@@ -494,33 +457,23 @@ import type { CliPlugin, AppTools } from '@modern-js/app-tools';
 export const myPlugin = (): CliPlugin<AppTools> => ({
   setup(api) {
     return {
-      modifyEntryRuntimePlugins({ entrypoint, plugins }) {
-        const name = 'customPlugin';
-        const options = {
-          /** serializable content */
-        };
-
-        return {
-          plugins: [
-            ...plugins,
-            {
-              name,
-              options: JSON.stringify(options),
-            },
-          ],
-        };
+      async modifyEntrypoints({ entrypoints }) {
+        const newEntryPoints = entrypoints.map(entrypoint => {
+            ...
+        });
+        return { entrypoints: newEntryPoints };
       },
     };
   },
 });
 ```
 
-### `modifyEntryRenderFunction`
+### `generateEntryCode`
 
-- Function: Used for modifying the `render` function in the generated entry files.
-- Execution stage: Executed before generating the entry files, triggered during the [`prepare`](#prepare) stage.
+- Function: Used for modifying the generated entry file
+- Execution stage: After generating the entry file and before creating the builder.
 - Hook model: `AsyncWaterfall`
-- Type: `AsyncWaterfall<{ entrypoint: Entrypoint; code: string; }>`
+- Type: `AsyncWorkflow<{ entrypoints: Entrypoint[] }, void>`
 - Example:
 
 ```ts
@@ -529,18 +482,18 @@ import type { CliPlugin, AppTools } from '@modern-js/app-tools';
 export const myPlugin = (): CliPlugin<AppTools> => ({
   setup(api) {
     return {
-      modifyEntryRenderFunction({ entrypoint, code }) {
-        const customRender = `/** render function body */`;
-        return {
-          entrypoint,
-          code: customRender,
-        };
+      async generateEntryCode({ entrypoints }) {
+        await Promise.all(
+            entrypoints.map(async entrypoint => {
+               ...
+            })
+          );
       },
     };
   },
 });
 ```
-
+*/}
 ### `modifyFileSystemRoutes`
 
 - Function: Used for modifying the content of the generated front-end page routing files, which must be serializable.
@@ -608,32 +561,6 @@ export const myPlugin = (): CliPlugin<AppTools> => ({
 });
 ```
 
-### `modifyAsyncEntry`
-
-- Function: Used for modifying the asynchronous module that wraps the entry file, see [source.enableAsyncEntry](/configure/app/source/enable-async-entry).
-- Execution stage: Executed before generating the entry files, triggered during the [`prepare`](#prepare) stage.
-- Hook model: `AsyncWaterfall`
-- Type: `AsyncWaterfall<{ entrypoint: Entrypoint; code: string; }>`
-- Example:
-
-```ts
-import type { CliPlugin, AppTools } from '@modern-js/app-tools';
-
-export const myPlugin = (): CliPlugin<AppTools> => ({
-  setup(api) {
-    return {
-      modifyAsyncEntry({ entrypoint, code }) {
-        const customCode = `console.log('hello');`;
-        return {
-          entrypoint,
-          code: `${customCode}${code}`,
-        };
-      },
-    };
-  },
-});
-```
-
 ### `htmlPartials`
 
 - Function: Used for customizing the generated HTML page template.
@@ -780,7 +707,7 @@ export const myPlugin = (): Plugin => ({
 - Function: Modifies the components that need to be rendered.
 - Execution stage: Rendering (SSR/CSR).
 - Hook model: `Pipeline`
-- Type: `Pipeline<{ App: React.ComponentType<any>; }, React.ComponentType<any>>`
+- Type: `Pipeline<{ App: React.ComponentType<any>;config: Record<string, any>; },React.ComponentType<any>>`
 - Example:
 
 :::note
@@ -790,13 +717,12 @@ When using the hoc hook, you need to copy the static properties of the original
 ```ts
 import { createContext } from 'react';
 import type { Plugin } from '@modern-js/runtime';
-import hoistNonReactStatics from 'hoist-non-react-statics';
 
 export const myPlugin = (): Plugin => ({
   setup(api) {
     const FooContext = createContext('');
     return {
-      hoc({ App }, next) {
+      hoc({ App, config }, next) {
         const AppWrapper = (props: any) => {
           return (
             <FooContext.Provider store={'test'}>
@@ -805,84 +731,11 @@ export const myPlugin = (): Plugin => ({
           );
         };
         return next({
-          App: hoistNonReactStatics(AppWrapper, App),
+          App: AppWrapper,
+          config
         });
       },
     };
   },
 });
 ```
-
-{/* ### `provide`
-
-- Function: Modifies the Elements that need to be rendered.
-- Execution stage: Rendering (SSR/CSR).
-- Hook model: `Pipeline`
-- Type: `Pipeline<{ element: JSX.Element; props: AppProps; context: RuntimeContext }, JSX.Element>`
-- Example:
-
-```ts
-import { createContext } from 'react';
-import type { Plugin } from '@modern-js/runtime';
-
-export const myPlugin = (): Plugin => ({
-  setup(api) {
-    const FooContext = createContext('');
-
-    return {
-      provide: ({ element }) => <div>{element}</div>,
-    };
-  },
-});
-```
-
-### `client`
-
-- Function: Customizes the client-side rendering process.
-- Execution stage: Client-side rendering in the browser.
-- Hook model: `AsyncPipeline`
-- Type: `AsyncPipeline<{ App: React.ComponentType<any>; context?: RuntimeContext; rootElement: HTMLElement; }, void>`
-- Example:
-
-```ts
-import ReactDOM from 'react-dom';
-import type { Plugin } from '@modern-js/runtime';
-
-export const myPlugin = (): Plugin => ({
-  setup(api) {
-    return {
-      client: async ({ App, rootElement }) => {
-        ReactDOM.render(
-          React.createElement(App, { context: { foo: 'test' } }),
-          rootElement,
-        );
-      },
-    };
-  },
-});
-```
-
-### `server`
-
-- Function: Customize the server-side rendering process.
-- Execution Phase: SSR
-- Hook model: `AsyncPipeline`
-- Type: `AsyncPipeline<{ App: React.ComponentType<any>; context?: RuntimeContext; }, string>`
-- Example:
-
-```ts
-import ReactDomServer from 'react-dom/server';
-import type { Plugin } from '@modern-js/runtime';
-
-export const myPlugin = (): Plugin => ({
-  setup(api) {
-    return {
-      server({ App, context }) {
-        return ReactDomServer.renderToString(
-          React.createElement(App, { context: { foo: 'test' } }),
-        );
-      },
-    };
-  },
-});
-``` */}

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

@@ -0,0 +1,42 @@
+---
+title: entry.[tj]s
+sidebar_position: 4
+---
+# entry.[tj]s
+
+通常情况下[`routes/`](/apis/app/hooks/src/routes.html) 和 [`App.[tj]sx`](/apis/app/hooks/src/app) 钩子文件已经能满足我们的需求，当我们需要在组件渲染之前添加自定义行为或者完全接管 webpack 打包入口时，可以在 `src` 或者入口目录下放置 `entry.[tj]s`。 下面有分两种情况进行讨论：
+
+:::info
+使用该文件需要开启 [source.enableCustomEntry](/configure/app/source/enable-custom-entry)。
+:::
+
+## 在组件渲染前添加自定义行为
+
+在 `src/entry.[tj]s` 中这样实现：
+
+```js title=src/entry.tsx
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+async function beforeRender() {
+   // todo
+}
+
+beforeRender().then(() => {
+  render(<ModernRoot />);
+});
+```
+
+## 完全接管 webpack 入口
+
+当项目未安装 `@modern-js/runtime` 依赖时， `src/entry.[tj]sx?` 即为真正的 webpack 打包入口文件, 可以直接像使用 create-react-app 等脚手架一样组织代码：
+
+```js title=src/entry.jsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
+```

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

@@ -0,0 +1,52 @@
+---
+title: entry.server.[tj]sx
+sidebar_position: 5
+---
+
+# entry.server.[tj]sx
+
+当项目开启 `server.ssr` 时，Modern.js 生成一个默认的 Server-Side 入口。示例代码如下：
+
+```tsx title="entry.server.tsx"
+import {
+  renderString,
+  createRequestHandler,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest = async (request, ServerRoot, options) => {
+  const body = await renderString(request, <ServerRoot />, options);
+
+  return new Response(body, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```
+
+## 添加自定义行为
+
+如果用户需自定义 Server-Side Rendering 入口，可以在 `src/entry.server.ts`、`src/{entryName}/entry.server.ts` 中自定义 server 入口
+
+```tsx title="src/entry.server.tsx"
+import { renderString, createRequestHandler } from '@edenx/runtime/ssr/server';
+import type { HandleRequest } from '@edenx/runtime/ssr/server';
+
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
+  // do something before rendering
+  const body = await renderString(request, <ServerRoot />, options);
+
+  const newBody = body + '<div>Byte-Dance</div>';
+
+  return new Response(newBody, {
+    headers: {
+      'content-type': 'text/html; charset=UTF-8',
+      'x-custom-header': 'abc',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```

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

@@ -4,6 +4,10 @@ sidebar_position: 4
 ---
 # index.[tj]s
 
+:::warning
+即将废弃，推荐使用 [`entry.[tj]s`](/apis/app/hooks/src/entry)。
+:::
+
 应用使用自定义 `bootstrap` 时的入口标识。
 
 通常情况下 [`App.[tj]sx`](/apis/app/hooks/src/app) 钩子文件已经能满足我们的需求，当我们需要在 `bootstrap` 之前添加自定义行为或者完全接管 webpack 打包入口时，可以在 `src` 或者入口目录下放置 `index.[tj]s`。 下面有分两种情况进行讨论：

package/docs/zh/apis/app/runtime/core/bootstrap.mdx

@@ -3,6 +3,10 @@ title: bootstrap
 ---
 # bootstrap
 
+:::warning
+即将废弃，推荐使用 [`render`](/apis/app/runtime/core/render)。
+:::
+
 用于启动和挂载应用，通常情况下不做手动调用。只有在使用[自定义 Bootstrap](/guides/concept/entries#自定义-bootstrap) 时，才需要使用该 API。
 
 ## 使用姿势

package/docs/zh/apis/app/runtime/core/create-app.mdx

@@ -3,7 +3,11 @@ title: createApp
 ---
 # createApp
 
-用于创建自定义入口，定制运行时插件。只有在使用[自定义 App](/guides/concept/entries#自定义-app) 时，才需要使用该 API。
+:::warning
+即将废弃，推荐使用 [`createRoot`](/apis/app/runtime/core/create-root)。
+:::
+
+用于创建自定义入口，定制运行时插件。
 
 ## 使用姿势
 

package/docs/zh/apis/app/runtime/core/create-root.mdx

@@ -0,0 +1,22 @@
+---
+title: createRoot
+---
+# createRoot
+
+用于创建 Modern.js 提供的根组件，该根组件会自动注册 Runtime 插件，并完成 Runtime 插件初始化。
+
+## 使用姿势
+
+```ts
+import { createRoot } from '@modern-js/runtime/react';
+```
+
+## 函数签名
+
+```ts
+export function createRoot(UserApp?: React.ComponentType | null): React.ComponentType<any>;
+```
+
+### 参数
+
+- `UserApp` 可选参数，默认为 `App.tsx` 导出的组件