Bundler Version Compatibility Reference

This reference pins the version relationships between the major JavaScript bundlers and the Node.js runtimes and ecosystem packages they depend on: Rollup 3.x and 4.x, Vite 4 through 6, esbuild 0.19 through 0.25, and Turbopack as shipped in Next.js 13 through 15, against Node.js 18, 20, and 22. It documents the breaking changes and version conflicts that surface as engine warnings, ERR_REQUIRE_ESM failures, and peer-dependency mismatches during installs and CI. For the architectural background on why these tools couple the way they do — Vite delegating production builds to Rollup and dependency pre-bundling to esbuild — see Core Concepts of Modern Bundling, then use the matrices below to choose a known-good combination.

What This Page Pins and Why

Bundler compatibility is not a single number; it is the intersection of three constraints. First, the Node.js engine range a bundler declares — installing Vite 6 on Node 16 produces an EBADENGINE warning and unpredictable resolver behavior. Second, the internal coupling between tools: Vite bundles a specific Rollup major and a specific esbuild range, so you do not pick those independently — Vite pins them, and overriding via overrides/resolutions is where conflicts originate. Third, ecosystem peers: framework plugins (@vitejs/plugin-react, @vitejs/plugin-vue), PostCSS, and TypeScript each declare peer ranges that must overlap the bundler you chose.

Pinning matters because mismatches fail loudly in some cases (ERR_REQUIRE_ESM when a CJS config loads an ESM-only plugin) and silently in others (a Rollup major bump changing manualChunks semantics so chunks split differently with no error). The tables below give the known-good combinations and the specific traps at each boundary.

Bundler to Node.js Compatibility

Internal Coupling: What Vite Bundles

You do not select Rollup and esbuild versions for a Vite project — Vite pins them. Overriding the pinned versions is the most common self-inflicted breakage.

If you force a different Rollup major through overrides, plugin API contracts (this.emitFile, renderChunk signatures, manualChunks function arguments) may not match the version @vitejs/plugin-* packages compiled against, producing plugin X is not a function at config load.

Known Breaking Changes and Conflicts

• Vite 4 to 5: Node 14/16 dropped; CJS Node API deprecated (importing vite from a CommonJS file warns and is slated for removal). The define of process.env behavior tightened. Rollup 3 to 4 underneath changed output.manualChunks to also accept the { getModuleInfo } helper consistently.
• Vite 5 to 6: Node 18.0–18.17 excluded — the minimum is 18.18 (or 20.19/22.12 for newer sub-lines). Default build.target moved to baseline-widely-available. The legacy CJS API was removed entirely; ESM config or .mjs/.mts is mandatory.
• Rollup 3 to 4: Rewritten parser (SWC-based) and per-platform native binaries (@rollup/rollup-linux-x64-gnu, etc.). The common CI failure Cannot find module @rollup/rollup-linux-x64-gnu stems from an npm optional-dependency bug when a lockfile is reused across platforms; fix by deleting package-lock.json + node_modules and reinstalling on the target OS, or pinning the optional dep.
• esbuild 0.19 to 0.25: Each minor can introduce intentional breaking changes (esbuild does not follow semver in the 0.x range). Notable: --sources-content default handling, stricter tsconfig.json extends resolution, and keepNames interactions with class fields. Always read the esbuild changelog before bumping a minor in CI.
• Turbopack / Next 13 to 15: Turbopack was dev-only and behind --turbo in 13/14; Next 15 makes next dev Turbopack the documented default, and next build --turbo is the stabilizing build path. Plugins written for the Webpack next.config.js webpack() hook do not run under Turbopack — they require Turbopack’s turbopack/turbo config surface instead.

Peer Dependency Alignment

TypeScript ≥5.0 is assumed for moduleResolution: "bundler", which all current Vite, Rollup, and esbuild lines expect. Mismatched plugin peers surface during install as npm ERR! ERESOLVE — resolve by upgrading the plugin to the line matching your bundler rather than forcing --legacy-peer-deps.

Upgrade and Migration Notes

Upgrade Node and the bundler in the same change set when crossing a major, because the engine range moves with it: going to Vite 6 on a CI image still running Node 18.16 fails the EBADENGINE gate even though Vite 5 was fine. Bump the CI image to Node 20.19+ first, confirm node -v, then bump Vite. When the source map or chunking behavior of a deployed app must stay stable across an upgrade, validate against the guidance in Source Maps and Production Debugging — a Rollup major bump can shift chunk boundaries and therefore the .map file set your error tracker expects.

Deprecations

• Vite CJS Node API: deprecated in 5, removed in 6. Migrate config and programmatic usage to ESM.
• Rollup 2.x and 3.x: maintenance only; new plugin development targets 4.x APIs.
• esbuild --bundle without an explicit --format: still works but the inferred format changed across 0.x lines — set --format=esm explicitly.
• Next.js Webpack next build (non-Turbopack): not deprecated, but Turbopack is the forward path in Next 15; new framework features land on Turbopack first.

Related

• Core Concepts of Modern Bundling — the parent overview of how Vite, Rollup, esbuild, and Turbopack relate architecturally.
• Source Maps and Production Debugging — version-sensitive source map emit modes that change across Rollup and Vite majors.
• Understanding ESM vs CommonJS in Modern Bundlers — the module-format boundary behind the CJS API deprecations called out above.