docs: known-issue note for rolldown chunk-cycle (#9161/#9224) bundled in v0.1.20

[smorimoto]

Documentation is

• Missing

Explain in Detail

vite-plus@0.1.20 (released 2026-04-29) bundles rolldown@1.0.0-rc.17 and vite@8.0.10 per the release notes and the bundledVersions field in @voidzero-dev/vite-plus-core@0.1.20's package.json.

That rolldown release contains a chunk-optimizer regression where the runtime helper or builtin:esm-external-* shim modules can be hoisted into the entry chunk while a code-split CJS chunk imports those bindings back from the entry, forming an ESM cycle. When the CJS chunk's top-level evaluation runs (e.g. var x = __toESM(require_lib(), 1) generated for pg), the imported binding is still in TDZ / uninitialized, producing Uncaught TypeError: <fn> is not a function at module load.

The bug is tracked upstream in:

• [Bug]: (regression) circular import generated when using static import and dynamic import rolldown/rolldown#9161
• Circular runtime helper import between entry chunk and code-split CJS chunk causes "e is not a function" at load (rc.17, regression from rc.15) rolldown/rolldown#9224

…and fixed by rolldown/rolldown#9164, merged on 2026-04-26 (i.e. after rc.17 was cut on 2026-04-22). The fix will arrive in Vite+ once rolldown rc.18+ is bundled into a future vite-plus-core release.

Real-world impact today is meaningful because the build step completes successfully with no warning — affected users only discover the problem at deploy or first page load. The reported reproductions span quite different ecosystems:

• pg (node-postgres) on Cloudflare Workers (this report; Cloudflare deploy validation rejects with [code: 10021])
• google-protobuf in a React/Vite SPA (rolldown#9224)
• @noble/curves + @noble/hashes in viem/wagmi (rolldown#9225)

so this is not a Cloudflare-specific issue — any Vite+ project with bundled CJS dependencies that perform eager top-level work is exposed.

There is a one-off, drop-in user-config workaround that mirrors what #9164 does internally:

// vite.config.ts
import { defineConfig } from "vite-plus";

export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        advancedChunks: {
          groups: [
            {
              name: "node-builtin-shims",
              test: /\bbuiltin:esm-external-/,
              priority: 100,
            },
          ],
        },
      },
    },
  },
});

This forces every builtin:esm-external-* virtual module into a sibling chunk so that neither the entry nor the consumer chunk re-imports through the cycle.

Your Suggestion for Changes

Two non-mutually-exclusive asks, in priority order:

1. Add a "Known issue" addendum to the v0.1.20 release notes so affected users land on the workaround without having to rediscover the rolldown thread. Suggested wording:

   Known issue: rolldown chunk-cycle in CJS-heavy builds

   v0.1.20 bundles rolldown 1.0.0-rc.17, which contains a chunk-optimizer cycle bug ([Bug]: (regression) circular import generated when using static import and dynamic import rolldown/rolldown#9161, Circular runtime helper import between entry chunk and code-split CJS chunk causes "e is not a function" at load (rc.17, regression from rc.15) rolldown/rolldown#9224) that can cause production builds to crash at module load with errors like Uncaught TypeError: <fn> is not a function when bundled CJS dependencies (e.g. pg, google-protobuf, @noble/curves) execute eagerly at module top level. The fix landed in fix(chunk-optimizer): pick dominator for runtime placement to avoid cycles rolldown/rolldown#9164 (post-rc.17) and will be available once rolldown rc.18+ is bundled.

   Until then, force the affected helpers into a sibling chunk via build.rollupOptions.output.advancedChunks (see snippet above).

2. Treat this issue as a tracking thread for the bundled-rolldown bump, so the umbrella status is visible in one place rather than scattered across multiple downstream reports. The status table below can be kept current as the release chain progresses.

Relevant Page

Release notes: https://github.com/voidzero-dev/vite-plus/releases/tag/v0.1.20

Reproduction (Optional)

The two upstream rolldown issues already include reductions (google-protobuf SPA in #9224, viem/wagmi in #9225). On the Vite+ side, reproducing only requires a project that uses vp build with a CJS dependency that ships eager top-level CJS init — pg is a convenient one. Happy to put together a Vite+-specific minimal repro if useful for the maintainers.

---

Tracking

Status of the upstream chain (please update as it progresses):

Step	Status
rolldown/rolldown#9164 merged	✅ 2026-04-26
rolldown@1.0.0-rc.18 released (or later)	⏳ pending
vite@8.0.11+ bundles new rolldown	⏳ pending
@voidzero-dev/vite-plus-core bumps bundledVersions.rolldown	⏳ pending
vite-plus@x.y.z released with the fix	⏳ pending

Documentation status:

• v0.1.20 release notes mention the known issue

System Info

vp --version
0.1.20

OS: macOS 14.x (Darwin arm64) and Linux x86_64 (Cloudflare Workers Builds runner — Ubuntu 22.04 baseline)
Node: 25.9.0
Bun: 1.3.13 (also reproduced under pnpm 10)

Used Package Manager

bun (also reproduces with pnpm and npm — package manager is not load-bearing)

Validations

• Read the Contributing Guidelines.
• This issue is about Vite+'s docs / known-issue surfacing, not the rolldown bug itself (which is already tracked in fix(chunk-optimizer): pick dominator for runtime placement to avoid cycles rolldown/rolldown#9164).
• Confirmed there is no existing docs / tracking issue covering [Bug]: (regression) circular import generated when using static import and dynamic import rolldown/rolldown#9161, Circular runtime helper import between entry chunk and code-split CJS chunk causes "e is not a function" at load (rc.17, regression from rc.15) rolldown/rolldown#9224 in this repository.