docs(utils): document bundle module loader

[killagu]

Summary

• document the new setBundleModuleLoader(loader) API in @eggjs/utils
• clarify loader fallback, default export handling, and clearing behavior

Verification

• pnpm exec oxfmt --check packages/utils/README.md

Note: the normal pre-commit hook was not used for the final commit because oxlint --type-aware --fix fails on a Markdown-only staged set with No files found to lint; the targeted Markdown format check passed.

Summary by CodeRabbit

• Documentation
  • Added documentation describing how to register and clear a globally shared, synchronous hook for customizing dynamic import resolution, including fallback behavior when the hook yields no result and guidance that the hook must not be asynchronous.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0be106d5-74f1-47d3-af52-356fede6d2bb

📥 Commits

Reviewing files that changed from the base of the PR and between a0ff522 and a49016f.

📒 Files selected for processing (1)

• packages/utils/README.md

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/utils/README.md

---

📝 Walkthrough

Walkthrough

Adds README documentation for a new setBundleModuleLoader(loader) API in packages/utils, describing global registration via globalThis, synchronous-return semantics, undefined fallback behavior, and clearing the loader when passed undefined.

Changes

Cohort / File(s)	Summary
API Documentation packages/utils/README.md	Adds documentation for setBundleModuleLoader(loader): how to register a globally shared synchronous hook for importModule(), that returning undefined falls back to normal resolution, non-undefined synchronous returns are treated as bundle hits (respecting importDefaultOnly and __esModule rules), loader must not be async/return Promises, and passing undefined clears the loader.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• feat(utils): add setBundleModuleLoader runtime hook #5867: Implements the runtime setBundleModuleLoader() hook used by import.ts, matching the documentation changes.

Poem

🐰 A loader is born, so shiny and new,
In importModule's bundle, we toss it right through!
Undefined means revert, else hit the jackpot,
The sync hook stands ready—no promises sought. 🥕✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding documentation for the bundle module loader API in the utils package.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/egg-doc/b8a28020

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cloudflare-workers-and-pages]

Deploying egg with    Cloudflare Pages

Latest commit:	a49016f
Status:	✅  Deploy successful!
Preview URL:	https://1f41d3f0.egg-cci.pages.dev
Branch Preview URL:	https://agent-egg-doc-b8a28020.egg-cci.pages.dev

View logs

[gemini-code-assist]

Code Review

This pull request adds documentation for the setBundleModuleLoader function in the @eggjs/utils package. The review feedback suggests clarifying that the loader is registered globally via globalThis and refining the terminology used to describe the fallback behavior to standard module resolution.

[Copilot]

Pull request overview

Documents the new bundle module loader hook in @eggjs/utils, clarifying how importModule() can be intercepted for bundled/virtual module resolution.

Changes:

• Add README documentation for setBundleModuleLoader(loader).
• Describe loader fallback behavior (undefined), default export unwrapping semantics, and how to clear the loader.

[cloudflare-workers-and-pages]

Deploying egg-v3 with    Cloudflare Pages

Latest commit:	a49016f
Status:	✅  Deploy successful!
Preview URL:	https://f32d169e.egg-v3.pages.dev
Branch Preview URL:	https://agent-egg-doc-b8a28020.egg-v3.pages.dev

View logs