@modern-js/main-doc 2.54.5 → 2.55.0

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` 导出的组件

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

@@ -0,0 +1,43 @@
+---
+title: render
+---
+# render
+
+用于渲染项目组件。
+
+## 使用姿势
+
+```ts
+import { render } from '@modern-js/runtime/browser';
+
+render(<ModernRoot />);
+```
+
+## 函数签名
+
+```ts
+export function render(App: React.ReactElement, id?: HTMLElement | string): Promise<any>;
+```
+
+### 参数
+
+- `App`：通过 [`createRoot`](./create-root) 创建的 ReactElement 实例。
+- `id`：要挂载的 DOM 根元素 id，如 `"root"`。
+
+## 示例
+
+```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 />);
+});
+```
+

package/docs/zh/apis/app/runtime/ssr/renderStreaming.mdx

@@ -0,0 +1,69 @@
+---
+title: renderStreaming
+---
+
+# renderStreaming
+
+用于 React v18+ Streaming SSR 渲染出可读流, 配合 `createRequestHandler` 使用
+
+## 使用
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderStreaming,
+  createRequestHandler,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest = async (request, ServerRoot, options) => {
+  const stream = await renderStreaming(request, <ServerRoot />, options);
+
+  return new Response(stream, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```
+
+## 函数签名
+
+```ts
+export type RenderStreaming = (
+  request: Request,
+  serverRoot: React.ReactElement,
+  optinos: RenderOptions,
+) => Promise<ReadableStream>;
+```
+
+## 示例
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderStreaming,
+  createRequestHandler,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest = async (request, ServerRoot, options) => {
+  // do something before render
+  const stream = await renderStreaming(request, <ServerRoot />, options);
+
+  // docs: https://developer.mozilla.org/en-US/docs/Web/API/TransformStream
+  const transformStream = new TransformStream({
+    transform(chunk, controller) {
+      // do some transform
+    },
+  });
+
+  stream.pipeThrough(transformStream);
+
+  return new Response(transformStream.readable, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```

package/docs/zh/apis/app/runtime/ssr/renderString.mdx

@@ -0,0 +1,62 @@
+---
+title: renderString
+---
+
+# renderString
+
+用于 React String SSR 渲染出字符串，配合 `createRequestHandler` 使用
+
+## 使用
+
+```tsx title="src/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);
+```
+
+## 函数签名
+
+```ts
+export type RenderString = (
+  request: Request,
+  serverRoot: React.ReactElement,
+  optinos: RenderOptions,
+) => Promise<string>;
+```
+
+## 示例
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderString,
+  createRequestHandler,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest = async (request, ServerRoot, options) => {
+  // do something before render
+  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',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```