Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
3 changes: 3 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,9 @@ status: seed|active|stale

Use lowercase kebab-case filenames and keep one topic per page.

Use the workspace-local Asia/Shanghai calendar date for wiki log headings and
frontmatter `updated_at` values.

## Citation And Freshness Rules

- every nontrivial wiki claim should be traceable to raw sources
Expand Down
2 changes: 1 addition & 1 deletion plugins/onerror/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Default error handling plugin for egg.
- `html: Function` - customize html error handler.
- `text: Function` - customize text error handler.
- `json: Function` - customize json error handler.
- `jsonp: Function` - customize jsonp error handler.
- `js: Function` - customize JSONP error handler.

```ts
// config/config.default.ts
Expand Down
2 changes: 2 additions & 0 deletions wiki/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,9 @@ Read this file before exploring raw sources.
## Packages

- [Egg Bundler](./packages/egg-bundler.md) - Tooling package that bundles Egg applications and backs `egg-bin bundle`.
- [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.

## Sources

Expand Down
8 changes: 8 additions & 0 deletions wiki/log.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,13 @@
# Wiki Log

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

## [2026-05-06] package | sync bundled runtime support changes
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Use a non-future log date to avoid chronology drift.

Line 3 records 2026-05-06, but this PR is dated 2026-05-05 (2026-05-05T18:06:51Z). Please align to the actual entry date (or explicitly document UTC-based dating) so the log and package updated_at fields don’t appear future-dated.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@wiki/log.md` at line 3, Update the log entry date on the second line in
wiki/log.md from "2026-05-06" to the actual PR date "2026-05-05" (or
alternatively add an explicit note that dates are UTC) so the entry aligns with
the PR timestamp and avoids a future-dated record; locate the string "##
[2026-05-06] package | sync bundled runtime support changes" and replace the
date portion or append a UTC dating note to that header.


- sources touched: `tools/egg-bundler/src/lib/ExternalsResolver.ts`, `packages/utils/src/import.ts`, `plugins/onerror/src/lib/onerror.ts`
- pages updated: `wiki/index.md`, `wiki/log.md`, `wiki/packages/egg-bundler.md`, `wiki/packages/utils.md`, `wiki/packages/onerror.md`
- note: Recorded native optional platform package externalization, the opaque native dynamic import fallback used by bundled `importModule()`, and the local `@eggjs/onerror` implementation that avoids `koa-onerror` template reads.

## [2026-05-03] package | record egg bundler runtime path mapping

- sources touched: `tools/egg-bundler/src/lib/EntryGenerator.ts`, `tools/egg-bundler/docs/output-structure.md`
Expand Down
3 changes: 2 additions & 1 deletion wiki/packages/egg-bundler.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,10 @@ source_files:
- tools/egg-bundler/src/index.ts
- tools/egg-bundler/src/lib/Bundler.ts
- tools/egg-bundler/src/lib/EntryGenerator.ts
- 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-03
updated_at: 2026-05-06
status: active
---

Expand Down
39 changes: 39 additions & 0 deletions wiki/packages/onerror.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
---
title: Onerror Plugin
type: package
summary: Default Egg error-handling plugin and configurable response negotiation layer.
source_files:
- plugins/onerror/README.md
- plugins/onerror/src/app.ts
- plugins/onerror/src/lib/onerror.ts
- plugins/onerror/src/lib/error_view.ts
- plugins/onerror/src/config/config.default.ts
updated_at: 2026-05-06
status: active
---

# Onerror Plugin

`@eggjs/onerror` is the default Egg error-handling plugin. It installs
`ctx.onerror` and supports configurable handlers for HTML, text, JSON, JS
(JSONP), redirect, and catch-all error responses.

## Public Configuration

- `errorPageUrl` redirects production HTML requests after unexpected errors.
- `accepts` customizes content negotiation.
- `all`, `html`, `text`, `json`, and `js` customize response handling for
specific response types.
- `appErrorFilter` can suppress logging for selected errors.

## Current Behavior

The plugin owns its Koa-style `onerror()` implementation in
`plugins/onerror/src/lib/onerror.ts` instead of importing it from
`koa-onerror`. This keeps the response behavior local to the plugin and avoids
reading `koa-onerror` package templates when the plugin app boot hook is
imported, which is important for static bundling.

Default HTML error-page rendering still flows through `ErrorView` and the
plugin's local default template. Applications can continue to provide custom
templates and handlers through the documented `config.onerror` options.
38 changes: 38 additions & 0 deletions wiki/packages/utils.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
title: Utils Package
type: package
summary: Shared utility package for Egg module loading, config/plugin helpers, and bundled module-loader integration.
source_files:
- packages/utils/README.md
- packages/utils/src/import.ts
- packages/utils/test/bundle-import.test.ts
updated_at: 2026-05-06
status: active
---

# Utils Package

`@eggjs/utils` is a shared utility package used across Egg packages.

## Public Surfaces

- `getPlugins(options)`, `getLoadUnits(options)`, `getConfig(options)`, and
`getFrameworkPath(options)` expose application/framework discovery helpers.
- `importModule(filepath, options)` and `importResolve(filepath, options)`
centralize runtime module loading.
- `setBundleModuleLoader(loader)` registers the bundled runtime loader hook.

## Bundled Module Loading

`setBundleModuleLoader(loader)` stores the hook on `globalThis` so bundled and
external copies of `@eggjs/utils` share the same loader. The loader receives the
original `importModule()` filepath after POSIX separator normalization, or a
virtual specifier. Returning `undefined` falls back to the normal resolution
path; other return values follow the same default-export unwrapping rules as
`importModule()`.

When a bundle loader is installed and `importModule()` falls through to native
ESM loading, `packages/utils/src/import.ts` uses an opaque native dynamic import
created with `new Function('specifier', 'return import(specifier);')`. This
prevents bundlers such as Turbopack from rewriting non-static dynamic import
expressions and preserves Node's native fallback for external ESM modules.
Loading