@modern-js/main-doc 2.54.5 → 2.55.0

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

@@ -0,0 +1,47 @@
+---
+title: createRequestHandler
+---
+
+# createRequestHandler
+
+用于自定义 Server-Side Rendering 入口返回 requestHandler
+
+## 使用
+
+```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 HandleRequest = (
+  request: Request,
+  ServerRoot: React.ComponentType
+  options: HandleRequestOptions,
+) => Promise<Response>;
+
+export type RequestHandler = (
+  request: Request,
+  options: RequestHandlerOptions,
+) => Promise<Response>;
+
+export type CreateRequestHandler = (
+  handleRequest: HandleRequest,
+) => Promise<RequestHandler>;
+```

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

@@ -7,13 +7,17 @@ title: Middleware
 用于拓展 Modern.js 内置的 Web Server，与 [Hook](/apis/app/runtime/web-server/hook) 不同的是，Middleware 可以直接操作 Node 原生的请求、响应对象，并且可以使用框架拓展。
 
 :::note
+
 在下一个大版本，Modern.js 将会使用新 Middleware 来替代该写法。
 
 推荐使用 [UnstableMiddleware](/apis/app/runtime/web-server/unstable_middleware) 处理页面请求。
+
 :::
 
 :::note
+
 更多内容可以查看[自定义 Web Server](/guides/advanced-features/web-server)。
+
 :::
 
 ## 使用姿势

package/docs/zh/components/debug-app.mdx

@@ -5,8 +5,9 @@ $ pnpm run dev
 
 > modern dev
 
-info    Starting dev server...
-ready   Client compiled in 50 ms
+  Modern.js Framework v2.55.0
+
+ready   Client compiled in 0.86 s
 
   > Local:    http://localhost:8080/
   > Network:  http://192.168.0.1:8080/

package/docs/zh/configure/app/dev/client.mdx

@@ -35,7 +35,7 @@ const defaultConfig = {
   port: '',
   host: location.hostname,
   protocol: location.protocol === 'https:' ? 'wss' : 'ws',
-  overlay: true,
+  overlay: false,
 };
 ```
 

package/docs/zh/configure/app/output/ssg.mdx

@@ -9,6 +9,10 @@ sidebar_label: ssg
 
 开启**自控式路由**或**约定式路由** SSG 功能的配置。
 
+:::info 开启 SSG 功能
+此配置需要在开启 SSG 功能情况下才会生效。请阅读 [静态站点生成](/guides/advanced-features/ssg) 文档了解如何开启 SSG 功能。
+:::
+
 :::info 客户端路由
 相关内容可以查看[路由方案](/guides/basic-features/routes)。
 

package/docs/zh/configure/app/source/enable-async-entry.mdx

@@ -35,15 +35,15 @@ export default defineConfig({
 node_modules
   └─ .modern-js
      └─ main
-        ├─ bootstrap.jsx  # 真正的入口代码
-        ├─ index.js      # 异步入口文件（asynchronous boundary）
+        ├─ bootstrap.jsx  # 异步入口文件（asynchronous boundary）
+        ├─ index.js      # 真正的入口代码
         └─ index.html
 ```
 
-其中 `index.js` 的内容如下：
+其中 `bootstrap.js` 的内容如下：
 
 ```js
-import('./bootstrap.jsx');
+import('./index.jsx');
 ```
 
 此时，就可以在当前页面中消费任意的远程模块了。

package/docs/zh/configure/app/source/enable-custom-entry.mdx

@@ -0,0 +1,41 @@
+---
+sidebar_label: enableCustomEntry
+---
+
+# source.enableCustomEntry
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+该选项用于使用 Modern.js 自定义入口场景。
+
+开启此选项后，Modern.js 将使用 `src/entry.[jt]sx` 文件作为项目的入口， 具体使用姿势可参考[页面入口](/guides/concept/entries.html)。
+
+## 示例
+
+首先，在配置文件中开启此选项：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    enableCustomEntry: true,
+  },
+});
+```
+
+创建 `src/entry.tsx` 文件：
+
+```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/guides/advanced-features/ssr/cache.mdx

@@ -55,10 +55,10 @@ export interface CacheControl {
 ```ts
 export type CacheOptionProvider = (
   req: IncomingMessage,
-) => Promise<CacheControl> | CacheControl;
+) => Promise<CacheControl | false> | CacheControl | false;
 ```
 
-有时开发者需要通过 req 来自定义缓存 key，可以配置为函数的形式进行处理, 例如以下代码：
+有时开发者需要通过 req 来自定义缓存 key，或者特定 url 时缓存不生效，可以配置为函数的形式进行处理, 例如以下代码：
 
 ```ts title="server/cache.ts"
 
@@ -69,6 +69,10 @@ const provider: CacheOptionProvider = (req) => {
 
   const key = computedKey(url, headers, ...);
 
+  if(url.includes('no-cache=1')) {
+    return false;
+  }
+
   return {
     maxAge: 500, // ms
     staleWhileRevalidate: 1000, // ms

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

@@ -81,12 +81,14 @@ import EntryMode from '@site-docs/components/entry-mode.mdx';
 
 :::
 
-并非 `src/` 下所有的一级目录都会成为项目入口, 入口所在目录必须满足以下四个条件之一：
+并非 `src/` 下所有的一级目录都会成为项目入口, 入口所在目录必须满足以下五个条件之一：
 
 1. 具有 `routes/` 目录。
 2. 具有 `App.[jt]sx?` 文件。
-3. 具有 `index.[jt]sx?` 文件。
-4. 具有 `pages/` 目录（兼容 Modern.js 1.0）。
+3. 具有 `entry.[jt]sx?` 文件 (需要开启 `source.enableCustomEntry` 使用)。
+4. 具有 `index.[jt]sx?` 文件（即将废弃）。
+5. 具有 `pages/` 目录（兼容 Modern.js 1.0）(即将废弃)。
+
 
 当 `src/` 目录满足入口特征时，Modern.js 会认为当前项目为单入口应用。
 
@@ -138,8 +140,47 @@ export default () => {
 
 详细内容可以参考[路由方案](/guides/basic-features/routes#自控式路由)。
 
+#### 自定义入口
+
+如果入口中存在 `entry.[jt]sx` 文件，需要开发者在 `entry.[jt]sx` 文件中调用 `createRoot` 和 `render` 函数，完成项目入口逻辑。
+
+:::info
+使用该文件需要开启 [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 />);
+
+```
+
+比如在 render 执行前，需要做一些其他操作，可以这样实现：
+
+```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 />);
+});
+```
+
 #### 自定义 Bootstrap
 
+:::warning
+即将废弃，推荐使用自定义入口
+:::
+
 如果入口中存在 `index.[jt]sx` 文件，并且当文件默认导出函数时，Modern.js 会将默认的 `bootstrap` 函数作为入参传入，并用导出的函数替代默认的 `bootstrap`，这样开发者可以自定义将组件挂载到 DOM 节点上，或在挂载前添加自定义行为。例如：
 
 ```tsx
@@ -151,47 +192,19 @@ export default (App: React.ComponentType, bootstrap: () => void) => {
 };
 ```
 
-此时，Modern.js 生成的文件内容如下：
-
-```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;
-let root = null;
-
-function render() {
-  AppWrapper = createApp({
-    // runtime 的插件参数...
-  })(App);
-  if (IS_BROWSER) {
-    customBootstrap(AppWrapper, () =>
-      bootstrap(AppWrapper, MOUNT_ID, root, ReactDOM),
-    );
-  }
-  return AppWrapper;
-}
-
-AppWrapper = render();
-
-export default AppWrapper;
-```
-
 ### 构建模式入口
 
-构建模式指的是不使用 Modern.js 自动生成的入口，而是完全由开发者自行定义页面的入口。
+构建模式指的是不使用 Modern.js 提供的 Runtime 能力，而是完全由开发者自行定义页面的入口。
+
+当入口目录中存在 `index.[jt]sx`(即将废弃) 并且没有通过 `export default` 导出函数或者入口目录存在 `entry.[jt]sx` 并且未安装 `@modern-js/runtime` 依赖时，对应文件就会被识别为 webpack 或 Rspack 的 entry 模块。
 
-当入口目录中存在 `index.[jt]sx`，并且没有通过 `export default` 导出函数时，这类文件就会被识别为 webpack 或 Rspack 的 entry 模块。
+:::info
+使用 `entry.[jt]sx` 文件需要开启 [source.enableCustomEntry](/configure/app/source/enable-custom-entry)。
+:::
 
 此时 Modern.js 不会自动生成入口代码，因此需要你自行将组件挂载到 DOM 节点上，例如:
 
-```js title=src/index.jsx
+```js title=src/entry.tsx
 import React from 'react';
 import ReactDOM from 'react-dom';
 import App from './App';
@@ -199,9 +212,9 @@ import App from './App';
 ReactDOM.render(<App />, document.getElementById('root'));
 ```
 
-这种方式等价于开启 Modern.js 的 [source.entries.disableMount](/configure/app/source/entries) 选项。当你使用这种方式时，**将无法使用 Modern.js 框架的运行时能力**，比如 modern.config.js 文件中的 `runtime` 配置将不会再生效。
+这种方式等价于开启 Modern.js 的 [source.entries.disableMount](/configure/app/source/entries) 选项。当你使用这种方式时，**将无法使用 Modern.js 框架的运行时能力**，比如 `modern.config.js` 文件中的 `runtime` 配置将不会再生效。
 
-## 自定义入口
+## 自定义入口配置
 
 在某些情况下，你可能需要自定义入口配置，而不是使用 Modern.js 提供的入口约定。
 
@@ -234,4 +247,4 @@ export default defineConfig({
 });
 ```
 
-注意，当你开启 `disableMount` 时，**将无法使用 Modern.js 框架的运行时能力**，比如 modern.config.ts 文件中的 `runtime` 配置将不会再生效。
+注意，当你开启 `disableMount` 时，**将无法使用 Modern.js 框架的运行时能力**，比如 `modern.config.ts` 文件中的 `runtime` 配置将不会再生效。

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

@@ -56,7 +56,11 @@ export default defineConfig({
   server: {
     ssr: true,
   },
-  plugins: [appTools()],
+  plugins: [
+    appTools({
+      bundler: 'webpack', // Set to 'experimental-rspack' to enable rspack ⚡️🦀
+    }),
+  ],
 });
 ```
 
@@ -91,15 +95,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
 ```
 
 构建产物默认生成到 `dist/`，目录结构如下：
@@ -125,9 +141,9 @@ dist
 ```bash
 $ pnpm run serve
 
-> modern serve
+  Modern.js Framework v2.55.0
 
-Starting production server...
+info    Starting production server...
 
   > Local:    http://localhost:8080/
   > Network:  http://192.168.0.1:8080/

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

@@ -421,12 +421,13 @@ export const myPlugin = (): CliPlugin<AppTools> => ({
 });
 ```
 
-### `modifyEntryImports`
+{/*
+### `checkEntryPoint`
 
-- 功能：用于修改、添加生成入口文件中的 `import` 语句
+- 功能：增加入口类型
 - 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
 - Hook 模型：`AsyncWaterfall`
-- 类型：`AsyncWaterfall<{ imports: ImportStatement[]; entrypoint: Entrypoint; }>`
+- 类型：`AsyncWaterfall<{ path: string; entry: false | string; }>`
 - 使用示例：
 
 ```ts
@@ -435,57 +436,20 @@ import type { CliPlugin, AppTools } from '@modern-js/app-tools';
 export const myPlugin = (): CliPlugin<AppTools> => ({
   setup(api) {
     return {
-      modifyEntryImports({ entrypoint, imports }) {
-        // 添加 `import React from 'React'`
-        imports.push({
-          value: 'react',
-          specifiers: [
-            {
-              imported: 'unmountComponentAtNode',
-            },
-          ],
-        });
-
-        return { entrypoint, imports };
-      },
-    };
-  },
-});
-```
-
-### `modifyEntryExport`
-
-- 功能：用于修改生成入口文件中的 `export` 语句
-- 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
-- Hook 模型：`AsyncWaterfall`
-- 类型：`AsyncWaterfall<{ entrypoint: Entrypoint; exportStatement: string; }>`
-- 使用示例：
-
-```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',
-          ),
-        };
+      checkEntryPoint({ path, entry }) {
+        return { path, entry: entry || isNewEntry(path) };
       },
     };
   },
 });
 ```
 
-### `modifyEntryRuntimePlugins`
+### `modifyEntrypoints`
 
-- 功能：用于添加、修改生成入口文件中的 [Runtime 插件](#Runtime)
+- 功能：用于修改入口信息，针对于插件新增的入口，可以通过该钩子修改对应的 entrypoint 信息
 - 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
 - Hook 模型：`AsyncWaterfall`
-- 类型：`AsyncWaterfall<{ entrypoint: Entrypoint; plugins: RuntimePlugin[]; }>`
+- 类型：`AsyncWaterfall<{ entrypoints: Entrypoint[]; }>`
 - 使用示例：
 
 ```ts
@@ -494,33 +458,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 = {
-          /** 可序列化的内容 */
-        };
-
-        return {
-          plugins: [
-            ...plugins,
-            {
-              name,
-              options: JSON.stringify(options),
-            },
-          ],
-        };
+      async modifyEntrypoints({ entrypoints }) {
+        const newEntryPoints = entrypoints.map(entrypoint => {
+            ...
+        });
+        return { entrypoints: newEntryPoints };
       },
     };
   },
 });
 ```
 
-### `modifyEntryRenderFunction`
+### `generateEntryCode`
 
-- 功能：用于修改生成入口文件中 `render` 函数
-- 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
+- 功能：用于修改生成的入口文件
+- 执行阶段：生成入口文件之后，创建 builder 之前
 - Hook 模型：`AsyncWaterfall`
-- 类型：`AsyncWaterfall<{ entrypoint: Entrypoint; code: string; }>`
+- 类型：`AsyncWorkflow<{ entrypoints: Entrypoint[] }, void>`
 - 使用示例：
 
 ```ts
@@ -529,18 +483,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`
 
 - 功能：用于修改生成前端页面路由文件中的内容，内容都是需要可序列化的
@@ -608,32 +562,6 @@ export const myPlugin = (): CliPlugin<AppTools> => ({
 });
 ```
 
-### `modifyAsyncEntry`
-
-- 功能：用于修改包裹入口文件的异步模块，参见 [source.enableAsyncEntry](/configure/app/source/enable-async-entry)
-- 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
-- Hook 模型：`AsyncWaterfall`
-- 类型：`AsyncWaterfall<{ entrypoint: Entrypoint; code: string; }>`
-- 使用示例：
-
-```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`
 
 - 功能：用于定制生成的 HTML 页面模版
@@ -782,7 +710,7 @@ export const myPlugin = (): Plugin => ({
 - 功能：修改需要渲染的组件
 - 执行阶段：渲染（SSR/CSR）
 - Hook 模型：`Pipeline`
-- 类型：`Pipeline<{ App: React.ComponentType<any>; }, React.ComponentType<any>>`
+- 类型：`Pipeline<{ App: React.ComponentType<any>;config: Record<string, any>; },React.ComponentType<any>>`
 - 使用示例：
 
 :::note
@@ -792,13 +720,12 @@ export const myPlugin = (): Plugin => ({
 ```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'}>
@@ -807,7 +734,8 @@ export const myPlugin = (): Plugin => ({
           );
         };
         return next({
-          App: hoistNonReactStatics(AppWrapper, App),
+          App: AppWrapper,
+          config
         });
       },
     };
@@ -815,76 +743,3 @@ export const myPlugin = (): Plugin => ({
 });
 ```
 
-{/* ### `provide`
-
-- 功能：修改需要渲染的 Element
-- 执行阶段：渲染（SSR/CSR）
-- Hook 模型：`Pipeline`
-- 类型：`Pipeline<{ element: JSX.Element; props: AppProps; context: RuntimeContext }, JSX.Element>`
-- 使用示例：
-
-```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`
-
-- 功能：定制客户端渲染流程
-- 执行阶段：在浏览器客户端渲染
-- Hook 模型：`AsyncPipeline`
-- 类型：`AsyncPipeline<{ App: React.ComponentType<any>; context?: RuntimeContext; rootElement: HTMLElement; }, void>`
-- 使用示例：
-
-```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`
-
-- 功能：定制服务器端渲染流程
-- 执行阶段：SSR
-- Hook 模型：`AsyncPipeline`
-- 类型：`AsyncPipeline<{ App: React.ComponentType<any>; context?: RuntimeContext; }, string>`
-- 使用示例：
-
-```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' } }),
-        );
-      },
-    };
-  },
-});
-```*/}