How vuejs/vue-next works
1. Monorepo shape
This is a pnpm-based TypeScript monorepo for Vue 3 core. The code is split into small packages with clear boundaries: low-level shared utilities, the reactivity system, the platform-agnostic runtime, platform adapters, compilers, SSR, compatibility, and the public vue distribution package.
2. Shared foundation
packages/shared is the common utility layer used across almost every package. It holds generic helpers, feature/shape/patch flag constants, HTML escaping, prop normalization, CSS variable helpers, and DOM configuration tables. This package is the main “no-framework” dependency boundary.
3. Reactive system
packages/reactivity implements dependency tracking and updates: effect, ref, computed, watch, reactive proxies, and collection instrumentation for Map/Set/WeakMap/WeakSet. Other layers depend on it for state change propagation, but it stays independent of rendering and the DOM.
4. Runtime core
packages/runtime-core is the framework engine. It defines component instances, props/emits, lifecycle, scheduler, vnode creation, renderer orchestration, built-in components like KeepAlive, Suspense, Teleport, directives, and async component support. This is the platform-agnostic layer that turns reactive state and component definitions into render operations.
5. Platform adapter for the browser
packages/runtime-dom binds the renderer to real DOM APIs. It provides nodeOps, patchProp, DOM-specific modules for class/style/attrs/events, browser directives like vModel, vOn, vShow, and helpers such as CSS module / CSS vars support. This is where the abstract renderer becomes an actual browser UI runtime.
6. Server-side rendering
packages/server-renderer renders component trees to strings and streams. It includes SSR helpers for attributes, slots, lists, teleports, suspense, directives, and interpolation. Its data flow is from vnode/component trees to HTML output, with streaming support for Node/server environments.
7. Compiler pipeline
packages/compiler-core is the generic compiler pipeline: tokenizer, parser, AST transforms, expression handling, scope tracking, and code generation. packages/compiler-dom specializes that pipeline for browser templates by adding HTML parsing options and DOM-oriented transforms like vHtml, vText, vModel, vShow, style handling, and HTML nesting validation. packages/compiler-ssr specializes the compiler for SSR code generation.
8. Single-file component compilation
packages/compiler-sfc handles .vue SFCs end-to-end. It parses SFC blocks, compiles <script> / <script setup>, compiles styles with scoping and CSS variable injection, and compiles templates via the template compiler. This is the main entry from authoring .vue files into runtime-ready JavaScript and CSS artifacts.
9. Public distribution package
packages/vue is the user-facing package that re-exports the runtime, compiler SFC entrypoints, JSX runtime, and server-renderer entrypoints through package subpaths. It also includes examples and end-to-end tests, so it acts as the assembled product rather than a separate implementation layer.
10. Compatibility layer
packages/vue-compat provides Vue 2 compatibility on top of the Vue 3 core. It adapts runtime and compiler behavior for legacy APIs such as filters, global configuration, functional components, and v-model differences. Architecturally, it is a shim layer that sits above the core runtime/compiler, not a separate renderer.
11. Testing and host abstractions
packages/runtime-test is a minimal host renderer used to test renderer behavior without the browser. Each major package also has its own unit tests and snapshots, while packages/vue/__tests__/e2e covers integration scenarios like hydration, transitions, SVG, and custom elements. This test structure mirrors the runtime boundaries.
12. Build and release tooling
The repo uses Rollup for library builds, Vitest for tests, ESLint/Prettier for quality, and GitHub Actions for CI/release automation. scripts/ contains build, dev, size, treeshaking, and release tasks. These tools shape how packages are compiled and published, but they do not change the runtime architecture.
13. Typical data flow
In the main client path, a .vue SFC is parsed by compiler-sfc, compiled by compiler-core/compiler-dom, then executed by runtime-core and mounted through runtime-dom into the browser. In the SSR path, the same component model is compiled or rendered through SSR-specific compiler/runtime code and emitted by server-renderer as HTML.
14. Diagram boundaries to emphasize
The key architectural seams are: shared utilities vs framework logic; reactive state vs rendering; renderer core vs platform adapters; client compiler vs SFC compiler vs SSR compiler; and modern Vue core vs compat shim. These are the most important boundaries for an accurate architecture diagram.
Main entry points: shared shared · runtime-core runtime-core · compiler-core compiler-core · compiler-sfc compiler-sfc
Components 15
Foundation
Cross-cutting shared utilities and the standalone reactivity system.
- shared · Common helpers, flags, HTML escaping, prop normalization, and DOM tables used across the repo.
packages/shared - reactivity · Dependency tracking, refs, computed values, effects, and collection reactivity.
packages/reactivity
Runtime
Core renderer, platform adapters, SSR, and compatibility layer.
- runtime-core · Platform-agnostic component system, scheduler, vnode model, and renderer orchestration.
packages/runtime-core - runtime-dom · Binds the core renderer to DOM operations, prop patching, and browser directives.
packages/runtime-dom - server-renderer · Renders component trees to strings and streams for server environments.
packages/server-renderer - vue-compat · Vue 2 compatibility layer built on top of the Vue 3 core runtime and compiler behavior.
packages/vue-compat
Compiler
Template, DOM, SSR, and SFC compilation pipeline.
- compiler-core · Shared parsing, transforms, scope tracking, and code generation pipeline.
packages/compiler-core - compiler-dom · Browser template specialization with DOM-specific transforms and parsing options.
packages/compiler-dom - compiler-ssr · SSR-specific compiler transforms and code generation for server rendering.
packages/compiler-ssr - compiler-sfc · Parses and compiles .vue single-file components across script, style, and template blocks.
packages/compiler-sfc
Distribution
Public entrypoints and assembled package surface.
- vue · User-facing distribution package that re-exports runtime, compiler, JSX, and SSR entrypoints.
packages/vue
Tooling
Build, test, and host abstraction layers.
- runtime-test · Minimal host renderer used to exercise renderer behavior without the browser.
packages/runtime-test - playground · Interactive SFC playground and browser demo for authoring and debugging.
packages-private/sfc-playground - template explorer · Browser explorer for template compilation behavior and compiler options.
packages-private/template-explorer - vite debug · Small Vite-based debug app for local runtime and build investigation.
packages-private/vite-debug
Connections 23
- reactivity → runtime-core: state · Reactive effects and refs drive component updates and rendering.
- shared → reactivity: helpers · Reactivity uses shared constants and utility helpers.
- shared → runtime-core: helpers · Runtime core relies on shared flags, normalization, and generic helpers.
- shared → runtime-dom: dom config · DOM adapter consumes shared attribute, tag, and CSS helper tables.
- shared → compiler-core: utils · Compiler core uses shared utilities for generic helper behavior.
- shared → compiler-dom: html tables · DOM compiler extends the shared compiler with browser-specific parsing data.
- shared → compiler-sfc: css/helpers · SFC compiler uses shared utilities for style and template processing.
- compiler-core → compiler-dom: base pipeline · DOM compiler builds on the generic parser, transform, and codegen pipeline.
- compiler-core → compiler-ssr: base pipeline · SSR compiler reuses the generic compiler pipeline with SSR-specific transforms.
- compiler-core → compiler-sfc: template compile · SFC template compilation delegates to the core compiler pipeline.
- runtime-core → runtime-dom: renderer host · Browser runtime binds the platform-agnostic renderer to DOM operations.
- runtime-core → server-renderer: SSR render · Server renderer consumes the core component and vnode model.
- compiler-dom → compiler-sfc: template compile · SFC template compilation uses the DOM-specialized compiler for browser output.
- compiler-ssr → server-renderer: ssr codegen · SSR compiler output feeds server-side rendering paths.
- runtime-core → vue-compat: legacy runtime · Compat layer adapts core runtime behavior for Vue 2 APIs.
- compiler-core → vue-compat: legacy compile · Compat layer also patches compiler behavior for legacy template semantics.
- runtime-dom → vue: browser entry · Public package exposes the browser runtime through package entrypoints.
- server-renderer → vue: ssr entry · Public package re-exports server-renderer entrypoints.
- compiler-sfc → vue: sfc entry · Public package exposes SFC compiler entrypoints and related subpaths.
- runtime-core → runtime-test: host tests · Test host mirrors renderer contracts for runtime-core validation.
- compiler-sfc → playground: authoring · Playground exercises SFC parsing and compilation in the browser.
- compiler-dom → template explorer: inspect · Template explorer targets the DOM compiler pipeline.
- runtime-dom → vite debug: debug runtime · Debug app is used to probe browser runtime and build behavior.