feat: add source.enableAsyncPreEntry for async entry

Author: 2heal1

.changeset/friendly-planes-help.md

@@ -0,0 +1,6 @@
+---
+'@modern-js/app-tools': minor
+'@modern-js/runtime': minor
+---
+
+feat: add `source.enableAsyncPreEntry` for async entry scenarios

packages/document/main-doc/docs/en/configure/app/source/enable-async-pre-entry.mdx

@@ -0,0 +1,27 @@
+---
+title: enableAsyncPreEntry
+---
+
+# source.enableAsyncPreEntry
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+This option only takes effect when `source.enableAsyncEntry` is enabled.
+
+When enabled, Modern.js injects the modules configured in `source.preEntry` at the top of the auto-generated entry file (`index.jsx`), so `preEntry` still runs before the real entry logic 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"
+export default defineConfig({
+  source: {
+    enableAsyncEntry: true,
+    enableAsyncPreEntry: true,
+    preEntry: ['./src/pre-a.ts', './src/pre-b.ts'],
+  },
+});
+```
+

packages/document/main-doc/docs/zh/configure/app/source/enable-async-pre-entry.mdx

@@ -0,0 +1,27 @@
+---
+title: enableAsyncPreEntry
+---
+
+# source.enableAsyncPreEntry
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+该配置仅在 `source.enableAsyncEntry` 开启时生效。
+
+开启后，Modern.js 会在自动生成的入口文件（`index.jsx`）最上方依次插入 `source.preEntry` 中配置的模块 import，确保异步入口场景下 `preEntry` 也会在真正的入口代码之前执行。
+
+同时，当 `source.enableAsyncEntry` 与 `source.enableAsyncPreEntry` 同时开启时，Modern.js 不会将 `source.preEntry` 传递给构建器配置，避免重复注入或注入到不期望的 entry 中。
+
+## 示例
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    enableAsyncEntry: true,
+    enableAsyncPreEntry: true,
+    preEntry: ['./src/pre-a.ts', './src/pre-b.ts'],
+  },
+});
+```
+

packages/runtime/plugin-runtime/src/cli/code.ts

@@ -1,3 +1,5 @@
+/// <reference types="node" />
+
 import path from 'path';
 import type {
   AppNormalizedConfig,
@@ -6,7 +8,7 @@ import type {
   AppToolsNormalizedConfig,
 } from '@modern-js/app-tools';
 import type { Entrypoint } from '@modern-js/types';
-import { fs } from '@modern-js/utils';
+import { fs, formatImportPath } from '@modern-js/utils';
 import {
   ENTRY_BOOTSTRAP_FILE_NAME,
   ENTRY_POINT_FILE_NAME,
@@ -45,15 +47,54 @@ function getSSRMode(
   }
 }
 
+const normalizePreEntry = (preEntry: unknown): string[] => {
+  if (!preEntry) {
+    return [];
+  }
+  if (Array.isArray(preEntry)) {
+    return preEntry.filter(
+      (v): v is string => typeof v === 'string' && v.length > 0,
+    );
+  }
+  if (typeof preEntry === 'string') {
+    return preEntry ? [preEntry] : [];
+  }
+  return [];
+};
+
+const resolvePreEntryImportPath = ({
+  preEntry,
+  appDirectory,
+  srcDirectory,
+  internalSrcAlias,
+}: {
+  preEntry: string;
+  appDirectory: string;
+  srcDirectory: string;
+  internalSrcAlias: string;
+}) => {
+  const absPath = path.isAbsolute(preEntry)
+    ? preEntry
+    : path.resolve(appDirectory, preEntry);
+
+  // Prefer importing via the internal src alias to keep imports shorter and stable.
+  if (absPath.startsWith(srcDirectory)) {
+    return formatImportPath(absPath.replace(srcDirectory, internalSrcAlias));
+  }
+  return formatImportPath(absPath);
+};
+
 export const generateCode = async (
   entrypoints: Entrypoint[],
   appContext: AppToolsContext<'shared'>,
   config: AppToolsNormalizedConfig,
   hooks: AppToolsFeatureHooks<'shared'>,
 ) => {
   const { mountId } = config.html;
-  const { enableAsyncEntry } = config.source;
+  const { enableAsyncEntry, enableAsyncPreEntry, preEntry } = config.source;
+  const shouldInjectAsyncPreEntry = !!enableAsyncEntry && !!enableAsyncPreEntry;
   const {
+    appDirectory,
     runtimeConfigFile,
     internalDirectory,
     internalSrcAlias,
@@ -85,8 +126,10 @@ export const generateCode = async (
             metaName,
             entryName,
             mountId,
-            urlPath: serverRoutes.find(route => route.entryName === entryName)
-              ?.urlPath,
+            urlPath: serverRoutes.find(
+              (route: { entryName: string; urlPath?: string }) =>
+                route.entryName === entryName,
+            )?.urlPath,
             isNestedRouter: entrypoint.nestedRoutesEntry,
           });
         } else {
@@ -104,6 +147,28 @@ export const generateCode = async (
           });
         }
 
+        // Only works with `enableAsyncEntry`:
+        // inject `source.preEntry` to the top of the generated entry file
+        // (`index.jsx`), so it runs before the real entry code even when the
+        // build entry is `bootstrap.jsx`.
+        if (shouldInjectAsyncPreEntry) {
+          const preEntries = normalizePreEntry(preEntry);
+          if (preEntries.length > 0) {
+            const injected = preEntries
+              .map(item => {
+                const importPath = resolvePreEntryImportPath({
+                  preEntry: item,
+                  appDirectory,
+                  srcDirectory,
+                  internalSrcAlias,
+                });
+                return `import '${importPath}';`;
+              })
+              .join('\n');
+            indexCode = `${injected}\n${indexCode}`;
+          }
+        }
+
         const indexFile = path.resolve(
           internalDirectory,
           `./${entryName}/${ENTRY_POINT_FILE_NAME}`,

packages/solutions/app-tools/src/builder/generator/createBuilderProviderConfig.ts

@@ -67,6 +67,13 @@ export function createBuilderProviderConfig<B extends Bundler>(
     },
   };
 
+  // Only works with `enableAsyncEntry`:
+  // when both are enabled, `preEntry` should be handled by Modern.js entry code
+  // generation (inject into `index.jsx`), not by builder.
+  if (config.source?.enableAsyncEntry && config.source?.enableAsyncPreEntry) {
+    delete (config.source as any).preEntry;
+  }
+
   modifyOutputConfig(config, appContext);
 
   return config as AppNormalizedConfig<B>;

packages/solutions/app-tools/src/config/default.ts

@@ -41,6 +41,7 @@ export function createDefaultConfig(
     mainEntryName: MAIN_ENTRY_NAME,
     enableAsyncEntry: false,
     enableCustomEntry: false,
+    enableAsyncPreEntry: false,
     disableDefaultEntries: false,
     entriesDir: './src',
     configDir: './config',

packages/solutions/app-tools/src/types/config/source.ts

@@ -27,6 +27,11 @@ export type Entries = Record<string, Entry>;
 
 export interface SourceUserConfig
   extends NonNullable<UniBuilderConfig['source']> {
+  /**
+   * Add code before each page entry. It will be executed before the page code.
+   * @default []
+   */
+  preEntry?: string | string[];
   /**
    * Used to configure custom page entries.
    */
@@ -47,6 +52,13 @@ export interface SourceUserConfig
    * @default false
    */
   enableCustomEntry?: boolean;
+  /**
+   * When enabled, framework will inject `source.preEntry` into the top of the
+   * auto-generated entry file (`index.jsx`) in async entry scenarios.
+   * This option only takes effect when `source.enableAsyncEntry` is enabled.
+   * @default false
+   */
+  enableAsyncPreEntry?: boolean;
   /**
    * Used to disable the functionality of automatically identifying page entry points based on directory structure.
    * @default false

tests/integration/ssr/fixtures/base-async-pre-entry/modern.config.ts

@@ -0,0 +1,14 @@
+import { applyBaseConfig } from '../../../../utils/applyBaseConfig';
+
+export default applyBaseConfig({
+  server: {
+    ssr: {
+      mode: 'string',
+    },
+  },
+  source: {
+    enableAsyncEntry: true,
+    enableAsyncPreEntry: true,
+    preEntry: ['./src/pre.ts'],
+  },
+});

tests/integration/ssr/fixtures/base-async-pre-entry/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "ssr-base-async-pre-entry-test",
+  "version": "2.66.0",
+  "private": true,
+  "scripts": {
+    "dev": "modern dev"
+  },
+  "dependencies": {
+    "@modern-js/runtime": "workspace:*",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
+  "devDependencies": {
+    "@modern-js/app-tools": "workspace:*",
+    "@modern-js/tsconfig": "workspace:*",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^5"
+  }
+}

tests/integration/ssr/fixtures/base-async-pre-entry/src/modern-app-env.d.ts

@@ -0,0 +1 @@
+/// <reference types='@modern-js/app-tools/types' />