0
# Vue Compiler Core
1

2
@vue/compiler-core is the core compilation system for Vue.js template processing. It provides a complete pipeline for transforming Vue templates into optimized JavaScript render functions, including parsing, AST transformation, and code generation capabilities.
3

4
## Package Information
5

6
- **Package Name**: @vue/compiler-core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @vue/compiler-core`
10

11
## Core Imports
12

13
```typescript
14
import { baseCompile, baseParse, transform, generate } from "@vue/compiler-core";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { baseCompile, baseParse, transform, generate } = require("@vue/compiler-core");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { baseCompile, type CompilerOptions } from "@vue/compiler-core";
27

28
// Compile a Vue template to render function
29
const template = `
30
  <div>
31
    <h1>{{ title }}</h1>
32
    <p v-if="showMessage">{{ message }}</p>
33
  </div>
34
`;
35

36
const options: CompilerOptions = {
37
  mode: 'module',
38
  prefixIdentifiers: true
39
};
40

41
const result = baseCompile(template, options);
42
console.log(result.code); // Generated JavaScript render function
43
```
44

45
## Architecture
46

47
Vue Compiler Core follows a traditional compiler architecture with distinct phases:
48

49
- **Parser**: Converts template strings into Abstract Syntax Trees (AST) using `baseParse`
50
- **Transform System**: Applies transformations to AST nodes via plugins and directives
51
- **Code Generator**: Converts transformed AST into executable JavaScript using `generate`
52
- **Error System**: Provides comprehensive error reporting with source location information
53
- **Type System**: Full TypeScript support with detailed type definitions for all APIs
54

55
## Capabilities
56

57
### Template Compilation
58

59
Complete template compilation pipeline that transforms Vue templates into optimized JavaScript render functions with support for all Vue features.
60

61
```typescript { .api }
62
function baseCompile(
63
  source: string | RootNode,
64
  options?: CompilerOptions
65
): CodegenResult;
66

67
interface CompilerOptions extends ParserOptions, TransformOptions, CodegenOptions {}
68

69
interface CodegenResult {
70
  code: string;
71
  preamble: string;
72
  ast: RootNode;
73
  map?: RawSourceMap;
74
}
75
```
76

77
[Compilation Pipeline](./compilation.md)
78

79
### AST Node System
80

81
Comprehensive Abstract Syntax Tree node types representing all Vue template constructs, from elements and text to complex expressions and directives.
82

83
```typescript { .api }
84
enum NodeTypes {
85
  ROOT = 0,
86
  ELEMENT = 1,
87
  TEXT = 2,
88
  COMMENT = 3,
89
  SIMPLE_EXPRESSION = 4,
90
  INTERPOLATION = 5,
91
  ATTRIBUTE = 6,
92
  DIRECTIVE = 7,
93
  // ... additional node types
94
}
95

96
interface Node {
97
  type: NodeTypes;
98
  loc: SourceLocation;
99
}
100

101
interface RootNode extends Node {
102
  type: NodeTypes.ROOT;
103
  source: string;
104
  children: TemplateChildNode[];
105
  helpers: Set<symbol>;
106
  components: string[];
107
  directives: string[];
108
  hoists: (JSChildNode | null)[];
109
  imports: ImportItem[];
110
  cached: (CacheExpression | null)[];
111
  temps: number;
112
  ssrHelpers?: symbol[];
113
  codegenNode?: TemplateChildNode | JSChildNode | BlockStatement;
114
  transformed?: boolean;
115
  filters?: string[];
116
}
117
```
118

119
[AST Types and Interfaces](./ast-types.md)
120

121
### Transform System
122

123
Flexible transformation system for processing and modifying AST nodes, with built-in transforms for Vue directives and structural elements.
124

125
```typescript { .api }
126
function transform(root: RootNode, options: TransformOptions): void;
127

128
function createTransformContext(
129
  root: RootNode,
130
  options: TransformOptions
131
): TransformContext;
132

133
function traverseNode(
134
  node: RootNode | TemplateChildNode,
135
  context: TransformContext
136
): void;
137

138
function createStructuralDirectiveTransform(
139
  name: string | RegExp,
140
  fn: StructuralDirectiveTransform
141
): NodeTransform;
142

143
interface TransformContext {
144
  root: RootNode;
145
  helpers: Map<symbol, number>;
146
  components: Set<string>;
147
  directives: Set<string>;
148
  hoists: (JSChildNode | null)[];
149
  imports: ImportItem[];
150
  constantCache: WeakMap<TemplateChildNode, ConstantTypes>;
151
  temps: number;
152
  cached: (CacheExpression | null)[];
153
  identifiers: { [name: string]: number | undefined };
154
  scopes: { vFor: number; vSlot: number; vPre: number; vOnce: number };
155
  parent: ParentNode | null;
156
  grandParent: ParentNode | null;
157
  childIndex: number;
158
  currentNode: RootNode | TemplateChildNode | null;
159
  inVOnce: boolean;
160
  helper<T extends symbol>(name: T): T;
161
  removeHelper<T extends symbol>(name: T): void;
162
  helperString(name: symbol): string;
163
  replaceNode(node: TemplateChildNode): void;
164
  removeNode(node?: TemplateChildNode): void;
165
  onNodeRemoved(): void;
166
  addIdentifiers(exp: ExpressionNode | string): void;
167
  removeIdentifiers(exp: ExpressionNode | string): void;
168
  hoist(exp: string | JSChildNode | ArrayExpression): SimpleExpressionNode;
169
  cache(exp: JSChildNode, isVNode?: boolean, inVOnce?: boolean): CacheExpression;
170
}
171
```
172

173
[Transform System](./transforms.md)
174

175
### Error Handling
176

177
Comprehensive error system with detailed error codes, source location tracking, and human-readable error messages.
178

179
```typescript { .api }
180
enum ErrorCodes {
181
  ABRUPT_CLOSING_OF_EMPTY_COMMENT = 0,
182
  CDATA_IN_HTML_CONTENT = 1,
183
  DUPLICATE_ATTRIBUTE = 2,
184
  END_TAG_WITH_ATTRIBUTES = 3,
185
  END_TAG_WITH_TRAILING_SOLIDUS = 4,
186
  // ... additional error codes
187
}
188

189
function createCompilerError<T extends number>(
190
  code: T,
191
  loc?: SourceLocation,
192
  messages?: { [code: number]: string },
193
  additionalMessage?: string
194
): InferCompilerError<T>;
195

196
function generateCodeFrame(
197
  source: string,
198
  start?: number,
199
  end?: number
200
): string;
201

202
interface CompilerError extends SyntaxError {
203
  code: number;
204
  loc?: SourceLocation;
205
}
206
```
207

208
[Error Handling](./error-handling.md)
209

210
### Utilities and Helpers
211

212
Collection of utility functions for AST manipulation, type checking, and common compiler operations.
213

214
```typescript { .api }
215
function findDir(
216
  node: ElementNode,
217
  name: string | RegExp,
218
  allowEmpty?: boolean
219
): DirectiveNode | undefined;
220

221
function findProp(
222
  node: ElementNode,
223
  name: string,
224
  dynamicOnly?: boolean,
225
  allowEmpty?: boolean
226
): ElementNode['props'][0] | undefined;
227

228
function isText(node: TemplateChildNode): node is TextNode | InterpolationNode;
229

230
function toValidAssetId(name: string, type: 'component' | 'directive' | 'filter'): string;
231
```
232

233
[Utilities and Helpers](./utilities.md)
234

235
## Types
236

237
### Core Configuration Types
238

239
```typescript { .api }
240
interface ParserOptions {
241
  parseMode?: 'base' | 'html' | 'sfc';
242
  ns?: Namespaces;
243
  delimiters?: [string, string];
244
  getNamespace?: (tag: string, parent: ElementNode | undefined, rootNamespace: Namespace) => Namespace;
245
  isNativeTag?: (tag: string) => boolean;
246
  isVoidTag?: (tag: string) => boolean;
247
  isPreTag?: (tag: string) => boolean;
248
  isIgnoreNewlineTag?: (tag: string) => boolean;
249
  isBuiltInComponent?: (tag: string) => symbol | void;
250
  isCustomElement?: (tag: string) => boolean | void;
251
  decodeEntities?: (rawText: string, asAttr: boolean) => string;
252
  whitespace?: 'preserve' | 'condense';
253
  comments?: boolean;
254
  prefixIdentifiers?: boolean;
255
  expressionPlugins?: ParserPlugin[];
256
}
257

258
interface TransformOptions {
259
  nodeTransforms?: NodeTransform[];
260
  directiveTransforms?: Record<string, DirectiveTransform | undefined>;
261
  transformHoist?: HoistTransform | null;
262
  isBuiltInComponent?: (tag: string) => symbol | void;
263
  isCustomElement?: (tag: string) => boolean | void;
264
  prefixIdentifiers?: boolean;
265
  hoistStatic?: boolean;
266
  cacheHandlers?: boolean;
267
  expressionPlugins?: ParserPlugin[];
268
  scopeId?: string | null;
269
  slotted?: boolean;
270
  ssrCssVars?: string;
271
  hmr?: boolean;
272
  ssr?: boolean;
273
  inSSR?: boolean;
274
  bindingMetadata?: BindingMetadata;
275
  inline?: boolean;
276
  isTS?: boolean;
277
  filename?: string;
278
}
279

280
interface CodegenOptions {
281
  mode?: 'module' | 'function';
282
  sourceMap?: boolean;
283
  scopeId?: string | null;
284
  optimizeImports?: boolean;
285
  runtimeModuleName?: string;
286
  ssrRuntimeModuleName?: string;
287
  runtimeGlobalName?: string;
288
}
289
```
290

291
### Source Location Types
292

293
```typescript { .api }
294
interface SourceLocation {
295
  start: Position;
296
  end: Position;
297
  source: string;
298
}
299

300
interface Position {
301
  offset: number;
302
  line: number;
303
  column: number;
304
}
305
```