Vue Core — Admin & Architecture Guide

This guide is for the people who build, ship, and contribute to Vue itself — maintainers, contributors, framework integrators, and architects who need to understand how the vuejs/core monorepo is structured, how it builds, and how its internals actually work. It is written from the source at version 3.5.35, commit 86ad076.

If you are using Vue to build an application, read the User Guide instead. This document assumes you are working on Vue or integrating its packages at a deep level.

1. Executive Summary

vuejs/core is a pnpm monorepo that produces the vue npm package and a family of @vue/* packages. The codebase is written in TypeScript, built with Rollup + esbuild, tested with Vitest, and organized so that each layer of the framework — reactivity, runtime, compiler, server renderer — is an independently publishable package with a clear dependency direction.

The architectural throughline: the compiler turns templates into render functions; the reactivity system tracks state; the runtime renders and patches the DOM (or any custom target) in response to reactive change. Each concern is a separate package so it can be tree-shaken, reused (e.g. @vue/reactivity standalone), or retargeted (custom renderers, SSR, the test renderer).

2. Repository Architecture

2.1 Monorepo layout

core/
├── packages/                    Published packages
│   ├── reactivity/              @vue/reactivity   — standalone reactivity system
│   ├── shared/                  @vue/shared       — internal utilities (private)
│   ├── runtime-core/            @vue/runtime-core — renderer, component model (platform-agnostic)
│   ├── runtime-dom/             @vue/runtime-dom  — DOM-specific renderer + browser APIs
│   ├── runtime-test/            @vue/runtime-test — test renderer (private)
│   ├── compiler-core/           @vue/compiler-core— platform-agnostic template compiler
│   ├── compiler-dom/            @vue/compiler-dom — DOM-specific compiler transforms
│   ├── compiler-sfc/            @vue/compiler-sfc — single-file-component compiler
│   ├── compiler-ssr/            @vue/compiler-ssr — SSR codegen (private)
│   ├── server-renderer/         @vue/server-renderer — SSR runtime
│   ├── vue/                     vue              — the umbrella package (full + runtime builds)
│   └── vue-compat/              @vue/compat      — Vue 2 migration build
├── packages-private/            Non-published tooling & tests
│   ├── sfc-playground/          The online SFC playground (Vite app)
│   ├── template-explorer/       Compiler output explorer (Monaco)
│   ├── dts-test/                Type-level tests (tsc-checked)
│   ├── dts-built-test/          Tests against rolled-up .d.ts
│   └── vite-debug/              Vite integration debug harness
├── scripts/                     Build/dev/release Node scripts
├── changelogs/                  Generated changelog history
├── rollup.config.js             Main build configuration
├── rollup.dts.config.js         .d.ts rollup configuration
├── tsconfig.json / .build.json  TypeScript configuration
├── vitest.config.ts             Test configuration (4 projects)
└── eslint.config.js             Lint rules (with codebase-specific bans)

2.2 Package dependency graph

The dependency direction is strictly one-way (lower layers never import higher layers):

                         shared  (leaf — depended on by everything)
                           ▲
        ┌──────────────────┼──────────────────────────┐
   reactivity         compiler-core                     │
        ▲                  ▲                            │
   runtime-core       compiler-dom                      │
        ▲                  ▲          ▲                 │
   runtime-dom        compiler-ssr   compiler-sfc ──────┤
        ▲                  ▲          ▲                 │
        └──────► vue ◄─────┴──────────┘                 │
                  ▲                                      │
            server-renderer ────────────────────────────┘

Note

@vue/shared is private to the framework (it has no dependencies of its own and is never meant to be installed directly by users). It contains the small utilities (extend, isObject, hasChanged, NOOP, camelize, normalizeClass, patch/shape flags, etc.) reused across every layer to keep bundle size down — note the ESLint rule that bans object spread in favor of extend from this package.

2.3 The vue umbrella package and its entries

The vue package re-exports @vue/runtime-dom and adds the in-browser compiler. Its exports map publishes several subpaths:

The umbrella's packages/vue/src/index.ts registers the runtime compiler via registerRuntimeCompiler(compileToFunction) — this is the mechanism that lets the full build compile string templates on the fly, while the runtime-only build omits it entirely.

3. Build System

3.1 Build formats

Each package declares its target formats in package.json's buildOptions.formats. The vue package builds all seven:

3.2 rollup.config.js internals

rollup.config.js is the single source of build truth. Key behaviors:

• Target selection. It requires the TARGET environment variable (the package name) and throws TARGET package must be specified via --environment flag. if missing. scripts/build.js sets it per-package.
• Compile-time defines (resolveDefine). Every build inlines a map of constants via esbuild's define (and the @rollup/plugin-replace plugin where esbuild's literal-only rules fall short). These constants drive dead-code elimination.
• Enum inlining. scripts/inline-enums.js rewrites const enum-style values to literals at build time (the project bans const enum in source — see Coding Standards — and inlines plain enums instead).
• Externalization (resolveExternal). For Node/bundler builds, all direct deps and peer deps are externalized; for browser/global builds, deps are inlined (tree-shaken deps like source-map-js, @babel/parser, estree-walker, entities/decode are only listed to suppress warnings).
• Minification. Production browser/global builds run through an SWC-based renderChunk minify pass (compress.ecma: 2016, mangle: true, Safari 10 workaround), re-prepending the license banner.
• Tree-shaking. treeshake.moduleSideEffects: false lets bundlers drop unused exports; circular-dependency warnings are suppressed (they're expected and benign in the runtime).

3.3 Compile-time feature flags

These constants are replaced at build time. They are the closest thing Vue has to a "configuration reference" — they shape what code ends up in each bundle.

Important

The three __VUE_* flags are the only ones intended for downstream consumers to define in their bundler. The rest are resolved entirely within Vue's own build. If you ship a library that bundles Vue, define __VUE_OPTIONS_API__, __VUE_PROD_DEVTOOLS__, and __VUE_PROD_HYDRATION_MISMATCH_DETAILS__ to avoid "feature flag not defined" warnings.

3.4 Type declaration build

build-dts runs tsc -p tsconfig.build.json --noCheck to emit raw .d.ts into temp/, then rollup.dts.config.js rolls each package's declarations into a single dist/{pkg}.d.ts using rollup-plugin-dts. A custom patchTypes plugin (AST-driven, via @babel/parser + magic-string) converts re-exported types to inline exports (so VitePress/defineComponent inference works) and appends per-package type augmentations (JSX, macros). For the vue package, a copyMts plugin duplicates vue.d.ts to vue.d.mts so Node ESM and CJS both get correct types.

4. Development & Operations

4.1 npm scripts (the operational CLI surface)

The root package.json scripts are how everything is built, tested, and released:

Tip

pnpm dev <package> (e.g. pnpm dev reactivity) rebuilds one package on change — the fastest loop when working on a single layer. pnpm dev-sfc spins up the playground wired to your local build, which is the best way to exercise the full compile→render path interactively.

4.2 Git hooks and commit conventions

simple-git-hooks (installed via postinstall) wires:

• pre-commit: pnpm lint-staged && pnpm check — lints staged files (ESLint + Prettier) and runs a full type check.
• commit-msg: node scripts/verify-commit.js — enforces Conventional Commits.

lint-staged runs Prettier on *.{js,json} and ESLint --fix + Prettier on *.ts(x).

Caution

The pre-commit hook runs a full tsc --noEmit, which can take significant time on a cold cache. Do not bypass it with --no-verify unless you have separately verified types — a type regression that lands on main breaks every downstream consumer's build.

4.3 Testing architecture

vitest.config.ts defines four test projects:

The config also defines the same compile-time flags as the build (with __DEV__: true, __TEST__: true, __FEATURE_* enabled) and aliases workspace packages via scripts/aliases.js so tests run against source, not built output. Coverage uses the v8 provider over packages/*/src/**, excluding entries that are not meaningfully unit-testable (e.g. profiling.ts, featureFlags.ts, hydrationStrategies.ts, Transition*).

Note

Type-level correctness is tested separately from runtime behavior: packages-private/dts-test contains .test-d.ts(x) files checked by tsc, and dts-built-test verifies the rolled-up declarations. A change that compiles but breaks public types is caught here, not by Vitest.

5. Reactivity Internals

The reactivity system was substantially rewritten for Vue 3.5 to use a doubly-linked-list dependency graph with version counters, replacing the older Set-based dependency collection. This is the most performance-critical subsystem in the framework.

5.1 Core data structures (packages/reactivity/src/dep.ts, effect.ts)

   reactive object property              effect / computed
        (a Dep)                           (a Subscriber)
          │                                     │
          ├── subs ──► Link ◄── deps ───────────┤
          │            │  ▲                      │
          │         nextSub nextDep              │
          ▼            ▼  │                      ▼
        (more subs)   Link (more deps)

5.2 Tracking and triggering

• track(target, type, key) (called from proxy getters) finds (or lazily creates) the Dep for target[key] in targetMap, then calls dep.track(). If an effect is active (activeSub) and shouldTrack is on, it creates or reuses a Link between the dep and the active subscriber, appending it to the sub's dep-list tail.
• trigger(target, type, key, …) finds affected deps and calls dep.trigger(), which bumps dep.version and the module-global globalVersion, then notifies subscribers. Array length changes, ADD/DELETE/CLEAR operations, and Map/Set iteration keys (ITERATE_KEY, MAP_KEY_ITERATE_KEY, ARRAY_ITERATE_KEY) are handled with special cases so iteration-dependent effects re-run correctly.

5.3 The globalVersion fast path

Every reactive mutation increments globalVersion. A ComputedRefImpl records the globalVersion at its last evaluation. When a computed is read, if globalVersion hasn't changed since, it can skip dependency-checking entirely — no reactive state changed anywhere, so the cache is definitely valid. This is a cheap global short-circuit before the finer-grained per-dep version check.

5.4 Batching (effect.ts)

Notifications are batched. startBatch()/endBatch() bracket a trigger; subscribers are collected into batchedSub/batchedComputed linked lists (marked with the NOTIFIED flag) and flushed at the end of the batch — effects run in original order, computeds are processed separately. Mutating methods that change array length (push, pop, splice, etc.) wrap their work in pauseTracking() + startBatch() to avoid the infamous length-tracking infinite loop (issue #2137).

5.5 Effect flags

ReactiveEffect and ComputedRefImpl carry a bitmask (EffectFlags) instead of multiple booleans, for compactness and speed:

5.6 Proxy handlers

• baseHandlers.ts — BaseReactiveHandler (get), MutableReactiveHandler (get/set/deleteProperty/has/ownKeys), and ReadonlyReactiveHandler (blocks writes, warns in dev). The getter handles ref-unwrapping, the __v_* reactive flags (IS_REACTIVE, IS_READONLY, IS_SHALLOW, RAW, SKIP), array instrumentation, and lazy nested proxying. Four singleton handlers are exported: mutableHandlers, readonlyHandlers, shallowReactiveHandlers, shallowReadonlyHandlers.
• collectionHandlers.ts — Special handling for Map/Set/WeakMap/WeakSet, whose methods (get/set/add/delete/has/forEach/iterators) must be instrumented rather than proxied via property access. Identity-key consistency is checked in dev (the "raw and reactive versions of the same object" warning).
• arrayInstrumentations.ts — Reactive-aware versions of array methods. Iteration methods (map, filter, forEach, find, includes, indexOf, etc.) take an ARRAY_ITERATE dependency and wrap returned items in reactive proxies as needed. Identity-sensitive searches (includes/indexOf/lastIndexOf) retry with raw values so you can search by either the reactive or raw form.

5.7 Public surface vs. internal

packages/reactivity/src/index.ts exports the public API (ref, reactive, computed, watch, effect, effectScope, the type set, and the TrackOpTypes/TriggerOpTypes/ReactiveFlags enums). The Dep, Link, Subscriber, targetMap, globalVersion, and batching internals are not part of the public contract — runtime-core augments RefUnwrapBailTypes via declaration merging to teach ref-unwrapping about VNodes and component instances without creating a runtime dependency cycle.

6. Compiler & Runtime Pipeline

6.1 Compiler stages

The template compiler is a classic three-stage pipeline, split across compiler-core (platform-agnostic) and compiler-dom (browser specifics):

template string
   │  baseParse()            ── parser.ts → AST (RootNode)
   ▼
   AST
   │  transform()            ── transform.ts: node + directive transforms
   │    nodeTransforms:      transformElement, transformExpression, vIf, vFor,
   │                         vSlot, vOnce, vMemo, cacheStatic (static hoisting)…
   │    directiveTransforms:  vBind, vOn, vModel, vShow, vHtml, vText…
   ▼
   transformed AST (with codegenNode)
   │  generate()             ── codegen.ts → render function source + sourcemap
   ▼
   { code, ast, map }

• compiler-core exposes baseCompile, baseParse, transform, generate, plus every individual transform and the ErrorCodes/createCompilerError machinery. It is target-agnostic.
• compiler-dom supplies parserOptions (HTML namespaces, native tags), DOM directive transforms (v-html→transformVHtml, v-text, v-model override, v-on override, v-show, <Transition>), and stringifyStatic (turns large static subtrees into a single innerHTML string for performance). Its compile() composes these into baseCompile.
• compiler-ssr reuses the DOM parser/transforms but swaps in SSR-specific transforms (ssrTransformElement, ssrTransformComponent, ssrVIf, ssrVFor, ssrVModel, ssrVShow, CSS-var injection) and emits SSR render functions via ssrCodegenTransform.

6.2 SFC compilation (compiler-sfc)

@vue/compiler-sfc is the bridge that build tools (@vitejs/plugin-vue, vue-loader) call. Its public API:

It bundles a forked @vue/consolidate for alternative template engines and exposes babelParse, MagicString, and walk for tooling.

Note

shouldTransformRef and the old reactivity-transform are gone — compiler-sfc keeps shouldTransformRef = () => false only to avoid breaking vite-plugin-vue < 5.0 that passed reactivityTransform: true. Do not build new features on reactivity transform.

6.3 Runtime rendering (runtime-core → runtime-dom)

runtime-core is platform-agnostic. createRenderer(options) takes a set of node operations (create/insert/remove/patchProp/…) and returns a { render, createApp } pair. This is how Vue supports multiple targets:

runtime-dom lazily instantiates the renderer (ensureRenderer) so apps that only use the reactivity APIs don't pull in renderer code. createApp wraps the core app to add DOM container normalization, in-DOM template handling (full build), and dev-only checks (isNativeTag, deprecated-isCustomElement/compilerOptions guards). createSSRApp uses the hydration renderer (createHydrationRenderer) to adopt server markup instead of creating new nodes.

6.4 Hydration strategies (lazy hydration)

runtime-core exports hydrateOnIdle, hydrateOnVisible, hydrateOnMediaQuery, and hydrateOnInteraction — strategy factories for deferring hydration of async components until the browser is idle, the element is visible, a media query matches, or the user interacts. These power "islands"-style performance patterns.

7. Coding Standards & Conventions

eslint.config.js enforces several codebase-specific rules that contributors must respect:

Important

These bans exist because Vue's source is shipped to users essentially as-authored (after esbuild transpilation to ES2016). Convenience syntax that looks free in app code (spread, async/await, ?.) expands into helper functions that bloat the framework's own bundle. When in doubt, mirror the surrounding code and reach for @vue/shared helpers.

8. Security Analysis

Vue is a client/SSR library, so its security surface is about safe rendering, not network/auth.

Caution

The single most common Vue security mistake is v-html with user content. Treat every v-html, innerHTML-equivalent render path, and selector-template mount (#id) as a potential XSS vector and audit accordingly.

9. Quality, Tech Debt & Improvement Areas

These are observations grounded in the current source and the community issue tracker; they are candidate areas for contributors.

• Vapor mode is in flight. The issue tracker shows active [Vapor] / [runtime-vapor] work (e.g. #14844, #14787, #14851) — a compilation strategy that skips the virtual DOM. It is not yet a stable public API; expect churn in compiler and runtime internals around it.
• Reactivity edge cases. reactive silently no-ops on non-extensible objects (#14893) — arguably should warn. watch with immediate: true and a static source running only once (#14898) is a recurring source of confusion; documentation/DX could be improved.
• Type-level scaling. Very large prop union types can trip TS2590 ("union type too complex," #10514). Components with hundreds of literal-union prop values need workarounds.
• Transition/animation gaps. <Transition> doesn't animate visibility (#2531); v-show enter animations differ from v-if/v-for in <TransitionGroup> (#14894).
• SSR hydration robustness. Recent fixes around Teleport + Suspense unmount (#14876) and redundant mismatch logging (#14855) indicate the Teleport/Suspense/hydration intersection is a complex, regression-prone area worth additional test coverage.
• Compiler crash hardening. Edge-case template inputs (<template v-for> + non-identifier :key + v-memo, #14859) have produced compiler crashes; fuzz-style template tests would help.

Note

Because Vue has no staging environment between main and published releases, the test matrix (unit + jsdom + e2e + dts) is the safety net. Any internals change to reactivity, the renderer, or the compiler should land with tests at the seam it touches.

10. Quick Reference

Package → npm name

Common contributor commands

pnpm install                 # bootstrap (pnpm enforced)
pnpm dev reactivity          # watch-build one package
pnpm dev-sfc                 # run the SFC playground on local source
pnpm test-unit               # unit tests
pnpm test --project unit-jsdom   # DOM tests
pnpm check                   # full type check
pnpm lint                    # eslint
pnpm build vue               # production build of the vue package
pnpm build-dts               # build rolled-up type declarations
pnpm size                    # measure bundle sizes

Key source files for orientation