@modern-js/main-doc 2.70.7 → 2.71.0

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

@@ -16,8 +16,9 @@ import {
   renderString,
   createRequestHandler,
 } from '@modern-js/runtime/ssr/server';
+import type { HandleRequest } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   const body = await renderString(request, <ServerRoot />, options);
 
   return new Response(body, {

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

@@ -13,8 +13,9 @@ import {
   renderStreaming,
   createRequestHandler,
 } from '@modern-js/runtime/ssr/server';
+import type { HandleRequest } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   const stream = await renderStreaming(request, <ServerRoot />, options);
 
   return new Response(stream, {
@@ -44,8 +45,9 @@ import {
   renderStreaming,
   createRequestHandler,
 } from '@modern-js/runtime/ssr/server';
+import type { HandleRequest } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   // do something before render
   const stream = await renderStreaming(request, <ServerRoot />, options);
 

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

@@ -13,8 +13,9 @@ import {
   renderString,
   createRequestHandler,
 } from '@modern-js/runtime/ssr/server';
+import type { HandleRequest } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   const body = await renderString(request, <ServerRoot />, options);
 
   return new Response(body, {
@@ -44,8 +45,9 @@ import {
   renderString,
   createRequestHandler,
 } from '@modern-js/runtime/ssr/server';
+import type { HandleRequest } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   // do something before render
   const body = await renderString(request, <ServerRoot />, options);
 

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

@@ -13,8 +13,9 @@ import {
   renderString,
   createRequestHandler,
 } from '@modern-js/runtime/ssr/server';
+import type { HandleRequest } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   const body = await renderString(request, <ServerRoot />, options);
 
   return new Response(body, {

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

@@ -0,0 +1,30 @@
+---
+title: enableAsyncPreEntry
+---
+
+# source.enableAsyncPreEntry
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+When enabled, Modern.js will inject the modules configured in `source.preEntry` to the top of the auto-generated entry file (`index.jsx`) in order.
+
+This option only takes effect when `source.enableAsyncEntry` is enabled. If async entry is not enabled, this behavior will be skipped and the original builder-side `source.preEntry` injection remains unchanged.
+
+This option is mainly designed to work with `source.enableAsyncEntry`: when async entry is enabled, the final build entry becomes `bootstrap.jsx`, and the builder-side `source.preEntry` may not be injected into the real entry code. With `source.enableAsyncPreEntry` enabled, `preEntry` will be injected into `index.jsx` (the real entry code), so it also works in async entry scenarios.
+
+Meanwhile, when both `source.enableAsyncEntry` and `source.enableAsyncPreEntry` are enabled, Modern.js will not pass `source.preEntry` into builder config to avoid duplicate injection or injection into an unexpected entry.
+
+## Example
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    enableAsyncEntry: true,
+    enableAsyncPreEntry: true,
+    preEntry: ['./src/pre-a.ts', './src/pre-b.ts'],
+  },
+});
+```

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

@@ -16,8 +16,9 @@ import {
   renderString,
   createRequestHandler,
 } from '@modern-js/runtime/ssr/server';
+import type { HandleRequest } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   const body = await renderString(request, <ServerRoot />, options);
 
   return new Response(body, {

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

@@ -13,8 +13,9 @@ import {
   renderStreaming,
   createRequestHandler,
 } from '@modern-js/runtime/ssr/server';
+import type { HandleRequest } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   const stream = await renderStreaming(request, <ServerRoot />, options);
 
   return new Response(stream, {
@@ -44,8 +45,9 @@ import {
   renderStreaming,
   createRequestHandler,
 } from '@modern-js/runtime/ssr/server';
+import type { HandleRequest } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   // do something before render
   const stream = await renderStreaming(request, <ServerRoot />, options);
 

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

@@ -13,8 +13,9 @@ import {
   renderString,
   createRequestHandler,
 } from '@modern-js/runtime/ssr/server';
+import type { HandleRequest } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   const body = await renderString(request, <ServerRoot />, options);
 
   return new Response(body, {
@@ -44,8 +45,9 @@ import {
   renderString,
   createRequestHandler,
 } from '@modern-js/runtime/ssr/server';
+import type { HandleRequest } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   // do something before render
   const body = await renderString(request, <ServerRoot />, options);
 

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

@@ -13,8 +13,9 @@ import {
   renderString,
   createRequestHandler,
 } from '@modern-js/runtime/ssr/server';
+import type { HandleRequest } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   const body = await renderString(request, <ServerRoot />, options);
 
   return new Response(body, {

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

@@ -0,0 +1,77 @@
+---
+title: enableAsyncPreEntry
+---
+
+# source.enableAsyncPreEntry
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+开启后，Modern.js 会在自动生成的入口文件（`index.jsx`）最上方依次插入 `source.preEntry` 中配置的模块 import。
+
+该配置仅在 `source.enableAsyncEntry` 开启时生效；如果未开启异步入口，则不会启用该行为（并保持 `source.preEntry` 原有的构建器注入逻辑不受影响）。
+
+该配置主要用于配合 `source.enableAsyncEntry` 使用：当启用异步入口时，最终的构建 entry 会变为 `bootstrap.jsx`，这会导致构建器侧的 `source.preEntry` 不一定能注入到真正的入口代码中。开启 `source.enableAsyncPreEntry` 后，`preEntry` 会注入到 `index.jsx`（真正的入口代码）顶部，从而保证在异步入口场景下也能生效。
+
+同时，当 `source.enableAsyncPreEntry` 开启时，Modern.js 不会将 `source.preEntry` 传递给构建器配置，避免重复注入或注入到不期望的 entry 中。
+
+## 示例
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    enableAsyncEntry: true,
+    enableAsyncPreEntry: true,
+    preEntry: ['./src/pre-a.ts', './src/pre-b.ts'],
+  },
+});
+```
+
+## 编译效果
+
+在开启 `source.enableAsyncEntry` 后，Modern.js 会为每个入口生成一个异步边界文件 `bootstrap.jsx`，并由它去动态加载真正的入口代码 `index.jsx`。
+
+当同时开启 `source.enableAsyncPreEntry` 时，Modern.js 会把 `source.preEntry` 以 `import` 的形式注入到 **`index.jsx` 的最顶部**（而不是注入到 `bootstrap.jsx`），保证异步入口场景下 `preEntry` 一定会在入口代码之前执行。
+
+### 生成文件结构
+
+以单入口 `main` 为例，生成的文件结构大致如下（位于 `node_modules/.modern-js/main/`）：
+
+```bash
+node_modules
+  └─ .modern-js
+     └─ main
+        ├─ bootstrap.jsx        # 最终用于构建的 entry（异步边界）
+        ├─ index.jsx            # 真正的入口代码（会被注入 preEntry import）
+        ├─ register.js
+        ├─ runtime-register.js
+        └─ runtime-global-context.js
+```
+
+### bootstrap.jsx
+
+`bootstrap.jsx` 的核心逻辑是通过 dynamic import 加载 `index.jsx`：
+
+```js title="node_modules/.modern-js/main/bootstrap.jsx"
+import(/* webpackChunkName: "async-main" */ './index');
+```
+
+### index.jsx（会注入 preEntry）
+
+开启 `source.enableAsyncPreEntry` 后，`index.jsx` 文件的最上方会被注入 `source.preEntry` 对应的 import，随后才是 Modern.js 生成的入口逻辑，例如：
+
+```js title="node_modules/.modern-js/main/index.jsx"
+import '@_modern_js_src/pre-a.ts';
+import '@_modern_js_src/pre-b.ts';
+
+import '@modern-js/runtime/registry/main';
+// ...后续为 Modern.js 自动生成的入口逻辑
+```
+
+其中 `@_modern_js_src` 是 Modern.js 内部用于指向项目 `src` 目录的别名（实际值会随项目 metaName 等信息变化）。
+
+### 与 builder 的关系
+
+当 `source.enableAsyncEntry` 与 `source.enableAsyncPreEntry` 同时开启时，Modern.js **不会再把 `source.preEntry` 传递给构建器配置**，避免构建器重复注入或注入到不期望的 entry 中。

package/package.json

@@ -15,17 +15,17 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.70.7",
+  "version": "2.71.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.4.1",
-    "@modern-js/sandpack-react": "2.70.7"
+    "@modern-js/sandpack-react": "2.71.0"
   },
   "devDependencies": {
-    "@rsbuild/plugin-sass": "1.5.0",
+    "@rsbuild/plugin-sass": "1.5.2",
     "@shikijs/transformers": "^3.4.2",
     "@rspress/shared": "2.0.0-beta.16",
     "@rspress/plugin-llms": "2.0.0-beta.16",