Bundled dev mode design doc and Road Map

Bundled dev mode was previously called as "Full Bundle Mode".

Background and Motivation

Vite is known for its unbundled dev server approach, ...
However, as projects scale in size and complexity, two main challenges have emerged:

1. Development/Production inconsistency: ...
2. Performance degradation during development: ...

With the Rolldown integration, we have an opportunity to unify the development and production experiences while maintaining Vite's signature performance. A Full Bundle Mode would allow serving bundled files not only in production but also during development, combining the best of both worlds:

• Fast startup times even for large applications
• Consistent behavior between development and production
• Reduced network overhead on page refreshes
• Maintained efficient HMR on top of ESM output

Quoted from Rolldown Integration | Vite

User Guide

Q. As a user, can I use bundled dev mode now?
A. Only if your app does not use any SSR related features from Vite and the third party plugins are compatible. Third party plugins might be compatible, but we don't expect all to work. We'll be publishing plugin author guides in the future.

Q. How can I enable bundled dev mode?
A. You can enable it by experimental.bundledDev option or by passing --experimental-bundle flag.

Q. Does bundled dev mode bundle my entire app when the dev server starts?
A. No. Bundled dev mode uses lazy bundling (a.k.a. lazy compilation): on startup it only bundles what's needed to render the page the browser actually requests, and compiles the remaining modules on demand as they're imported. This is what keeps startup non-blocking even for large apps because bundling the whole app up front would reintroduce the slow cold starts that Vite's unbundled dev server was designed to avoid. It's enabled by default, so you don't need to configure anything.

Q. Can I disable lazy bundling?
A. You normally shouldn't need to, but it can be turned off. You can set build.rolldownOptions.experimental.devMode.lazy to opt out for debugging purposes:

import { defineConfig } from 'vite'

export default defineConfig({
  experimental: {
    bundledDev: true,
  },
  build: {
    rolldownOptions: {
      experimental: {
        devMode: {
          lazy: false,
        },
      },
    },
  },
})

Key Changes in Mental Models

Since bundled dev mode bundles the files, there will be some changes in the mental models.

• The served file structure would be different from the project files.
  • e.g. new URL("./foo.png", import.meta.url) should be rewritten to new URL("../relative-path/to/output/foo.png", import.meta.url)
  • Some of Vite's internal plugins utilize the fact that the file structure is preserved and skips the rewrite in development. But this won't be possible. Probably some of the frameworks / plugins that only runs in dev assume that.
• Importing a random file is not easily possible.
  • This is because the entrypoint files are only exposed from the files. Technically, we can re-generate the bundle when a non-entrypoint file is imported, but this is not implemented currently.
  • For SSR, this is how it is written in Vite docs (link). We have not considered how to make bundled dev mode work with SSR yet.
• Transforming a single module is not possible.
  • Technically, this is possible by exposing the functionality from Rolldown. But because the lifecycle of the plugins are different, it is difficult to expose without a big change.
• Output Generation Hooks are called for the initial bundle generation.
  • For file changes that can be applied by HMR, Vite generates a HMR patch file similar to unbundled mode. But for the patch files, the output generation hooks are not called.
• Dependency Optimizer does not run in bundled dev mode.

Roadmap

Work is sequenced as a series of experimental releases and is subject to frequent adjustment as things progress.

Checked items are complete; unchecked items are planned or in progress.

Phase 1: Basic CSR support

Goal: ship the first experimental release for Vite which is usable for client side rendering apps
Target date: 2026-06-22

• Option to opt-in to bundled dev
• Make the initial bundle generation work for all internal plugins: skipping non-needed ones
• Make the HMR patch file generation work for important internal plugins: updating the URL rewrite logics, watch files properly
• Serve the bundled files
• Lazy bundling implementation: Lazy bundling is a feature to defer the bundling of the modules imported behind dynamic imports until it is actually executed. This helps when you have a large app each page separated by dynamic imports.
• Reliable HMR & module resolution
• Graceful error handling in dev

Feedbacks are welcome in the feedback discussion!

Phase 2: Complete CSR support

Goal: stabilize for real-world projects beyond the basic scenario. Land the HMR refactor that unblocks plugin support, get incremental rebuilds correct, and expand the support for advanced features like globs.
Target date: 2026-09-10

• Introduce input option (vite#22642): For full bundle mode, the entrypoint has to be specified. Currently, we use build.rollupOptions.input, but this is not intuitive for the users.
• Correct & efficient incremental rebuilds: Currently the implementation of rebuilds are a bit unorganized.
• HMR boundary calculation refactor: Currently the HMR calculation is done in the server. But it turned out that this has a problem. We plan to move the HMR calculation to the client. This blocks the plugin support.
• Investigate supporting hotUpdate / handleHotUpdate, or whether a different mechanism fits.
• HMR partial-accept support (experimental.hmrPartialAccept)
• Skip HMR / reload when the output doesn't change: Vite currently always triggers HMR / reload even when the output doesn't change. With bundled dev mode, this should be relatively easy to implement.
• Plugin / framework author guide: Held until the HMR refactor settles the plugin model, so authors only have to adapt once.
• Expose the watcher options on the Vite side
• Rebuild when tsconfig.json changes
• Proper import.meta.glob support: This requires watching directories, which does not have an API that can be used in plugins.
• Align transformIndexHtml in unbundled mode to full bundle mode / build (vite#20374)
• Fix the this.emitFile memory leak (See rollup#6095)
• Make the HMR patch file generation work for all internal plugins: updating the URL rewrite logics, watch files properly
• Make all playground in Vite repo work with bundled dev mode
• In Rolldown tests, track memory usage to guard against leaks
• Make FBM work on StackBlitz

Phase 3: CSS HMR & template coverage

Goal: deliver proper CSS HMR and validate FBM across all create-vite templates.
Target date: 2026-11-12

• Proper CSS HMR: Currently reuses Vite's existing CSS HMR approach.
• Framework & template coverage: Test all templates in create-vite

Phase 4: Server environments

Goal: extend full-bundle mode beyond SPAs to server / SSR environments.
Target date: unknown at this point

TBD

• initial PR: vite#21626
• API implications, from early notes (the concrete design may differ now that a prototype exists):
  • ViteDevServer.ssrLoadModule / env.runner.import: Since importing a random file is not easily possible, these APIs need to change (or Rolldown needs to improve that part). One option is to restrict them to entrypoint files. Another way is to generate the bundle on the fly.
  • ViteDevServer.pluginContainer / env.pluginContainer: difficult for the same reason as "Transforming a single module is not possible."
  • ViteDevServer.transformRequest / env.transformRequest: difficult for the same reason as "Transforming a single module is not possible."
  • ViteDevServer.moduleGraph / env.moduleGraph: a similar functionality is exposed from this.getModuleInfo; we can add the lacking functionality there.

High Level Explanation of how full bundle mode may work with the module runner

High Level Explanation of how full bundle mode may work with the module runner

1. Vite Dev Server generates bundled files and stores it in memory
2. Frameworks calls ViteDevServer.runner.dispatchFetch(entry)
3. The environment calls ModuleRunner.import(bundledFileEntry) on the remote runtime
4. The module runner asks the environment for the bundled file entry and executes it
5. A user changes a file
6. Vite Dev Server generates a HMR patch file for it and stores it in memory
7. The environment sends the HMR event to the remote runtime
8. The module runner asks for the HMR patch file and executes it

The difference is that the environment converts entry to bundledFileEntry.

Later

Deferred until after the HMR refactor; needs a feasibility pass (pros / cons / unknowns) before it's scheduled.

• One-pipeline model: fold the HMR/lazy codegen into the real build pipeline so asset URLs resolve chunk-independently, closing the HMR asset-resolution gap (404s on import x from './x.png' or new URL('./x', import.meta.url) inside patches). Expected to touch fewer plugins than the HMR refactor.
  • Trade-off: requires a dev-mode base / publicPath concept (today Vite-plugin-only); the lasting target is truly incremental HMR through the real render stage.

Plugin Compatibility Notes

Collapsed as it's not stable yet.

Details

• ViteDevServer.waitForRequestsIdle: this API does not work with full bundle mode and does not make sense with it
• Plugins that relied on the file structure being preserved need to rewrite the URLs for full bundle mode.
  • To achieve this, Vite forces the output chunks / assets to be put in a pre-defined structure so that the output URL / path can be calculated without actually generating the chunks/assets.
    • For example, all chunks are served below chunks/*.
    • Without this enforcement, the output URL will be unknown at transform hook and would require renderChunk hook which is not called for HMR patch files. Also, running renderChunk hooks of JS plugins are slow.
• Plugins now have to watch the files and register the dependencies properly.
  • In unbundled mode, refreshing the page always fetches the latest content. But in full bundle mode, the content is not updated unless the bundle is regenerated or a HMR patch file is generated. To trigger either of them, the plugin has to call this.addWatchFile to register the dependencies properly.
  • For some plugins, registering the dependencies is not possible (e.g. need to watch a directory like import.meta.glob requires). This will be tackled in the next phase.
• It is impossible to import a non-entry file from a file that is not included in the bundle. This can be solved by using a virtual module instead.

Current Status

Phase 1 (basic CSR support) is shipped. Work is now focused on Phase 2 (complete CSR support). Phase 4 (server environments) is on the PoC state.

[sapphi-red]

API consideration document

Copied from my docs, which was written a while ago to plan the whole road map.
Note that some parts might be outdated.

---

Required API changes

Ones with concrete ideas

• add entrypoint (input): needs to specify an entrypoint for full bundle mode, probably migrate from build.rollupOptions.input
  • the HMR client (@vite/client) should be always imported by the entrypoint for backend integration
  • should support options.isEntry for resolveId hook
    • so that the import for @vite/client and for plugin-react can inject it
• ViteDevServer.ssrLoadModule / env.runner.import: only support files specified by input? or generate the bundle on-the-fly
  • TODO: do we need an ability to add entry later? For example, when a route is added and all routes are an entry
  • to load a component for each route (astro code, sveltekit code1, sveltekit code2, waku code)
    • astro maps each route to the build file in build (code)
• ViteDevServer.waitForRequestsIdle: remove it, no use and probably no need

Ones without concrete ideas and needs further consideration

These are probably difficult to support as-is.

• on-demand entry points
  • to load each routes (react-router code)
    • we need to add a way to add entry dynamically (this API does not exist in rollup)
    • probably possible to workaround by using a virtual module that imports all entries
• hotUpdate / handleHotUpdate: is this possible to support?
  • Used by the internal import.meta.glob plugin to re-evaluate the file including import.meta.glob when a new file matches the glob (code)
    • This is not possible by this.addWatchFile because watching a glob pattern is not supported by that. This is also not possible by shouldTransformCachedModule and there's no way to trigger the rebuild by a plugin
    • A similar code exists in nuxt (code)
  • to only run some parts of the HMR so that only the changed part is run (plugin-vue code, plugin-svelte code, astro code)
    • this is probably to preserve state
  • to update the importer module when the importee is a self-accept module (vitepress code)
    • for example, when index.md inlines Foo.vue as a snippet and Foo.vue is also imported by index.md, editing Foo.vue only triggers HMR for the component and the snippet is not updated because Foo.vue is a self-accept module. Vitepress's code adds index.md as a HMR boundary so that both index.md and Foo.vue is updated
    • (we have a similar problem with tailwindcss)
  • For some cases, we should encourage people to use watchChange hook
    • to reload when some files for backend (e.g. .php, .blade) or config are changed (plugin-cloudflare code, waku code, vitepress code)
    • to reload the browser when a module only imported on SSR module graph is changed (astro code)
    • to re-evaluate code on browser when a SSR module is changed (nuxt code, react-router code, waku code1, waku code2)
  • https://github.com/search?q=handlehotUpdate+NOT+is%3Afork&type=code&p=1
• ViteDevServer.pluginContainer / env.pluginContainer
  • to resolve an ID to browser URL (astro code)
    • this won't be needed with full-bundled mode, it should be added to the entry instead
  • to transform a file into JS so that it's statically analyzable (react router code)
    • the information extracted by the static analysis is used to determine how to do the HMR
    • maybe possible to migrate to this.load by moving the react-router specific HMR filtering logic on browser side
  • to resolve an ID (waku code)
    • (not sure why this is needed, also not sure how to migrate this to full-bundled mode)
  • to crawl the entire module graph (waku code)
    • (not sure why this is needed, also not sure how to migrate this to full-bundled mode)
  • Vitest uses it in multiple places (code search)
  • vite-node uses it
    • react-router, nuxt, vitest uses it
• ViteDevServer.moduleGraph / env.moduleGraph
  • traverses the module graph to obtain information (astro code)
    • in build, it uses placeholder in transform hook and replaces that placeholder after build
  • traverses the module graph to get meta in all imported module (astro code)
    • (not sure what it's used for and how it's handled in build)
  • traverses the module graph to set meta (astro code)
    • (not sure what it does)
  • traverses the module graph to collect the imported styles (react-router code, sveltekit code)
    • probably not needed for full bundle mode as that information already exists in the output
  • to invalidate modules in handleHotUpdate / watchChange (described above)
  • to invalidate modules in other cases (astro code1, astro code2, astro code 3, nuxt code1)
• ViteDevServer.transformRequest / env.transformRequest
  • used by Vitest

Other Notes

• I checked Vite core, astro, marko, nuxt, react-router, sveltekit, vite-plugin-cloudflare, waku, vitepress, vitest
• For Vitest, I think it would be better for hiroshi to take a brief look how much it's difficult to migrate for both unit tests and browser mode
• Output Generation Hooks (e.g. renderChunk) are called only for the initial bundle
  • In other words, it's not called for the HMR-patch files
  • The code passed to renderChunk contains the HMR runtime related code (e.g. __rolldown_runtime__.registerModule)
• Need to check if workers (import w from './foo?worker') works
• Feedback on Rolldown Dev (hmr-poc branch) rolldown/rolldown#2866
• TODO: how would RSC frameworks work? would it require any APIs?

[raphamorim]

Phase 2 hotUpdate design: please include defer-and-replay (gating) semantics — a large-scale production use case

Context: we run Lovable, where each user project is a Vite dev server driven by an AI agent (millions of projects; the active fleet is largely React + TanStack Start, currently on Vite 8.1). We've had bundled dev running behind a feature flag since 8.1 and the startup wins are real for us. This is input for the Phase 2 item "Investigate supporting hotUpdate / handleHotUpdate, or whether a different mechanism fits", from a consumer with an unusual but — given the growth of agent-driven development — increasingly common requirement.

The requirement: suppress-and-replay, not just observe-and-filter. While the agent is mid-edit, files change many times in quick succession and routinely pass through broken intermediate states (half-written modules, transiently unresolved imports). The preview must NOT apply those updates; when the batch completes, we flush — granular updates preferred, full reload as fallback. The flush trigger comes from outside the browser (our backend calls an endpoint on the dev server when the agent's batch is done).

In unbundled Vite this is sanctioned and works: hotUpdate returns [] to swallow updates, we queue the modules, and on flush we re-emit via environment.hot.send. Clean, and stable for us across Vite 5–8.

In bundled dev there is no equivalent, so today we gate at the transport layer: wrap the HMR WebSocket send path and hold back the patch-fetch responses (/hmr_patch_N.js) until flush, buffering vite:bundled-dev:reload-needed events for replay. It works, but it is coupled to internals (patch URL shape, event names, WS framing) that Phases 2–3 will legitimately churn — exactly the kind of ecosystem workaround a design phase can obsolete.

What we'd like the Phase 2 mechanism to support, whatever shape it takes (whether that's #22956's adapter or something else):

1. Deferral — a plugin (or server API) can hold HMR emission (patches and reload-needed events) without side effects on the build itself; only delivery is held.
2. Coalescing — N held patches collapse to the minimal set on release (the patch sequence is stateful, so "replay the queue verbatim" is likely wrong; the engine knows how to coalesce, plugins don't).
3. Escalation rule — a reload-needed event arriving inside a held window defines what happens on release (our vote: release = single full reload in that case).
4. Programmatic release — triggerable from server-side code (middleware / plugin API), not only from a browser client.
5. Error containment — a held window that includes a failed build should release to the last-good state and surface the error, not white-screen.

Points 1+4 alone would let us delete the transport-layer workaround; 2+3 are what make it correct rather than merely possible.

Related, filed separately: #23314 — in current releases, hotUpdate is invoked without environment injection under bundled dev (this.environment undefined; hotUpdate is not in ROLLUP_HOOKS), which breaks plugins using the documented this.environment pattern (real-world: TanStack/router#8062), and the swallowed throw degrades to stale output until restart. Whatever Phase 2 decides about hotUpdate semantics, invoking the hook with a bare context is the one interim option that serves nobody.

Also registering interest in the Phase 2 import.meta.glob item — our templates use it, and it is currently the main reason projects fall back to classic dev under our flag.

We're happy to test design candidates against a large real-world fleet, and to contribute implementation work.

[sapphi-red]

Hi 👋 Thanks for the feedback.

The event consolidation exists in Rolldown, so I guess we need to let the watch events to be queued until triggered. cc @h-a-n-a
By the way, does waiting in the watchChange or hotUpdate hook work?