shared

Active contributors: Evan You, daiwei, edison

Purpose

@vue/shared is the home for environment-agnostic utilities used by both runtime and compiler packages. It exists specifically to break the rule that compiler and runtime never import each other: any constant or helper that legitimately spans both sides lives here. The package is small (16 source files, ~1,100 lines) but every other package depends on it.

Directory layout

packages/shared/src/
├── index.ts                # re-exports everything
├── general.ts              # NOOP, EMPTY_OBJ, EMPTY_ARR, extend, hasChanged, …
├── makeMap.ts              # interned-string lookup helper
├── patchFlags.ts           # PatchFlags enum + names map
├── shapeFlags.ts           # ShapeFlags enum
├── slotFlags.ts            # SlotFlags enum
├── globalsAllowList.ts     # globals safe to reference inside templates
├── codeframe.ts            # generateCodeFrame for compiler errors
├── normalizeProp.ts        # normalizeClass / normalizeStyle / normalizeProps
├── domTagConfig.ts         # isHTMLTag, isSVGTag, isMathMLTag, …
├── domAttrConfig.ts        # isBooleanAttr, isKnownHtmlAttr, …
├── escapeHtml.ts           # SSR string escaping
├── looseEqual.ts           # value equality used by v-model option lists
├── toDisplayString.ts      # how interpolations stringify
├── typeUtils.ts            # IfAny, LooseRequired, UnionToIntersection, …
└── cssVars.ts              # encode/decode for SFC CSS vars

Key abstractions

Symbol	File	Description
NOOP, NO, EMPTY_OBJ, EMPTY_ARR	packages/shared/src/general.ts	Frozen-or-not singletons used as defaults across the runtime to avoid per-call allocation.
extend	packages/shared/src/general.ts	Aliased Object.assign. Ubiquitous.
hasChanged(a, b)	packages/shared/src/general.ts	Object.is-based change detection.
makeMap(str, expectsLowerCase)	packages/shared/src/makeMap.ts	Builds a (key) => boolean from a comma-separated list. Used to test for HTML/SVG tag names, reserved props, etc.
PatchFlags	packages/shared/src/patchFlags.ts	Compiler-emitted bitmask of update kinds (TEXT, CLASS, STYLE, PROPS, FULL_PROPS, STABLE_FRAGMENT, KEYED_FRAGMENT, UNKEYED_FRAGMENT, NEED_PATCH, DYNAMIC_SLOTS, HOISTED, BAIL).
ShapeFlags	packages/shared/src/shapeFlags.ts	Renderer-side bitmask for vnode kind (ELEMENT, STATEFUL_COMPONENT, FUNCTIONAL_COMPONENT, TEXT_CHILDREN, ARRAY_CHILDREN, SLOTS_CHILDREN, TELEPORT, SUSPENSE, COMPONENT_KEPT_ALIVE, COMPONENT_SHOULD_KEEP_ALIVE).
SlotFlags	packages/shared/src/slotFlags.ts	Tracks whether slots are stable, dynamic, or forwarded.
normalizeClass, normalizeStyle, normalizeProps	packages/shared/src/normalizeProp.ts	Coerce the various accepted inputs (string, array, object) into a single canonical form.
isHTMLTag, isSVGTag, isMathMLTag	packages/shared/src/domTagConfig.ts	Tag-name predicates. Compiler-only: importing these from runtime code accidentally pulls multi-KB whitelists into every browser bundle.
generateCodeFrame	packages/shared/src/codeframe.ts	Pretty error frames for compile-time and dev-only runtime errors.
escapeHtml, escapeHtmlComment	packages/shared/src/escapeHtml.ts	SSR string escaping.
looseEqual	packages/shared/src/looseEqual.ts	Value equality for select option matching in v-model.
toDisplayString	packages/shared/src/toDisplayString.ts	The function the compiler emits inside {{ … }} interpolations.

Why it matters

Every other package imports from @vue/shared. Many of the names re-export upward — runtime-core/src/index.ts re-exports toDisplayString, camelize, capitalize, toHandlerKey, normalizeProps, normalizeClass, and normalizeStyle so that compiler-emitted render functions can import { … } from 'vue'.

Two contributor traps to know about:

1. Don't import compiler-only helpers from runtime code. The whitelist sets in domTagConfig.ts are large; pulling them into the runtime bundle inflates every browser build. The contributing guide flags this specifically.
2. Add new general-purpose helpers here, not in runtime-core. If a function is needed in two packages, the answer is almost always to put it in shared.

Integration points

• runtime-core reads ShapeFlags, PatchFlags, EMPTY_OBJ, extend, NOOP, normalizeClass, normalizeStyle, toDisplayString, hasChanged, …
• compiler-core reads PatchFlags, SlotFlags, generateCodeFrame, makeMap, isHTMLTag, isSVGTag, isMathMLTag, isBooleanAttr.
• compiler-sfc uses cssVars.ts helpers to encode/decode the data passed between <style> and the runtime.
• server-renderer relies on escapeHtml for output sanitization.

Entry points for modification

If you need to add a flag or a helper that crosses the compiler/runtime boundary, add it here and update index.ts to re-export it. Avoid putting platform-specific helpers in this package — they belong in runtime-dom or compiler-dom.