docs(site): add Bundle Deployment guide#5988
Conversation
Document `egg-bin bundle` / `@eggjs/egg-bundler`: how to build a deployable CommonJS artifact, the output layout, how to run it (install externals next to worker.js, single-process boot), tegg-app support (manifest-served module discovery keeps the DI graph intact), and current limitations. Added to the Core sidebar (EN + zh-CN), next to the Startup Manifest guide it builds on. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
💤 Files with no reviewable changes (2)
📝 WalkthroughWalkthroughTwo new documentation pages ( ChangesBundle Deployment Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds documentation for Bundle Deployment in both English and Chinese, detailing how to bundle, configure, and run Egg applications using @eggjs/egg-bundler. It also updates the VitePress sidebar configuration to include these new pages. The review comments correctly point out that the documented npm ci command requires a package-lock.json file to run successfully, suggesting that both package.json and package-lock.json should be copied to the bundle directory.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| $ cd dist-bundle | ||
| $ cp ../package.json . | ||
| $ npm ci --omit=dev | ||
| $ node worker.js |
There was a problem hiding this comment.
The npm ci command strictly requires a package-lock.json file to be present in the directory. Copying only package.json will cause the command to fail. You should copy package-lock.json as well, or use npm install --omit=dev instead.
| $ cd dist-bundle | |
| $ cp ../package.json . | |
| $ npm ci --omit=dev | |
| $ node worker.js | |
| $ cd dist-bundle | |
| $ cp ../package.json ../package-lock.json . | |
| $ npm ci --omit=dev | |
| $ node worker.js |
| $ cd dist-bundle | ||
| $ cp ../package.json . | ||
| $ npm ci --omit=dev | ||
| $ node worker.js |
There was a problem hiding this comment.
The npm ci command strictly requires a package-lock.json file to be present in the directory. Copying only package.json will cause the command to fail. You should copy package-lock.json as well, or use npm install --omit=dev instead.
| $ cd dist-bundle | |
| $ cp ../package.json . | |
| $ npm ci --omit=dev | |
| $ node worker.js | |
| $ cd dist-bundle | |
| $ cp ../package.json ../package-lock.json . | |
| $ npm ci --omit=dev | |
| $ node worker.js |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## next #5988 +/- ##
=======================================
Coverage 85.91% 85.91%
=======================================
Files 669 669
Lines 19907 19907
Branches 3949 3949
=======================================
Hits 17104 17104
Misses 2425 2425
Partials 378 378 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with 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.
Inline comments:
In `@site/docs/core/bundle.md`:
- Around line 62-71: Add a language tag to the markdown code fence that displays
the file tree output. The fence currently opens with just triple backticks but
needs a language identifier to satisfy markdownlint rule MD040. Add either
`text` or `console` as the language tag to the opening fence before the
dist-bundle/ tree structure to make the documentation lint-clean.
- Around line 78-86: The bash recipe in the example needs two updates: First,
replace the `cp ../package.json .` step with an approach that preserves the
bundle's intentional `{ "type": "commonjs" }` manifest instead of overwriting it
(consider merging dependencies or documenting how to safely combine manifests).
Second, add an explicit step to copy the appropriate lockfile
(package-lock.json, npm-shrinkwrap.json, pnpm-lock.yaml, or yarn.lock) before
running `npm ci`, since npm ci requires a lockfile to function properly.
Additionally, add a language specifier (e.g., text) to the unlabeled code fence
that appears earlier in the document before this example.
In `@site/docs/zh-CN/core/bundle.md`:
- Around line 52-61: The code block containing the dist-bundle directory
structure tree is missing a language identifier on the opening code fence, which
causes markdownlint rule MD040 to report a warning. Add a language identifier
(either `text` or `console`) immediately after the opening triple backticks of
the code block that shows the dist-bundle directory tree with worker.js,
_root-of-the-server chunks, and other files.
- Around line 67-75: The bash example in the bundle documentation currently
shows copying the app's package.json to dist-bundle, which overwrites the
bundler-generated package.json that explicitly contains { "type": "commonjs" }.
This is problematic because if the app declares "type": "module", Node will
misinterpret the bundled CommonJS files as ESM. Additionally, the npm ci command
requires either package-lock.json or npm-shrinkwrap.json to exist. Update the
example to either preserve the bundler's package.json (which contains the
critical "type": "commonjs" declaration) while only copying necessary
dependencies, or explicitly copy the lockfile from the parent directory before
running npm ci and document why the package type declaration is important for
CommonJS module resolution.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: f496f131-669f-4944-b40a-7dacd4e5dc2b
📒 Files selected for processing (3)
site/.vitepress/config.mtssite/docs/core/bundle.mdsite/docs/zh-CN/core/bundle.md
| ``` | ||
| dist-bundle/ | ||
| ├── worker.js # synthetic worker entry produced by the bundler | ||
| ├── _root-of-the-server__*.js # @utoo/pack module-graph chunks (opaque names) | ||
| ├── _turbopack__runtime.js # @utoo/pack runtime shim | ||
| ├── app/... # copied runtime assets (html/static, etc.) | ||
| ├── tsconfig.json # written for the SWC compiler | ||
| ├── package.json # { "type": "commonjs" } | ||
| └── bundle-manifest.json # reference metadata (externals, chunks, ...) | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add a language tag to the output tree fence.
The tree block is unlabeled, so markdownlint flags it (MD040). Mark it as text or console to keep the docs lint-clean.
Suggested fix
-```
+```text📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ``` | |
| dist-bundle/ | |
| ├── worker.js # synthetic worker entry produced by the bundler | |
| ├── _root-of-the-server__*.js # @utoo/pack module-graph chunks (opaque names) | |
| ├── _turbopack__runtime.js # @utoo/pack runtime shim | |
| ├── app/... # copied runtime assets (html/static, etc.) | |
| ├── tsconfig.json # written for the SWC compiler | |
| ├── package.json # { "type": "commonjs" } | |
| └── bundle-manifest.json # reference metadata (externals, chunks, ...) | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 62-62: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 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 `@site/docs/core/bundle.md` around lines 62 - 71, Add a language tag to the
markdown code fence that displays the file tree output. The fence currently
opens with just triple backticks but needs a language identifier to satisfy
markdownlint rule MD040. Add either `text` or `console` as the language tag to
the opening fence before the dist-bundle/ tree structure to make the
documentation lint-clean.
Source: Linters/SAST tools
| Packages classified as **external** are not inlined and must be installed | ||
| alongside the bundle. The simplest way is to copy the app's `package.json` next | ||
| to `worker.js` and install production dependencies: | ||
|
|
||
| ```bash | ||
| $ cd dist-bundle | ||
| $ cp ../package.json . | ||
| $ npm ci --omit=dev | ||
| $ node worker.js |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major
🧩 Analysis chain
🏁 Script executed:
# First, find and examine the documentation file
find . -name "bundle.md" -type fRepository: eggjs/egg
Length of output: 207
🏁 Script executed:
# Search for information about dist-bundle package.json and its generation
rg "dist-bundle" --type md --type json -A 3 -B 3Repository: eggjs/egg
Length of output: 147
🏁 Script executed:
# Check for any bundle build configuration or documentation about the CommonJS manifest
rg '"type".*"commonjs"' -A 2 -B 2Repository: eggjs/egg
Length of output: 147
🏁 Script executed:
# Search for markdownlint configuration
find . -name ".markdownlint*" -o -name "markdownlint.config.*" | head -10Repository: eggjs/egg
Length of output: 147
🏁 Script executed:
# Read the bundle.md file around lines 78-86
cat -n site/docs/core/bundle.md | sed -n '70,95p'Repository: eggjs/egg
Length of output: 1160
🏁 Script executed:
# Read more of the file to understand the context of the run section
cat -n site/docs/core/bundle.md | sed -n '1,100p'Repository: eggjs/egg
Length of output: 4931
🏁 Script executed:
# Search for bundle build code to understand how dist-bundle is generated
rg "dist-bundle|package.json" --type js --type ts -A 3 -B 1 | head -100Repository: eggjs/egg
Length of output: 147
🏁 Script executed:
# Look for the build or bundle configuration files
find . -name "*bundle*" -type f | grep -E "\.(js|ts|json)$" | head -20Repository: eggjs/egg
Length of output: 330
🏁 Script executed:
# Look at the bundle command implementation to understand how package.json is generated
cat -n ./tools/egg-bin/src/commands/bundle.ts | head -150Repository: eggjs/egg
Length of output: 5411
🏁 Script executed:
# Search for where the dist-bundle package.json is created
rg "package.json.*commonjs|type.*commonjs" --type ts --type js -B 5 -A 5Repository: eggjs/egg
Length of output: 147
🏁 Script executed:
# Check the egg-bundler source for package.json generation
find ./tools/egg-bundler -name "*.ts" -o -name "*.js" | head -20Repository: eggjs/egg
Length of output: 1194
🏁 Script executed:
# Look for the bundler's output generation logic
rg "dist-bundle|write.*package" ./tools/egg-bundler --type ts -A 3 -B 1 | head -80Repository: eggjs/egg
Length of output: 6510
🏁 Script executed:
# Look at the PackRunner test that confirms package.json { "type": "commonjs" } is written
cat -n ./tools/egg-bundler/test/PackRunner.test.ts | sed -n '1,100p'Repository: eggjs/egg
Length of output: 4783
🏁 Script executed:
# Find the specific test and see what it does
rg 'writes package.json.*commonjs' ./tools/egg-bundler/test/PackRunner.test.ts -A 30Repository: eggjs/egg
Length of output: 1594
🏁 Script executed:
# Look at the PackRunner implementation to see where package.json is written
cat -n ./tools/egg-bundler/src/lib/PackRunner.ts | head -150Repository: eggjs/egg
Length of output: 7400
🏁 Script executed:
# Search for where the bundle's package.json is generated with commonjs type
rg '"type".*"commonjs"' ./tools/egg-bundler -A 3 -B 3Repository: eggjs/egg
Length of output: 1678
🏁 Script executed:
# Check if there's a markdownlint config in the project
find . -type f \( -name ".markdownlint*" -o -name "markdownlint*" \) 2>/dev/null | head -20Repository: eggjs/egg
Length of output: 147
🏁 Script executed:
# Check for markdown linting rules or standards
rg "fence|code.*block" site/docs --type md -i | head -20Repository: eggjs/egg
Length of output: 147
🏁 Script executed:
# Let's verify the fence labeling issue by checking the actual lines 62-71
cat -n site/docs/core/bundle.md | sed -n '60,75p'Repository: eggjs/egg
Length of output: 912
Preserve the bundle-generated manifest and add the lockfile step.
The example at lines 82-86 has two problems:
cp ../package.json .overwrites the bundle's intentional{ "type": "commonjs" }manifest, which can breaknode worker.jsfor apps with a different package type (e.g.,"type": "module").npm cifails without a lockfile. You must also copypackage-lock.json(ornpm-shrinkwrap.json/pnpm-lock.yaml/yarn.lockas appropriate).
Update the recipe to keep the bundle's CommonJS manifest intact and document the lockfile step explicitly.
Also, the unlabeled code fence at lines 62-71 should specify a language (e.g., ```text).
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 83-83: Dollar signs used before commands without showing output
(MD014, commands-show-output)
[warning] 84-84: Dollar signs used before commands without showing output
(MD014, commands-show-output)
[warning] 85-85: Dollar signs used before commands without showing output
(MD014, commands-show-output)
[warning] 86-86: Dollar signs used before commands without showing output
(MD014, commands-show-output)
🤖 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 `@site/docs/core/bundle.md` around lines 78 - 86, The bash recipe in the
example needs two updates: First, replace the `cp ../package.json .` step with
an approach that preserves the bundle's intentional `{ "type": "commonjs" }`
manifest instead of overwriting it (consider merging dependencies or documenting
how to safely combine manifests). Second, add an explicit step to copy the
appropriate lockfile (package-lock.json, npm-shrinkwrap.json, pnpm-lock.yaml, or
yarn.lock) before running `npm ci`, since npm ci requires a lockfile to function
properly. Additionally, add a language specifier (e.g., text) to the unlabeled
code fence that appears earlier in the document before this example.
| ``` | ||
| dist-bundle/ | ||
| ├── worker.js # 打包器生成的 worker 入口 | ||
| ├── _root-of-the-server__*.js # @utoo/pack 模块图 chunk（文件名不透明） | ||
| ├── _turbopack__runtime.js # @utoo/pack 运行时垫片 | ||
| ├── app/... # 拷贝的运行时资源（html/静态资源等） | ||
| ├── tsconfig.json # 供 SWC 编译器读取 | ||
| ├── package.json # { "type": "commonjs" } | ||
| └── bundle-manifest.json # 参考元数据（externals、chunks 等） | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
给产物树代码块补一个语言标记。
这个代码块没有语言标记，markdownlint（MD040）会报警。这里标成 text 或 console 就行。
建议修改
-```
+```text📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ``` | |
| dist-bundle/ | |
| ├── worker.js # 打包器生成的 worker 入口 | |
| ├── _root-of-the-server__*.js # @utoo/pack 模块图 chunk（文件名不透明） | |
| ├── _turbopack__runtime.js # @utoo/pack 运行时垫片 | |
| ├── app/... # 拷贝的运行时资源（html/静态资源等） | |
| ├── tsconfig.json # 供 SWC 编译器读取 | |
| ├── package.json # { "type": "commonjs" } | |
| └── bundle-manifest.json # 参考元数据（externals、chunks 等） | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 52-52: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 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 `@site/docs/zh-CN/core/bundle.md` around lines 52 - 61, The code block
containing the dist-bundle directory structure tree is missing a language
identifier on the opening code fence, which causes markdownlint rule MD040 to
report a warning. Add a language identifier (either `text` or `console`)
immediately after the opening triple backticks of the code block that shows the
dist-bundle directory tree with worker.js, _root-of-the-server chunks, and other
files.
Source: Linters/SAST tools
| 被识别为 **external** 的包不会被内联，必须与产物一起安装。最简单的方式是把应用的 | ||
| `package.json` 拷贝到 `worker.js` 旁边，并安装生产依赖： | ||
|
|
||
| ```bash | ||
| $ cd dist-bundle | ||
| $ cp ../package.json . | ||
| $ npm ci --omit=dev | ||
| $ node worker.js | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🔴 Critical
🧩 Analysis chain
🏁 Script executed:
# First, let's locate and read the specific file
find . -name "bundle.md" -path "*/zh-CN/*" | head -5Repository: eggjs/egg
Length of output: 180
🏁 Script executed:
# Also check for the English version to compare
find . -name "bundle.md" | grep -E "(en|english)" | head -5Repository: eggjs/egg
Length of output: 147
🏁 Script executed:
# Check the structure of the docs directory
ls -la site/docs/ 2>/dev/null || echo "Directory not found"Repository: eggjs/egg
Length of output: 833
🏁 Script executed:
# Read the specific lines from the Chinese bundle.md file
cat -n site/docs/zh-CN/core/bundle.md | sed -n '60,85p'Repository: eggjs/egg
Length of output: 1008
🏁 Script executed:
# Check if there's an English version to compare
find site/docs -name "bundle.md" -not -path "*/zh-CN/*" | head -5Repository: eggjs/egg
Length of output: 172
🏁 Script executed:
# Check the total length of the file
wc -l site/docs/zh-CN/core/bundle.mdRepository: eggjs/egg
Length of output: 181
🏁 Script executed:
# Read the English version
cat -n site/docs/core/bundle.md | sed -n '60,85p'Repository: eggjs/egg
Length of output: 1265
🏁 Script executed:
# Let's also check the full context of both files to understand the bundle output structure
cat -n site/docs/zh-CN/core/bundle.md | sed -n '40,80p'Repository: eggjs/egg
Length of output: 1459
🏁 Script executed:
# Check the bundler documentation mentioned in the file
find . -path "*/egg-bundler/docs/output-structure.md" | head -5Repository: eggjs/egg
Length of output: 192
🏁 Script executed:
# Let's read more context from the English version to see if there's any additional explanation
cat -n site/docs/core/bundle.md | sed -n '76,95p'Repository: eggjs/egg
Length of output: 898
🏁 Script executed:
# Check what package.json the bundler generates
find . -name "*.ts" -o -name "*.js" | xargs grep -l "type.*commonjs" | grep -i bundl | head -5Repository: eggjs/egg
Length of output: 2258
🏁 Script executed:
# Look for any bundler code that generates package.json
find ./tools/egg-bundler -type f \( -name "*.ts" -o -name "*.js" \) | head -10Repository: eggjs/egg
Length of output: 592
🏁 Script executed:
# Check the PackRunner to see how package.json is generated
cat -n tools/egg-bundler/src/lib/PackRunner.ts | head -100Repository: eggjs/egg
Length of output: 4718
🏁 Script executed:
# Look for package.json generation in the bundler
rg "package.json" tools/egg-bundler/src --context 3 | head -60Repository: eggjs/egg
Length of output: 5221
🏁 Script executed:
# Check if the bundler writes a package.json with "type": "commonjs"
rg "commonjs" tools/egg-bundler/srcRepository: eggjs/egg
Length of output: 674
Preserve the bundler-generated package.json to maintain CommonJS type declaration.
The bundler explicitly writes { "type": "commonjs" } to dist-bundle/package.json to prevent the parent ESM package from forcing CJS modules into ESM parse mode. Copying the app's package.json overwrites this critical declaration. If the app declares "type": "module", Node will then misinterpret the bundled CJS files as ESM, causing module resolution to fail.
Additionally, the example does not mention that npm ci requires a package-lock.json or npm-shrinkwrap.json to exist; without it, the command will fail.
Update the example to either preserve the bundler's manifest or explicitly copy the lockfile and explain the package type requirement.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 71-71: Dollar signs used before commands without showing output
(MD014, commands-show-output)
[warning] 72-72: Dollar signs used before commands without showing output
(MD014, commands-show-output)
[warning] 73-73: Dollar signs used before commands without showing output
(MD014, commands-show-output)
[warning] 74-74: Dollar signs used before commands without showing output
(MD014, commands-show-output)
🤖 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 `@site/docs/zh-CN/core/bundle.md` around lines 67 - 75, The bash example in the
bundle documentation currently shows copying the app's package.json to
dist-bundle, which overwrites the bundler-generated package.json that explicitly
contains { "type": "commonjs" }. This is problematic because if the app declares
"type": "module", Node will misinterpret the bundled CommonJS files as ESM.
Additionally, the npm ci command requires either package-lock.json or
npm-shrinkwrap.json to exist. Update the example to either preserve the
bundler's package.json (which contains the critical "type": "commonjs"
declaration) while only copying necessary dependencies, or explicitly copy the
lockfile from the parent directory before running npm ci and document why the
package type declaration is important for CommonJS module resolution.
Remove the "Tegg applications" section (manifest decoratedFiles / DI-graph internals) — too implementation-focused for a user-facing guide. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
估计很快可以将 egg 部署到 cf workers 上了 |
Adds a Bundle Deployment guide to the Core docs (EN + zh-CN), documenting the
egg-bin bundle/@eggjs/egg-bundlerworkflow:egg-bin bundle, options, auto-externals,module.ymlconfigbundle-manifest.jsonworker.js(npm ci --omit=dev), single-process bootdecoratedFiles(no on-disk glob), keeping the tegg DI graph intact for auto-resolved egg-compatible injects (httpClient/logger/config)Registered in the Core sidebar next to the Startup Manifest guide it builds on. Pairs with the bundle-boot fix in #5987.
🤖 Generated with Claude Code
Summary by CodeRabbit
egg-bin bundleworkflow, key CLI options, and how build outputs are structured indist-bundle/.module.ymlconfiguration examples and documented limitations.