diff --git a/tools/egg-bundler/README.md b/tools/egg-bundler/README.md index cbe99026ba..4c19fcb552 100644 --- a/tools/egg-bundler/README.md +++ b/tools/egg-bundler/README.md @@ -100,8 +100,10 @@ cd dist-bundle 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. +The generated worker entry runs the app in Egg's single-process mode with a +manifest-backed loader filesystem, so framework file discovery and module +resolution are served from the inlined bundle map before falling back to the +real 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..402e51bf26 100644 --- a/tools/egg-bundler/docs/output-structure.md +++ b/tools/egg-bundler/docs/output-structure.md @@ -33,14 +33,17 @@ 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. +`globalThis.__EGG_BUNDLE_MODULE_LOADER__`, creates a `ManifestLoaderFS` from the +startup manifest, then calls +`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. Loader file discovery, JSON reads, +and module loading use the manifest-backed loader filesystem first and fall back +to the real filesystem when a path is outside the manifest. Application code and +plugins may still use `fs` for resources such as config, views, or assets. ## Runtime assets diff --git a/wiki/index.md b/wiki/index.md index a9449c7a06..fa41fb7939 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -20,7 +20,7 @@ Read this file before exploring raw sources. - [Core Package](./packages/core.md) - Loader, lifecycle, and application core primitives used by Egg runtime packages. - [Egg Bundler](./packages/egg-bundler.md) - Tooling package that bundles Egg applications and backs `egg-bin bundle`. -- [Loader FS Package](./packages/loader-fs.md) - Shared loader-facing filesystem boundary for Egg loaders and future bundled runtimes. +- [Loader FS Package](./packages/loader-fs.md) - Shared loader-facing filesystem boundary for Egg loaders and bundled runtimes. - [Onerror Plugin](./packages/onerror.md) - Default Egg error-handling plugin and configurable response negotiation layer. - [Typings Package](./packages/typings.md) - Shared TypeScript type surface for cross-package Egg typings. - [Utils Package](./packages/utils.md) - Shared utility package for module loading and bundled module-loader integration. diff --git a/wiki/log.md b/wiki/log.md index cb4ae3398b..93293cab82 100644 --- a/wiki/log.md +++ b/wiki/log.md @@ -2,6 +2,12 @@ Dates use the workspace-local Asia/Shanghai calendar date. +## [2026-06-02] package | sync manifest-backed loader FS docs + +- sources touched: `packages/core/src/loader/loader_fs.ts`, `packages/core/src/index.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`, `wiki/packages/loader-fs.md` +- note: Recorded that bundled workers now create `ManifestLoaderFS`, pass it into `startEgg()`, and serve loader discovery/module loading from manifest data 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..4af5b1583b 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-06-02 status: active --- @@ -20,11 +21,18 @@ 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`, and also exports `ManifestLoaderFS` from its manifest-aware +loader implementation. 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 +`loadToContext()` so bundled loaders can replace file discovery and module loading without changing the public loader call sites. + +`ManifestLoaderFS` adapts a `ManifestStore` into that loader boundary for +bundled runtimes. It answers `exists`, `stat`, `realpath`, and `glob` from +manifest `fileDiscovery` and `resolveCache` data, loads bundled modules through +`globalThis.__EGG_BUNDLE_MODULE_LOADER__`, and delegates to a fallback +`LoaderFS` for paths not covered by the manifest. diff --git a/wiki/packages/egg-bundler.md b/wiki/packages/egg-bundler.md index fd483e4373..8fb2c098ed 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-06-02 status: active --- @@ -32,7 +32,8 @@ CommonJS artifact from an Egg application. `/.egg/manifest.json`. 2. `ExternalsResolver` classifies packages that should stay external. 3. `EntryGenerator` writes a synthetic worker entry that installs the bundle - manifest/module loader before starting Egg. + manifest/module loader, creates a `ManifestLoaderFS`, and passes it into + `startEgg()`. 4. `PackRunner` invokes `@utoo/pack`. 5. `Bundler` writes `bundle-manifest.json` and returns absolute output paths. @@ -47,10 +48,11 @@ 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 and manifest-backed `loaderFS` 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. - 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 diff --git a/wiki/packages/loader-fs.md b/wiki/packages/loader-fs.md index 85120ebdde..0f977033e7 100644 --- a/wiki/packages/loader-fs.md +++ b/wiki/packages/loader-fs.md @@ -1,11 +1,11 @@ --- title: Loader FS Package type: package -summary: Shared loader-facing filesystem boundary for Egg loaders and future bundled runtimes. +summary: Shared loader-facing filesystem boundary for Egg loaders and bundled runtimes. source_files: - packages/loader-fs/src/index.ts - packages/loader-fs/package.json -updated_at: 2026-05-10 +updated_at: 2026-06-02 status: active --- @@ -25,5 +25,7 @@ discovery to `globby.sync`, and module loading to the same `@eggjs/utils` `@eggjs/core` depends on this package and re-exports its public API so existing core consumers can still import the loader filesystem boundary from core while -tegg and later bundled runtime packages can depend on the smaller package -directly. +tegg and bundled runtime packages can depend on the smaller package directly. +The manifest-backed implementation used by bundle workers lives in +`@eggjs/core` as `ManifestLoaderFS`; this package remains the shared interface +and real-filesystem implementation.