feat(bundler): enable @eggjs/* packages to be bundled by turbopack

packages/core/src/loader/manifest.ts

@@ -53,7 +53,32 @@ export class ManifestStore {
    * Load and validate manifest from `.egg/manifest.json`.
    * Returns null if manifest doesn't exist or is invalid.
    */
+  /**
+   * Register a pre-built manifest store for bundled egg apps. When set,
+   * `ManifestStore.load()` returns this store unconditionally, bypassing
+   * disk reads and invalidation checks. The bundler-generated entry calls
+   * this at startup before creating the Application.
+   *
+   * Uses globalThis so that bundled and external copies of @eggjs/core
+   * share the same store instance.
+   */
+  static setBundleStore(store: ManifestStore | undefined): void {
+    (globalThis as any).__EGG_BUNDLE_STORE__ = store;
+  }
+
+  /**
+   * Return the registered bundle store, if any.
+   */
+  static getBundleStore(): ManifestStore | undefined {
+    return (globalThis as any).__EGG_BUNDLE_STORE__;
+  }
+
   static load(baseDir: string, serverEnv: string, serverScope: string): ManifestStore | null {
+    const bundleStore: ManifestStore | undefined = (globalThis as any).__EGG_BUNDLE_STORE__;
+    if (bundleStore) {
+      debug('load: returning registered bundle store');
+      return bundleStore;
+    }
     if (serverEnv === 'local' && process.env.EGG_MANIFEST !== 'true') {
       debug('skip manifest in local env (set EGG_MANIFEST=true to enable)');
       return null;
@@ -84,6 +109,20 @@ export class ManifestStore {
     return new ManifestStore(data, baseDir);
   }
 
+  /**
+   * Create a ManifestStore from pre-validated bundled data.
+   * Skips invalidation checks — the caller (bundler) is responsible for
+   * guaranteeing the data matches the shipped artifact.
+   */
+  static fromBundle(data: StartupManifest, baseDir: string): ManifestStore {
+    if (data.version !== MANIFEST_VERSION) {
+      throw new Error(
+        `[@eggjs/core] bundled manifest version mismatch: expected ${MANIFEST_VERSION}, got ${data.version}`,
+      );
+    }
+    return new ManifestStore(data, baseDir);
+  }
+
   /**
    * Create a collector-only ManifestStore (no cached data).
    * Used during normal startup to collect data for future manifest generation.

packages/egg/package.json

@@ -70,6 +70,7 @@
     "./lib/loader/AgentWorkerLoader": "./src/lib/loader/AgentWorkerLoader.ts",
     "./lib/loader/AppWorkerLoader": "./src/lib/loader/AppWorkerLoader.ts",
     "./lib/loader/EggApplicationLoader": "./src/lib/loader/EggApplicationLoader.ts",
+    "./lib/snapshot": "./src/lib/snapshot.ts",
     "./lib/start": "./src/lib/start.ts",
     "./lib/types": "./src/lib/types.ts",
     "./lib/types.plugin": "./src/lib/types.plugin.ts",
@@ -125,6 +126,7 @@
       "./lib/loader/AgentWorkerLoader": "./dist/lib/loader/AgentWorkerLoader.js",
       "./lib/loader/AppWorkerLoader": "./dist/lib/loader/AppWorkerLoader.js",
       "./lib/loader/EggApplicationLoader": "./dist/lib/loader/EggApplicationLoader.js",
+      "./lib/snapshot": "./dist/lib/snapshot.js",
       "./lib/start": "./dist/lib/start.js",
       "./lib/types": "./dist/lib/types.js",
       "./lib/types.plugin": "./dist/lib/types.plugin.js",

packages/utils/src/import.ts

@@ -376,8 +376,6 @@ export function importResolve(filepath: string, options?: ImportResolveOptions):
  */
 export type SnapshotModuleLoader = (resolvedPath: string) => any;
 
-let _snapshotModuleLoader: SnapshotModuleLoader | undefined;
-
 /**
  * Register a snapshot module loader that intercepts `importModule()` calls.
  *
@@ -388,15 +386,46 @@ let _snapshotModuleLoader: SnapshotModuleLoader | undefined;
  *
  * Also sets `isESM = false` because the snapshot bundle is CJS and
  * esbuild's `import.meta` polyfill causes incorrect ESM detection.
+ *
+ * Uses globalThis so that bundled and external copies share the same loader.
  */
 export function setSnapshotModuleLoader(loader: SnapshotModuleLoader): void {
-  _snapshotModuleLoader = loader;
+  (globalThis as any).__EGG_SNAPSHOT_MODULE_LOADER__ = loader;
   isESM = false;
 }
 
+/**
+ * Module loader for bundled egg apps. Called with the raw `importModule()`
+ * filepath (posix-normalized) before `importResolve`, so bundled apps can
+ * serve modules that no longer exist on disk. Return `undefined` to fall
+ * through to the standard import path.
+ */
+export type BundleModuleLoader = (filepath: string) => unknown;
+
+/**
+ * Register a bundle module loader. Uses globalThis so that bundled and
+ * external copies of @eggjs/utils share the same loader.
+ */
+export function setBundleModuleLoader(loader: BundleModuleLoader | undefined): void {
+  (globalThis as any).__EGG_BUNDLE_MODULE_LOADER__ = loader;
+  if (loader) isESM = false;
+}
+
 export async function importModule(filepath: string, options?: ImportModuleOptions): Promise<any> {
+  const _bundleModuleLoader: BundleModuleLoader | undefined = (globalThis as any).__EGG_BUNDLE_MODULE_LOADER__;
+  if (_bundleModuleLoader) {
+    const hit = _bundleModuleLoader(filepath.replaceAll('\\', '/'));
+    if (hit !== undefined) {
+      let obj = hit as any;
+      if (obj?.default?.__esModule === true && 'default' in obj.default) obj = obj.default;
+      if (options?.importDefaultOnly && obj && typeof obj === 'object' && 'default' in obj) obj = obj.default;
+      return obj;
+    }
+  }
+
   const moduleFilePath = importResolve(filepath, options);
 
+  const _snapshotModuleLoader: SnapshotModuleLoader | undefined = (globalThis as any).__EGG_SNAPSHOT_MODULE_LOADER__;
   if (_snapshotModuleLoader) {
     let obj = _snapshotModuleLoader(moduleFilePath);
     if (obj && typeof obj === 'object' && obj.default?.__esModule === true && obj.default && 'default' in obj.default) {

packages/utils/test/__snapshots__/index.test.ts.snap

@@ -19,6 +19,7 @@ exports[`test/index.test.ts > export all > should keep checking 1`] = `
   "importResolve",
   "isESM",
   "isSupportTypeScript",
+  "setBundleModuleLoader",
   "setSnapshotModuleLoader",
 ]
 `;

packages/utils/test/bundle-import.test.ts

@@ -0,0 +1,63 @@
+import { strict as assert } from 'node:assert';
+
+import { afterEach, describe, it } from 'vitest';
+
+import { importModule, setBundleModuleLoader } from '../src/import.ts';
+import { getFilepath } from './helper.ts';
+
+describe('test/bundle-import.test.ts', () => {
+  afterEach(() => {
+    setBundleModuleLoader(undefined);
+  });
+
+  it('returns the real module when no bundle loader is registered', async () => {
+    const result = await importModule(getFilepath('esm'));
+    assert.ok(result);
+    assert.equal(typeof result, 'object');
+  });
+
+  it('intercepts importModule with the registered loader', async () => {
+    const seen: string[] = [];
+    const fakeModule = { default: { hello: 'bundle' }, other: 'stuff' };
+    setBundleModuleLoader((p) => {
+      seen.push(p);
+      if (p.endsWith('/fixtures/esm')) return fakeModule;
+    });
+
+    const result = await importModule(getFilepath('esm'));
+    assert.deepEqual(result, fakeModule);
+    assert.ok(seen.some((p) => p.endsWith('/fixtures/esm')));
+  });
+
+  it('honors importDefaultOnly when the bundle hit has a default key', async () => {
+    setBundleModuleLoader(() => ({ default: { greet: 'hi' }, other: 'x' }));
+
+    const result = await importModule(getFilepath('esm'), { importDefaultOnly: true });
+    assert.deepEqual(result, { greet: 'hi' });
+  });
+
+  it('unwraps __esModule double-default shape', async () => {
+    setBundleModuleLoader(() => ({
+      default: { __esModule: true, default: { fn: 'bundled' } },
+    }));
+
+    const result = await importModule(getFilepath('esm'));
+    assert.equal(result.__esModule, true);
+    assert.deepEqual(result.default, { fn: 'bundled' });
+  });
+
+  it('falls through to normal import when loader returns undefined', async () => {
+    setBundleModuleLoader(() => undefined);
+
+    const result = await importModule(getFilepath('esm'));
+    assert.ok(result);
+  });
+
+  it('short-circuits importResolve so bundled paths need not exist on disk', async () => {
+    const fakeModule = { virtual: true };
+    setBundleModuleLoader((p) => (p === 'virtual/not-on-disk' ? fakeModule : undefined));
+
+    const result = await importModule('virtual/not-on-disk');
+    assert.deepEqual(result, fakeModule);
+  });
+});

plugins/development/package.json

@@ -29,6 +29,7 @@
     "./agent": "./src/agent.ts",
     "./app": "./src/app.ts",
     "./app/middleware/egg_loader_trace": "./src/app/middleware/egg_loader_trace.ts",
+    "./app/middleware/loader_trace_template": "./src/app/middleware/loader_trace_template.ts",
     "./config/config.default": "./src/config/config.default.ts",
     "./types": "./src/types.ts",
     "./utils": "./src/utils.ts",
@@ -41,6 +42,7 @@
       "./agent": "./dist/agent.js",
       "./app": "./dist/app.js",
       "./app/middleware/egg_loader_trace": "./dist/app/middleware/egg_loader_trace.js",
+      "./app/middleware/loader_trace_template": "./dist/app/middleware/loader_trace_template.js",
       "./config/config.default": "./dist/config/config.default.js",
       "./types": "./dist/types.js",
       "./utils": "./dist/utils.js",

plugins/development/src/app/middleware/egg_loader_trace.ts

@@ -5,16 +5,15 @@ import type { Application, MiddlewareFunc } from 'egg';
 import { readJSON } from 'utility';
 
 import { isTimingFile } from '../../utils.ts';
+import { LOADER_TRACE_TEMPLATE } from './loader_trace_template.ts';
 
 export default function createEggLoaderTraceMiddleware(_options: unknown, app: Application): MiddlewareFunc {
   return async (ctx, next) => {
     if (ctx.path !== '/__loader_trace__') {
       return await next();
     }
-    const templatePath = path.join(import.meta.dirname, 'loader_trace.html');
-    const template = await fs.readFile(templatePath, 'utf8');
     const data = await loadTimingData(app);
-    ctx.body = template.replace('{{placeholder}}', JSON.stringify(data));
+    ctx.body = LOADER_TRACE_TEMPLATE.replace('{{placeholder}}', JSON.stringify(data));
   };
 }
 

plugins/development/src/app/middleware/loader_trace_template.ts

@@ -0,0 +1,51 @@
+/** Loader trace visualization template - inlined from loader_trace.html */
+export const LOADER_TRACE_TEMPLATE = `<!doctype html>
+<html lang="en">
+  <head>
+    <title></title>
+  </head>
+  <body>
+    <div id="mountNode"></div>
+    <script src="https://gw.alipayobjects.com/os/antv/assets/g2/3.0.9/g2.min.js"></script>
+    <script>
+      var data = {{placeholder}};
+
+      const chart = new G2.Chart({
+        container: 'mountNode', // 指定图表容器 ID
+        height: data.length * 22, // 指定图表高度
+        forceFit: true,
+        padding: 'auto',
+      });
+
+      // Step 2: 载入数据源
+      chart.source(data, {
+        range: {
+          type: 'time',
+          mask: 'HH:mm:ss',
+          nice: true,
+        },
+      });
+      chart
+        .coord()
+        .transpose()
+        .scale(1, -1);
+
+      chart.legend({ position: 'top' });
+
+      chart.tooltip({
+        showTitle: false,
+        itemTpl: '<li>{duration}ms: {name} </li>'
+      });
+
+      chart
+        .interval()
+        .position('title*range')
+        .color('type')
+        .tooltip('name*duration', (name, duration) => ({ name, duration }))
+        .size(5);
+
+      chart.render();
+    </script>
+  </body>
+</html>
+`;

plugins/onerror/package.json

@@ -28,6 +28,7 @@
     "./app": "./src/app.ts",
     "./config/config.default": "./src/config/config.default.ts",
     "./lib/error_view": "./src/lib/error_view.ts",
+    "./lib/onerror_page": "./src/lib/onerror_page.ts",
     "./lib/utils": "./src/lib/utils.ts",
     "./types": "./src/types.ts",
     "./package.json": "./package.json"
@@ -40,6 +41,7 @@
       "./app": "./dist/app.js",
       "./config/config.default": "./dist/config/config.default.js",
       "./lib/error_view": "./dist/lib/error_view.js",
+      "./lib/onerror_page": "./dist/lib/onerror_page.js",
       "./lib/utils": "./dist/lib/utils.js",
       "./types": "./dist/types.js",
       "./package.json": "./package.json"

plugins/onerror/src/app.ts

@@ -6,6 +6,7 @@ import { onerror, type OnerrorOptions, type OnerrorError } from 'koa-onerror';
 
 import type { OnerrorConfig } from './config/config.default.ts';
 import { ErrorView } from './lib/error_view.ts';
+import { ONERROR_PAGE_TEMPLATE } from './lib/onerror_page.ts';
 import { isProd, detectStatus, detectErrorMessage, accepts } from './lib/utils.ts';
 
 export interface OnerrorErrorWithCode extends OnerrorError {
@@ -23,7 +24,7 @@ export default class Boot implements ILifecycleBoot {
   async didLoad(): Promise<void> {
     // logging error
     const config = this.app.config.onerror;
-    const viewTemplate = fs.readFileSync(config.templatePath, 'utf8');
+    const viewTemplate = config.templatePath ? fs.readFileSync(config.templatePath, 'utf8') : ONERROR_PAGE_TEMPLATE;
     const app = this.app;
     app.on('error', (err, ctx) => {
       if (!ctx) {

plugins/onerror/src/config/config.default.ts

@@ -1,5 +1,3 @@
-import path from 'node:path';
-
 import type { Context } from 'egg';
 import type { OnerrorError, OnerrorOptions } from 'koa-onerror';
 
@@ -20,7 +18,9 @@ export interface OnerrorConfig extends OnerrorOptions {
    */
   appErrorFilter?: (err: OnerrorError, ctx: Context) => boolean;
   /**
-   * default template path
+   * Custom template path. If empty, uses the built-in error page template.
+   *
+   * Default: `''`
    */
   templatePath: string;
 }
@@ -29,6 +29,6 @@ export default {
   onerror: {
     errorPageUrl: '',
     appErrorFilter: undefined,
-    templatePath: path.join(import.meta.dirname, '../lib/onerror_page.mustache.html'),
+    templatePath: '',
   } as OnerrorConfig,
 };