From 1e571ef14487922fe559716e93607f74d052e190 Mon Sep 17 00:00:00 2001 From: killa Date: Sat, 30 May 2026 02:05:32 +0800 Subject: [PATCH] docs(bundler): document manifest loader fs runtime --- tools/egg-bundler/README.md | 3 ++- tools/egg-bundler/docs/output-structure.md | 20 +++++++++++--------- wiki/log.md | 6 ++++++ wiki/packages/core.md | 18 ++++++++++++++---- wiki/packages/egg-bundler.md | 12 +++++++----- 5 files changed, 40 insertions(+), 19 deletions(-) diff --git a/tools/egg-bundler/README.md b/tools/egg-bundler/README.md index cbe99026ba..eb5fc79eb5 100644 --- a/tools/egg-bundler/README.md +++ b/tools/egg-bundler/README.md @@ -101,7 +101,8 @@ node worker.js ``` The generated worker entry runs the app in Egg's single-process mode and serves -framework file discovery/module resolution from the inlined bundle map. +framework file discovery/module resolution from the inlined bundle map through +Egg's manifest-backed loader filesystem. See [output-structure.md](./docs/output-structure.md) for artifact layout, externals behavior, and current limitations. diff --git a/tools/egg-bundler/docs/output-structure.md b/tools/egg-bundler/docs/output-structure.md index 026c9cff1d..1a821fdca8 100644 --- a/tools/egg-bundler/docs/output-structure.md +++ b/tools/egg-bundler/docs/output-structure.md @@ -32,15 +32,17 @@ cd node worker.js ``` -The worker entry installs `ManifestStore.setBundleStore(...)` and -`globalThis.__EGG_BUNDLE_MODULE_LOADER__` before calling -`startEgg({ baseDir: outputDir, framework, mode: 'single' })`, so framework -specifier lookup is served by the already imported bundled framework module, -without adding framework path aliases. Runtime lookup keeps -the deploy output directory separate from the original app paths: the bundle map -is keyed by relKey, output-dir absolute paths, precomputed original app absolute -paths, and manifest `resolveCache` request aliases. Application code and plugins -may still use `fs` for resources such as config, views, or assets. +The worker entry builds a `ManifestStore` from the bundled startup manifest, +installs `ManifestStore.setBundleStore(...)` and +`globalThis.__EGG_BUNDLE_MODULE_LOADER__`, creates a `ManifestLoaderFS`, and +passes it to +`startEgg({ baseDir: outputDir, framework, mode: 'single', loaderFS })`. +Framework specifier lookup is served by the already imported bundled framework +module, without adding framework path aliases. Runtime lookup keeps the deploy +output directory separate from the original app paths: the bundle map is keyed +by relKey, output-dir absolute paths, precomputed original app absolute paths, +and manifest `resolveCache` request aliases. Application code and plugins may +still use `fs` for resources such as config, views, or assets. ## Runtime assets diff --git a/wiki/log.md b/wiki/log.md index cb4ae3398b..1916e1e936 100644 --- a/wiki/log.md +++ b/wiki/log.md @@ -2,6 +2,12 @@ Dates use the workspace-local Asia/Shanghai calendar date. +## [2026-05-30] package | document manifest-backed loader fs runtime + +- sources touched: `packages/core/src/loader/loader_fs.ts`, `packages/core/src/loader/egg_loader.ts`, `tools/egg-bundler/src/lib/EntryGenerator.ts`, `packages/egg/src/lib/start.ts` +- pages updated: `tools/egg-bundler/README.md`, `tools/egg-bundler/docs/output-structure.md`, `wiki/log.md`, `wiki/packages/core.md`, `wiki/packages/egg-bundler.md` +- note: Recorded that bundled workers now create `ManifestLoaderFS` from the bundled manifest and pass it to `startEgg`, letting loader file discovery and module loading resolve through the bundle map before falling back to the real filesystem. + ## [2026-05-10] package | extract shared LoaderFS package - sources touched: `packages/loader-fs/src/index.ts`, `packages/loader-fs/package.json`, `packages/core/src/index.ts`, `packages/core/src/loader/file_loader.ts`, `packages/core/src/loader/egg_loader.ts` diff --git a/wiki/packages/core.md b/wiki/packages/core.md index 36191710ad..a17899a42a 100644 --- a/wiki/packages/core.md +++ b/wiki/packages/core.md @@ -4,10 +4,11 @@ type: package summary: Loader, lifecycle, and application core primitives used by Egg runtime packages. source_files: - packages/core/src/index.ts + - packages/core/src/loader/loader_fs.ts - packages/core/src/loader/file_loader.ts - packages/core/src/loader/context_loader.ts - packages/core/src/loader/egg_loader.ts -updated_at: 2026-05-10 +updated_at: 2026-05-30 status: active --- @@ -20,11 +21,20 @@ support, lifecycle, and base context classes. ## LoaderFS `@eggjs/core` consumes and re-exports `LoaderFS` and `RealLoaderFS` from -`@eggjs/loader-fs`. The abstraction remains the minimal filesystem boundary for -loader-facing file access: `exists`, `stat`, `realpath`, `readJSON`, `glob`, and -`loadFile`, without trying to polyfill the full Node.js `fs` module. +`@eggjs/loader-fs`. It also exports `ManifestLoaderFS`, the bundled-runtime +implementation backed by an Egg startup manifest. The abstraction remains the +minimal filesystem boundary for loader-facing file access: `exists`, `stat`, +`realpath`, `readJSON`, `glob`, and `loadFile`, without trying to polyfill the +full Node.js `fs` module. `EggLoaderOptions`, `FileLoaderOptions`, and `ContextLoaderOptions` can carry a custom `loaderFS`. `EggLoader` passes its loader FS into `loadToApp()` and `loadToContext()` so later bundled loaders can replace file discovery and module loading without changing the public loader call sites. + +`ManifestLoaderFS` answers loader filesystem calls from +`ManifestStore.data.fileDiscovery` and `ManifestStore.data.resolveCache` before +falling back to `RealLoaderFS`. When the bundled module loader is installed on +`globalThis.__EGG_BUNDLE_MODULE_LOADER__`, manifest-backed `readJSON()` and +`loadFile()` can return modules from the bundle map instead of reading the +original source file from disk. diff --git a/wiki/packages/egg-bundler.md b/wiki/packages/egg-bundler.md index fd483e4373..e351b04e8d 100644 --- a/wiki/packages/egg-bundler.md +++ b/wiki/packages/egg-bundler.md @@ -9,7 +9,7 @@ source_files: - tools/egg-bundler/src/lib/ExternalsResolver.ts - tools/egg-bin/src/commands/bundle.ts - tools/egg-bundler/docs/output-structure.md -updated_at: 2026-05-06 +updated_at: 2026-05-30 status: active --- @@ -47,10 +47,12 @@ CommonJS artifact from an Egg application. not run. - The generated app runs in Egg single-process mode. Its worker entry treats the deploy output directory as the runtime Egg `baseDir`, passes the framework - specifier explicitly to `startEgg`, maps that specifier to the already bundled - framework module, and precomputes original app absolute aliases so bundled - module lookup can serve relKeys, output-dir absolute paths, original app - absolute paths, and manifest `resolveCache` request aliases. + specifier explicitly to `startEgg`, creates `ManifestLoaderFS` from the + bundled startup manifest, and passes that loader FS into Egg startup. + Framework lookup is mapped to the already bundled framework module, and + original app absolute aliases are precomputed so bundled module lookup can + serve relKeys, output-dir absolute paths, original app absolute paths, and + manifest `resolveCache` request aliases. - Explicit `externals.force` entries are external, and `ExternalsResolver` auto-detects root `peerDependencies`, root `optionalDependencies`, root dependency packages with native addons, root dependency packages whose optional