0
# Vue.js Compiler SSR
1
2
Vue.js Compiler SSR is a specialized compilation library that transforms Vue templates into optimized JavaScript code for server-side rendering. It provides a comprehensive transformation system that handles all Vue template features including components, directives, reactive data binding, and advanced features like teleports and suspense, specifically optimized for SSR environments.
3
4
## Package Information
5
6
- **Package Name**: @vue/compiler-ssr
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @vue/compiler-ssr`
10
11
## Core Imports
12
13
```typescript
14
import { compile } from "@vue/compiler-ssr";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { compile } = require("@vue/compiler-ssr");
21
```
22
23
## Basic Usage
24
25
```typescript
26
import { compile } from "@vue/compiler-ssr";
27
28
// Compile a Vue template for SSR
29
const result = compile(`
30
<div>
31
<h1>{{ title }}</h1>
32
<p v-if="showMessage">{{ message }}</p>
33
</div>
34
`, {
35
mode: 'function',
36
prefixIdentifiers: true
37
});
38
39
console.log(result.code);
40
// Outputs optimized SSR JavaScript code
41
```
42
43
## Architecture
44
45
Vue.js Compiler SSR is built around several key components:
46
47
- **Compilation Pipeline**: Main `compile` function that orchestrates the full SSR transformation process
48
- **Transform System**: Comprehensive set of node and directive transforms that convert Vue template features into SSR-optimized code
49
- **Runtime Helpers**: Collection of symbols and utilities that map to server-side rendering helper functions
50
- **Error Handling**: Specialized error codes and messages for SSR-specific compilation issues
51
- **Context Management**: Transform context interface that maintains state throughout the compilation process
52
53
## Capabilities
54
55
### Template Compilation
56
57
Core compilation functionality that transforms Vue templates or parsed AST into SSR-optimized JavaScript code with full support for all Vue template features.
58
59
```typescript { .api }
60
function compile(
61
source: string | RootNode,
62
options?: CompilerOptions
63
): CodegenResult;
64
65
function ssrCodegenTransform(
66
ast: RootNode,
67
options: CompilerOptions
68
): void;
69
```
70
71
[Template Compilation](./compilation.md)
72
73
### Transform System
74
75
Comprehensive transformation system that handles specific Vue template features including elements, components, directives, and control flow structures for SSR rendering.
76
77
```typescript { .api }
78
interface SSRTransformContext {
79
root: RootNode;
80
options: CompilerOptions;
81
body: (JSChildNode | IfStatement)[];
82
helpers: Set<symbol>;
83
withSlotScopeId: boolean;
84
onError: (error: CompilerError) => void;
85
helper<T extends symbol>(name: T): T;
86
pushStringPart(part: TemplateLiteral['elements'][0]): void;
87
pushStatement(statement: IfStatement | CallExpression): void;
88
}
89
90
function ssrCodegenTransform(
91
ast: RootNode,
92
options: CompilerOptions
93
): void;
94
```
95
96
[Transform System](./transforms.md)
97
98
### Runtime Helpers
99
100
Collection of symbolic identifiers and mappings for SSR runtime helper functions that handle specific rendering operations like interpolation, component rendering, and attribute handling.
101
102
```typescript { .api }
103
const SSR_INTERPOLATE: unique symbol;
104
const SSR_RENDER_COMPONENT: unique symbol;
105
const SSR_RENDER_ATTRS: unique symbol;
106
const SSR_RENDER_CLASS: unique symbol;
107
const SSR_RENDER_STYLE: unique symbol;
108
109
const ssrHelpers: Record<symbol, string>;
110
```
111
112
[Runtime Helpers](./runtime-helpers.md)
113
114
### Error Handling
115
116
SSR-specific error handling system with dedicated error codes and messages for compilation issues unique to server-side rendering contexts.
117
118
```typescript { .api }
119
enum SSRErrorCodes {
120
X_SSR_UNSAFE_ATTR_NAME = 65,
121
X_SSR_NO_TELEPORT_TARGET,
122
X_SSR_INVALID_AST_NODE,
123
}
124
125
interface SSRCompilerError extends CompilerError {
126
code: SSRErrorCodes;
127
}
128
129
function createSSRCompilerError(
130
code: SSRErrorCodes,
131
loc?: SourceLocation
132
): SSRCompilerError;
133
```
134
135
[Error Handling](./error-handling.md)
136
137
### Built-in Component Support
138
139
SSR-specific handling for Vue's built-in components including Teleport, Suspense, Transition, and TransitionGroup during server-side rendering.
140
141
```typescript { .api }
142
function ssrProcessTeleport(
143
node: TeleportNode,
144
context: SSRTransformContext
145
): void;
146
147
function ssrProcessSuspense(
148
node: SuspenseNode,
149
context: SSRTransformContext
150
): void;
151
152
function ssrTransformTransition(
153
node: ComponentNode,
154
context: TransformContext
155
): void;
156
157
function ssrTransformTransitionGroup(
158
node: ComponentNode,
159
context: TransformContext
160
): void;
161
```
162
163
[Built-in Components](./built-in-components.md)
164
165
### Processing Functions
166
167
Core processing functions that handle specific template nodes and generate appropriate SSR code during transformation.
168
169
```typescript { .api }
170
function processChildren(
171
parent: Container,
172
context: SSRTransformContext,
173
asFragment?: boolean,
174
disableNestedFragments?: boolean,
175
disableComment?: boolean
176
): void;
177
178
function processChildrenAsStatement(
179
parent: Container,
180
parentContext: SSRTransformContext,
181
asFragment?: boolean,
182
withSlotScopeId?: boolean
183
): BlockStatement;
184
185
function ssrProcessElement(
186
node: ElementNode,
187
context: SSRTransformContext,
188
parent: ParentNode,
189
slotScopeId?: string
190
): void;
191
192
function ssrProcessComponent(
193
node: ComponentNode,
194
context: SSRTransformContext,
195
parent: ParentNode,
196
slotScopeId?: string
197
): void;
198
199
function buildSSRProps(
200
props: (AttributeNode | DirectiveNode)[],
201
context: SSRTransformContext
202
): CallExpression | undefined;
203
```
204
205
### Utility Functions
206
207
Utility functions and constants used internally by the transform system for advanced use cases.
208
209
```typescript { .api }
210
const rawOptionsMap: WeakMap<RootNode, CompilerOptions>;
211
```
212
213
## Types
214
215
```typescript { .api }
216
// Core types imported from @vue/compiler-dom
217
interface CompilerOptions {
218
mode?: 'module' | 'function';
219
prefixIdentifiers?: boolean;
220
scopeId?: string;
221
ssr?: boolean;
222
inSSR?: boolean;
223
cacheHandlers?: boolean;
224
hoistStatic?: boolean;
225
nodeTransforms?: NodeTransform[];
226
directiveTransforms?: Record<string, DirectiveTransform>;
227
ssrCssVars?: string;
228
}
229
230
interface CodegenResult {
231
code: string;
232
preamble?: string;
233
ast: RootNode;
234
map?: SourceMap;
235
}
236
237
interface RootNode {
238
type: NodeTypes.ROOT;
239
children: TemplateChildNode[];
240
helpers: Set<symbol>;
241
components: string[];
242
directives: string[];
243
hoists: (JSChildNode | null)[];
244
imports: ImportItem[];
245
cached: number;
246
temps: number;
247
ssrHelpers?: symbol[];
248
codegenNode?: TemplateChildNode | JSChildNode | BlockStatement;
249
}
250
251
interface Container {
252
children: TemplateChildNode[];
253
}
254
255
interface ElementNode {
256
type: NodeTypes.ELEMENT;
257
tagType: ElementTypes;
258
tag: string;
259
props: (AttributeNode | DirectiveNode)[];
260
children: TemplateChildNode[];
261
loc: SourceLocation;
262
}
263
264
interface ComponentNode {
265
type: NodeTypes.ELEMENT;
266
tagType: ElementTypes.COMPONENT;
267
tag: string;
268
props: (AttributeNode | DirectiveNode)[];
269
children: TemplateChildNode[];
270
loc: SourceLocation;
271
}
272
273
interface ParentNode {
274
type: NodeTypes;
275
children: TemplateChildNode[];
276
}
277
278
interface AttributeNode {
279
type: NodeTypes.ATTRIBUTE;
280
name: string;
281
value?: TextNode;
282
loc: SourceLocation;
283
}
284
285
interface DirectiveNode {
286
type: NodeTypes.DIRECTIVE;
287
name: string;
288
exp?: ExpressionNode;
289
arg?: ExpressionNode;
290
modifiers: string[];
291
loc: SourceLocation;
292
}
293
294
interface BlockStatement {
295
type: 'BlockStatement';
296
body: (JSChildNode | IfStatement)[];
297
}
298
299
interface CallExpression {
300
type: 'CallExpression';
301
callee: string | symbol;
302
arguments: any[];
303
}
304
305
interface TeleportNode {
306
type: NodeTypes.ELEMENT;
307
tagType: ElementTypes.COMPONENT;
308
tag: 'Teleport' | 'teleport';
309
props: (AttributeNode | DirectiveNode)[];
310
children: TemplateChildNode[];
311
loc: SourceLocation;
312
}
313
314
interface SuspenseNode {
315
type: NodeTypes.ELEMENT;
316
tagType: ElementTypes.COMPONENT;
317
tag: 'Suspense' | 'suspense';
318
props: (AttributeNode | DirectiveNode)[];
319
children: TemplateChildNode[];
320
loc: SourceLocation;
321
}
322
323
interface TransitionNode {
324
type: NodeTypes.ELEMENT;
325
tagType: ElementTypes.COMPONENT;
326
tag: 'Transition' | 'transition' | 'TransitionGroup' | 'transition-group';
327
props: (AttributeNode | DirectiveNode)[];
328
children: TemplateChildNode[];
329
loc: SourceLocation;
330
}
331
332
enum NodeTypes {
333
ROOT = 0,
334
ELEMENT = 1,
335
TEXT = 2,
336
COMMENT = 3,
337
SIMPLE_EXPRESSION = 4,
338
INTERPOLATION = 5,
339
ATTRIBUTE = 6,
340
DIRECTIVE = 7,
341
COMPOUND_EXPRESSION = 8,
342
IF = 9,
343
IF_BRANCH = 10,
344
FOR = 11,
345
TEXT_CALL = 12,
346
VNODE_CALL = 13,
347
JS_CALL_EXPRESSION = 14,
348
JS_OBJECT_EXPRESSION = 15,
349
JS_PROPERTY = 16,
350
JS_ARRAY_EXPRESSION = 17,
351
JS_FUNCTION_EXPRESSION = 18,
352
JS_CONDITIONAL_EXPRESSION = 19,
353
JS_CACHE_EXPRESSION = 20,
354
JS_BLOCK_STATEMENT = 21,
355
JS_TEMPLATE_LITERAL = 22,
356
JS_IF_STATEMENT = 23,
357
JS_ASSIGNMENT_EXPRESSION = 24,
358
JS_SEQUENCE_EXPRESSION = 25,
359
JS_RETURN_STATEMENT = 26,
360
}
361
362
enum ElementTypes {
363
ELEMENT = 0,
364
COMPONENT = 1,
365
SLOT = 2,
366
TEMPLATE = 3,
367
}
368
369
interface SourceLocation {
370
start: Position;
371
end: Position;
372
source: string;
373
}
374
375
interface Position {
376
column: number;
377
line: number;
378
offset: number;
379
}
380
```