Skip to content

docs(wiki): record bundler runtime assets #5938

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
killagu wants to merge 1 commit into
base: next
Choose a base branch
from
Open

docs(wiki): record bundler runtime assets #5938

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions wiki/log.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,12 @@

Dates use the workspace-local Asia/Shanghai calendar date.

## [2026-05-08] package | record bundler runtime assets and tegg manifest path normalization

- sources touched: `tools/egg-bundler/src/lib/Bundler.ts`, `tools/egg-bundler/src/lib/ManifestLoader.ts`, `tools/egg-bundler/src/lib/EntryGenerator.ts`, `tegg/core/loader/src/LoaderUtil.ts`, `tools/egg-bundler/README.md`, `tools/egg-bundler/docs/output-structure.md`
- pages updated: `wiki/log.md`, `wiki/packages/egg-bundler.md`
- note: Recorded default/configurable runtime asset copying, bundle manifest chunk inclusion for copied assets, tegg module reference/descriptor path normalization, and tegg loader use of the bundle module loader before dynamic import fallback.

## [2026-05-06] package | sync bundled runtime support changes

- sources touched: `tools/egg-bundler/src/lib/ExternalsResolver.ts`, `packages/utils/src/import.ts`, `plugins/onerror/src/lib/onerror.ts`
Expand Down
17 changes: 15 additions & 2 deletions wiki/packages/egg-bundler.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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-08
status: active
---

Expand All @@ -34,7 +34,8 @@ CommonJS artifact from an Egg application.
3. `EntryGenerator` writes a synthetic worker entry that installs the bundle
manifest/module loader before starting Egg.
4. `PackRunner` invokes `@utoo/pack`.
5. `Bundler` writes `bundle-manifest.json` and returns absolute output paths.
5. `Bundler` copies configured runtime assets into the output directory.
6. `Bundler` writes `bundle-manifest.json` and returns absolute output paths.

## Current Behavior

Expand All @@ -45,12 +46,24 @@ CommonJS artifact from an Egg application.
lifecycle, runs `loadMetadata()` hooks, and the manifest generation child
process exits after writing the manifest, so registered `beforeClose` hooks do
not run.
- Applications may configure `bundle.runtimeAssets` in `module.yml` or
`BundlerConfig`. By default, the bundler scans `app` for runtime assets and
force-copies `app/public`, `app/assets`, and `app/static`, preserving
baseDir-relative output paths. Source-like files such as `.js`, `.ts`, `.mjs`,
and `.cjs` are skipped outside force-copy directories, and manifest-known
Comment on lines +52 to +53
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The list of skipped source-like extensions is incomplete. The implementation in Bundler.ts (line 44) defines BUNDLED_SOURCE_EXTENSIONS as including .cts, .jsx, .mts, and .tsx in addition to the ones currently listed. Updating this list will provide more accurate guidance for users.

Suggested change
baseDir-relative output paths. Source-like files such as `.js`, `.ts`, `.mjs`,
and `.cjs` are skipped outside force-copy directories, and manifest-known
baseDir-relative output paths. Source-like files such as `.js`, `.ts`, `.mjs`,
`.cjs`, `.mts`, `.cts`, `.tsx`, and `.jsx` are skipped outside force-copy directories, and manifest-known

module files are not copied as assets.
- 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.
- `ManifestLoader` normalizes tegg `moduleReferences` and `moduleDescriptors`
through the same module map so descriptors and references use matching
app-relative or package-normalized paths in the bundle manifest. Decorated
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The term "bundle manifest" is ambiguous here because the bundler now also generates a separate bundle-manifest.json file (as noted in step 6). In this context, it refers to the app startup manifest that is embedded into the worker entry. Using "startup manifest" (consistent with line 31) would be clearer.

Suggested change
app-relative or package-normalized paths in the bundle manifest. Decorated
app-relative or package-normalized paths in the startup manifest. Decorated

files from those descriptors are imported by the worker entry, and tegg loader
file loading can use `globalThis.__EGG_BUNDLE_MODULE_LOADER__` before falling
back to dynamic import.
- 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
Expand Down
Loading