Automatic Chunking Logic
Rollup's automatic chunking is based strictly on the module graph and import relationships, not on module size. When Rollup encounters a dynamic import(), it treats that call as a split point. It then analyzes the dependency tree of the imported module to determine which code is unique to that branch and which is shared with other parts of the application.
Chunk Boundary Determination
The algorithm prioritizes avoiding duplication. If two different dynamic imports both depend on the same module, Rollup attempts to hoist that shared dependency into a separate common chunk. This ensures the shared code is downloaded only once, regardless of which dynamic path is triggered first.
Size Thresholds and Limits
Rollup does not enforce a default maximum chunk size. There is no built-in mechanism to automatically split a single dynamic chunk into smaller pieces once it exceeds a specific byte threshold. To manage chunk sizes, you must use output.manualChunks to explicitly group modules or use a plugin for more granular control.
When Duplication Occurs
While Rollup strives for consolidation, shared dependencies may be duplicated across chunks under the following conditions:
- Circular Dependencies: Complex circular references involving dynamic imports can confuse the boundary determination, occasionally leading to duplicated code to ensure runtime stability.
- Manual Chunk Overrides: If
manualChunks is configured incorrectly, it may force a module into a specific chunk that conflicts with the automatic hoisting logic.
- Version Mismatches: If different dynamic imports reference different versions of the same package (common in monorepos), Rollup treats them as distinct modules.
Verification and Management
To diagnose boundary issues, use a bundle analyzer tool to visualize the actual distribution of modules. You can verify current chunking behavior by inspecting your build output directory:
# Example: Check for unexpected duplicate files or oversized chunks
ls -lh dist/*.js
If you are seeing an excessive number of tiny chunks, you can use the experimentalMinChunkSize option in your configuration to merge small modules and reduce HTTP request overhead.
Diagnostic Detail Needed: Are you using a monorepo structure with multiple versions of the same dependency? This significantly alters how Rollup determines shared boundaries.
rollup