# vitejs/vite architecture

> Architecture diagram of the GitHub repository vitejs/vite, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vitejs/vite
- Repository: https://github.com/vitejs/vite

## Overview

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: [`packages/vite/src/node/server/index.ts`](https://github.com/vitejs/vite/blob/main/packages/vite/src/node/server/index.ts) (Dev server), [`packages/vite/src/node/build.ts`](https://github.com/vitejs/vite/blob/main/packages/vite/src/node/build.ts) (Build pipeline), [`packages/vite/bin/vite.js`](https://github.com/vitejs/vite/blob/main/packages/vite/bin/vite.js) (Vite CLI), [`vitest.config.ts`](https://github.com/vitejs/vite/blob/main/vitest.config.ts) (Test infra)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Repo"]
  node_legacy["Legacy plugin<br/>plugin package<br/>[index.ts]"]
  node_create_vite["Create Vite<br/>scaffold CLI<br/>[index.ts]"]
end

subgraph group_core["Core runtime"]
  node_vite_cli["Vite CLI<br/>node runtime entry<br/>[vite.js]"]
  node_config["Config<br/>[config.ts]"]
  node_server["Dev server<br/>[index.ts]"]
  node_plugin_container["Plugin container<br/>node plugin boundary<br/>[pluginContainer.ts]"]
  node_middlewares["Middleware stack<br/>node request pipeline<br/>[base.ts]"]
  node_module_graph["Module graph<br/>node dependency graph<br/>[moduleGraph.ts]"]
  node_hmr_ws["HMR + WS<br/>node realtime sync<br/>[ws.ts]"]
  node_optimizer["Dep optimizer<br/>node prebundle<br/>[index.ts]"]
  node_build["Build pipeline<br/>node production build<br/>[build.ts]"]
  node_ssr["SSR stack<br/>node server rendering<br/>[index.ts]"]
  node_module_runner["Module runner<br/>node ESM runner<br/>[index.ts]"]
  node_client_runtime["Client runtime<br/>browser injected client<br/>[client.ts]"]
  node_shared["Shared helpers<br/>shared utilities<br/>[utils.ts]"]
end

subgraph group_support["Support surfaces"]
  node_docs["Docs site<br/>vitepress site<br/>[config.ts]"]
  node_playground["Playgrounds<br/>integration fixtures"]
  node_tests["Test infra<br/>validation suite<br/>[vitest.config.ts]"]
  node_automation["CI + release<br/>automation scripts<br/>[release.ts]"]
end

node_vite_cli -->|"loads"| node_config
node_vite_cli -->|"serve"| node_server
node_vite_cli -->|"build"| node_build
node_vite_cli -->|"ssr"| node_ssr
node_server -->|"uses"| node_middlewares
node_server -->|"delegates"| node_plugin_container
node_server -->|"tracks"| node_module_graph
node_server -->|"pushes"| node_hmr_ws
node_server -->|"consults"| node_optimizer
node_optimizer -->|"adapts"| node_plugin_container
node_build -->|"runs plugins"| node_plugin_container
node_build -->|"extends"| node_legacy
node_build -->|"uses"| node_shared
node_ssr -->|"executes via"| node_module_runner
node_ssr -->|"shares"| node_shared
node_module_runner -->|"shares"| node_shared
node_client_runtime -->|"uses"| node_shared
node_docs -.->|"documents"| node_client_runtime
node_playground -.->|"exercises"| node_server
node_playground -.->|"exercises"| node_build
node_playground -.->|"exercises"| node_ssr
node_tests -.->|"verifies"| node_server
node_tests -.->|"verifies"| node_optimizer
node_tests -.->|"verifies"| node_build
node_automation -->|"runs"| node_tests
node_automation -->|"publishes"| node_docs
node_create_vite -.->|"templates for"| node_docs
node_create_vite -.->|"consumes"| node_build

click node_vite_cli "https://github.com/vitejs/vite/blob/main/packages/vite/bin/vite.js"
click node_config "https://github.com/vitejs/vite/blob/main/packages/vite/src/node/config.ts"
click node_server "https://github.com/vitejs/vite/blob/main/packages/vite/src/node/server/index.ts"
click node_plugin_container "https://github.com/vitejs/vite/blob/main/packages/vite/src/node/server/pluginContainer.ts"
click node_middlewares "https://github.com/vitejs/vite/blob/main/packages/vite/src/node/server/middlewares/base.ts"
click node_module_graph "https://github.com/vitejs/vite/blob/main/packages/vite/src/node/server/moduleGraph.ts"
click node_hmr_ws "https://github.com/vitejs/vite/blob/main/packages/vite/src/node/server/ws.ts"
click node_optimizer "https://github.com/vitejs/vite/blob/main/packages/vite/src/node/optimizer/index.ts"
click node_build "https://github.com/vitejs/vite/blob/main/packages/vite/src/node/build.ts"
click node_ssr "https://github.com/vitejs/vite/blob/main/packages/vite/src/node/ssr/index.ts"
click node_module_runner "https://github.com/vitejs/vite/blob/main/packages/vite/src/module-runner/index.ts"
click node_client_runtime "https://github.com/vitejs/vite/blob/main/packages/vite/src/client/client.ts"
click node_shared "https://github.com/vitejs/vite/blob/main/packages/vite/src/shared/utils.ts"
click node_legacy "https://github.com/vitejs/vite/blob/main/packages/plugin-legacy/src/index.ts"
click node_create_vite "https://github.com/vitejs/vite/blob/main/packages/create-vite/src/index.ts"
click node_docs "https://github.com/vitejs/vite/blob/main/docs/.vitepress/config.ts"
click node_playground "https://github.com/vitejs/vite/tree/main/playground"
click node_tests "https://github.com/vitejs/vite/blob/main/vitest.config.ts"
click node_automation "https://github.com/vitejs/vite/blob/main/scripts/release.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_legacy,node_create_vite toneBlue
class node_vite_cli,node_config,node_server,node_plugin_container,node_middlewares,node_module_graph,node_hmr_ws,node_optimizer,node_build,node_ssr,node_module_runner,node_client_runtime,node_shared toneAmber
class node_docs,node_playground,node_tests,node_automation toneMint
```

## Components

### Repo

Vite monorepo architecture overview

- [Legacy plugin](https://github.com/vitejs/vite/blob/main/packages/plugin-legacy/src/index.ts): plugin package · Build-time compatibility layer for older browsers using legacy chunks, polyfills, and SystemJS support · `packages/plugin-legacy/src/index.ts`
- [Create Vite](https://github.com/vitejs/vite/blob/main/packages/create-vite/src/index.ts): scaffold CLI · 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](https://github.com/vitejs/vite/blob/main/packages/vite/bin/vite.js): node runtime entry · Command entry that loads config, starts dev/preview, or runs build · `packages/vite/bin/vite.js`
- [Config](https://github.com/vitejs/vite/blob/main/packages/vite/src/node/config.ts): node config/env · Loads user config, env, root, package metadata, and defaults · `packages/vite/src/node/config.ts`
- [Dev server](https://github.com/vitejs/vite/blob/main/packages/vite/src/node/server/index.ts): node dev server · Middleware-based request pipeline for HTML, static files, transforms, proxying, and host checks · `packages/vite/src/node/server/index.ts`
- [Plugin container](https://github.com/vitejs/vite/blob/main/packages/vite/src/node/server/pluginContainer.ts): node plugin boundary · Mediates resolve, load, transform, and environment-specific plugin hooks · `packages/vite/src/node/server/pluginContainer.ts`
- [Middleware stack](https://github.com/vitejs/vite/blob/main/packages/vite/src/node/server/middlewares/base.ts): node request pipeline · HTML fallback, static serving, proxy, invalid request rejection, and transform layers · `packages/vite/src/node/server/middlewares/base.ts`
- [Module graph](https://github.com/vitejs/vite/blob/main/packages/vite/src/node/server/moduleGraph.ts): node dependency graph · Tracks imported modules, invalidation, and HMR reachability · `packages/vite/src/node/server/moduleGraph.ts`
- [HMR + WS](https://github.com/vitejs/vite/blob/main/packages/vite/src/node/server/ws.ts): node realtime sync · WebSocket transport for hot updates and client notifications · `packages/vite/src/node/server/ws.ts`
- [Dep optimizer](https://github.com/vitejs/vite/blob/main/packages/vite/src/node/optimizer/index.ts): node prebundle · Scans and pre-bundles dependencies for fast dev startup and resolution · `packages/vite/src/node/optimizer/index.ts`
- [Build pipeline](https://github.com/vitejs/vite/blob/main/packages/vite/src/node/build.ts): node production build · Coordinates production bundling, output preparation, and asset plugins with Rolldown · `packages/vite/src/node/build.ts`
- [SSR stack](https://github.com/vitejs/vite/blob/main/packages/vite/src/node/ssr/index.ts): node server rendering · SSR module loading, transform, stack traces, manifest generation, and Node-like execution rules · `packages/vite/src/node/ssr/index.ts`
- [Module runner](https://github.com/vitejs/vite/blob/main/packages/vite/src/module-runner/index.ts): node ESM runner · Executes transformed ESM outside the browser with HMR-aware semantics and source maps · `packages/vite/src/module-runner/index.ts`
- [Client runtime](https://github.com/vitejs/vite/blob/main/packages/vite/src/client/client.ts): browser injected client · Injected browser-side client for HMR messaging, overlay errors, and env access · `packages/vite/src/client/client.ts`
- [Shared helpers](https://github.com/vitejs/vite/blob/main/packages/vite/src/shared/utils.ts): shared utilities · 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](https://github.com/vitejs/vite/blob/main/docs/.vitepress/config.ts): vitepress site · Documentation site with theme components, content data, and public assets · `docs/.vitepress/config.ts`
- [Playgrounds](https://github.com/vitejs/vite/tree/main/playground): integration fixtures · Feature-focused fixtures that exercise dev, build, SSR, HMR, CSS, resolve, worker, and optimizer behavior · `playground`
- [Test infra](https://github.com/vitejs/vite/blob/main/vitest.config.ts): validation suite · Vitest, package tests, and fixture-driven checks for core behavior and regressions · `vitest.config.ts`
- [CI + release](https://github.com/vitejs/vite/blob/main/scripts/release.ts): automation scripts · GitHub workflows and scripts for checks, publishing, changelog, and release automation · `scripts/release.ts`

## Connections

- 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
