How vitejs/vite works
1. This repository is the Vite monorepo. The primary runtime product is packages/vite, which ships the Vite CLI, dev server, build pipeline, SSR utilities, client runtime, and type definitions. The other published packages are @vitejs/plugin-legacy and create-vite.
2. The core architecture is split between a Node.js server-side toolchain and a browser client runtime. The Node side handles config loading, dependency optimization, file watching, plugin execution, SSR, preview server, and production build orchestration. The browser side is a small injected client (src/client) that handles HMR messaging, error overlays, and env access.
3. Development mode centers on the dev server in packages/vite/src/node/server. Incoming requests pass through middleware layers for HTML transformation, static file serving, proxying, host checks, invalid request rejection, and on-demand module transformation. The server maintains a module graph and pushes HMR updates over WebSocket.
4. Vite’s plugin system is a major boundary. Core transforms and asset handling live in packages/vite/src/node/plugins, while pluginContainer.ts and related server code mediate plugin hooks, resolution, load/transform behavior, and environment-specific execution. Plugins are the extension point that connects framework-specific behavior to the core pipeline.
5. Dependency optimization is a separate pre-runtime subsystem in src/node/optimizer. It scans source graphs, resolves package entry points, converts plugin behavior for optimization, and pre-bundles dependencies for faster dev startup. This subsystem feeds the dev server’s resolution and import analysis paths so bare imports resolve quickly.
6. Production build is coordinated from src/node/build.ts and uses Rolldown as the bundling engine, with additional plugins for CSS, assets, manifest generation, license extraction, preload behavior, terser/minification compatibility, and output preparation. The build path is distinct from dev: it produces static artifacts rather than serving modules on demand.
7. SSR is a dedicated subsystem under src/node/ssr plus shared helpers in src/shared. It includes SSR module loading, transform logic, stack trace rewriting, runtime runners, and manifest generation. SSR has its own resolution/externalization rules and its own test fixtures because it must execute modules in Node-like environments while respecting Vite transforms.
8. The “module runner” code under src/module-runner supports executing transformed ESM with HMR-aware behavior outside the browser, including source map handling and import metadata resolution. This is an important internal boundary because it allows server-side execution to reuse much of the same module semantics as the browser/dev server.
9. packages/plugin-legacy wraps Vite build output for older browsers. It sits on top of the main build pipeline and adds legacy chunking, polyfills, and SystemJS-related compatibility paths when required. It is deliberately isolated as a plugin package rather than being part of the core runtime.
10. packages/create-vite is the project scaffolding subsystem. Its CLI selects from template folders for frameworks such as React, Vue, Svelte, Solid, Qwik, Lit, and vanilla variants. It is not part of the runtime pipeline; it generates starter apps that consume Vite.
11. docs/ is a separate VitePress site, not an application built by Vite itself. It includes custom theme components, data files for blog/team/sponsors, and deployment-related public assets. The docs site is a first-class repo subsystem because it publishes the architecture and API surface consumed by users.
12. playground/ is the integration-test surface for the repo. Each subfolder is a focused fixture app that exercises one feature area: CSS, HMR, SSR, workers, asset handling, optimization, resolution, WASM, etc. These projects are the behavioral contract for the core packages and reveal which architectural boundaries are expected to hold.
13. Test infrastructure is split across vitest configs, playground tests, and package-level unit tests under packages/vite/src/**/__tests__ and packages/plugin-legacy/src/__tests__. The repo uses these fixtures to validate edge cases around resolution, transforms, sourcemaps, HMR, SSR, and environment-specific behavior.
14. CI/release tooling lives under .github/ and scripts/. GitHub Actions run checks, previews, releases, issue automation, and security linting. The scripts directory contains release/publish helpers and changelog merging, which affect packaging and publication rather than runtime behavior.
15. From an architecture-diagram perspective, the key boundaries are: user source code in the middle; Vite’s Node server/optimizer/build/SSR stack around it; a small browser client injected into served pages; and supporting surfaces for templates, docs, tests, and release automation around the core product.
Main entry points: index.ts Dev server · build.ts Build pipeline · vite.js Vite CLI · vitest.config.ts Test infra
Components 19
Repo
Vite monorepo architecture overview
- Legacy plugin · Build-time compatibility layer for older browsers using legacy chunks, polyfills, and SystemJS support
packages/plugin-legacy/src/index.ts - Create Vite · Project scaffolder that selects framework templates for new apps
packages/create-vite/src/index.ts
Core runtime
Published runtime packages and main execution paths
- Vite CLI · Command entry that loads config, starts dev/preview, or runs build
packages/vite/bin/vite.js - Config · Loads user config, env, root, package metadata, and defaults
packages/vite/src/node/config.ts - Dev server · Middleware-based request pipeline for HTML, static files, transforms, proxying, and host checks
packages/vite/src/node/server/index.ts - Plugin container · Mediates resolve, load, transform, and environment-specific plugin hooks
packages/vite/src/node/server/pluginContainer.ts - Middleware stack · HTML fallback, static serving, proxy, invalid request rejection, and transform layers
packages/vite/src/node/server/middlewares/base.ts - Module graph · Tracks imported modules, invalidation, and HMR reachability
packages/vite/src/node/server/moduleGraph.ts - HMR + WS · WebSocket transport for hot updates and client notifications
packages/vite/src/node/server/ws.ts - Dep optimizer · Scans and pre-bundles dependencies for fast dev startup and resolution
packages/vite/src/node/optimizer/index.ts - Build pipeline · Coordinates production bundling, output preparation, and asset plugins with Rolldown
packages/vite/src/node/build.ts - SSR stack · SSR module loading, transform, stack traces, manifest generation, and Node-like execution rules
packages/vite/src/node/ssr/index.ts - Module runner · Executes transformed ESM outside the browser with HMR-aware semantics and source maps
packages/vite/src/module-runner/index.ts - Client runtime · Injected browser-side client for HMR messaging, overlay errors, and env access
packages/vite/src/client/client.ts - Shared helpers · Shared HMR, SSR, transport, and utility code reused across Node and client paths
packages/vite/src/shared/utils.ts
Support surfaces
Docs, playgrounds, tests, and release automation
- Docs site · Documentation site with theme components, content data, and public assets
docs/.vitepress/config.ts - Playgrounds · Feature-focused fixtures that exercise dev, build, SSR, HMR, CSS, resolve, worker, and optimizer behavior
playground - Test infra · Vitest, package tests, and fixture-driven checks for core behavior and regressions
vitest.config.ts - CI + release · GitHub workflows and scripts for checks, publishing, changelog, and release automation
scripts/release.ts
Connections 28
- Vite CLI → Config: loads · CLI resolves user config and mode before invoking the chosen command
- Vite CLI → Dev server: serve · Starts the development server in serve mode
- Vite CLI → Build pipeline: build · Runs production build orchestration
- Vite CLI → SSR stack: ssr · Exposes SSR-related CLI flows and utilities
- Dev server → Middleware stack: uses · Request handling is composed from middleware layers
- Dev server → Plugin container: delegates · Resolution and transforms flow through plugin hooks
- Dev server → Module graph: tracks · Server maintains graph state for invalidation and HMR
- Dev server → HMR + WS: pushes · Sends hot update payloads to connected clients
- Dev server → Dep optimizer: consults · Dev server uses optimized dependencies for fast bare-import resolution
- Dep optimizer → Plugin container: adapts · Optimization reuses or adapts plugin behavior during scanning and prebundle
- Build pipeline → Plugin container: runs plugins · Production transforms and asset handling pass through plugin hooks
- Build pipeline → Legacy plugin: extends · Legacy package wraps build output when older-browser support is needed
- Build pipeline → Shared helpers: uses · Shares constants and helpers with SSR and client-facing paths
- SSR stack → Module runner: executes via · SSR runtime uses module runner semantics for transformed ESM execution
- SSR stack → Shared helpers: shares · SSR reuses shared transforms, HMR helpers, and utility code
- Module runner → Shared helpers: shares · Runner uses shared transport, HMR, and utility abstractions
- Client runtime → Shared helpers: uses · Browser client consumes shared HMR payload and env helpers
- Docs site → Client runtime: documents · Documentation describes browser-side HMR, env, and plugin APIs
- Playgrounds → Dev server: exercises · Fixtures validate dev server middleware, HMR, and transforms
- Playgrounds → Build pipeline: exercises · Fixtures cover build output, CSS, assets, and legacy behavior
- Playgrounds → SSR stack: exercises · Fixtures cover SSR loading, externalization, and stack traces
- Test infra → Dev server: verifies · Unit and integration tests target dev server internals and request paths
- Test infra → Dep optimizer: verifies · Tests cover dependency scanning and prebundle resolution
- Test infra → Build pipeline: verifies · Tests cover build plugins, manifests, minification, and asset preparation
- CI + release → Test infra: runs · CI executes the validation suite and related checks
- CI + release → Docs site: publishes · Release and preview automation includes docs site workflows
- Create Vite → Docs site: templates for · Scaffolded apps are reflected in the docs and user-facing guides
- Create Vite → Build pipeline: consumes · Generated projects are intended to be built by the core pipeline