0
# Error Handling
1

2
SSR-specific error handling system with dedicated error codes and messages for compilation issues unique to server-side rendering contexts.
3

4
## Capabilities
5

6
### SSR Error Codes
7

8
Enumeration of error codes specific to SSR compilation issues that extend the base compiler error codes.
9

10
```typescript { .api }
11
enum SSRErrorCodes {
12
  /** Unsafe attribute name detected during SSR compilation */
13
  X_SSR_UNSAFE_ATTR_NAME = 65,
14
  /** Teleport component missing required 'to' prop */
15
  X_SSR_NO_TELEPORT_TARGET,
16
  /** Invalid AST node encountered during SSR transformation */
17
  X_SSR_INVALID_AST_NODE,
18
}
19
```
20

21
### SSR Compiler Error Interface
22

23
Extended compiler error interface that includes SSR-specific error codes.
24

25
```typescript { .api }
26
interface SSRCompilerError extends CompilerError {
27
  /** SSR-specific error code */
28
  code: SSRErrorCodes;
29
}
30
```
31

32
### Error Creation Function
33

34
Factory function for creating SSR-specific compiler errors with appropriate error codes and location information.
35

36
```typescript { .api }
37
/**
38
 * Creates SSR-specific compiler errors with appropriate error codes
39
 * @param code - SSR error code indicating the type of error
40
 * @param loc - Optional source location where the error occurred
41
 * @returns SSRCompilerError instance with SSR-specific error information
42
 */
43
function createSSRCompilerError(
44
  code: SSRErrorCodes,
45
  loc?: SourceLocation
46
): SSRCompilerError;
47
```
48

49
### Error Messages
50

51
Human-readable error messages corresponding to each SSR error code.
52

53
```typescript { .api }
54
/**
55
 * Mapping of SSR error codes to human-readable error messages
56
 * Used for displaying meaningful error information to developers
57
 */
58
const SSRErrorMessages: { [code: number]: string };
59
```
60

61
The `SSRErrorMessages` object contains the following mappings:
62

63
- `X_SSR_UNSAFE_ATTR_NAME` → `"Unsafe attribute name for SSR."`
64
- `X_SSR_NO_TELEPORT_TARGET` → `"Missing the 'to' prop on teleport element."`
65
- `X_SSR_INVALID_AST_NODE` → `"Invalid AST node during SSR transform."`
66

67
## Error Categories
68

69
### Attribute Safety Errors
70

71
**X_SSR_UNSAFE_ATTR_NAME**: Indicates an attribute name that is unsafe for server-side rendering.
72

73
Common causes:
74
- Attribute names containing characters that could cause XSS vulnerabilities
75
- Attribute names that conflict with SSR rendering logic
76
- Malformed or potentially dangerous attribute names
77

78
```typescript
79
// Example usage in transform code
80
if (isUnsafeAttrName(attrName)) {
81
  context.onError(createSSRCompilerError(
82
    SSRErrorCodes.X_SSR_UNSAFE_ATTR_NAME,
83
    attr.loc
84
  ));
85
}
86
```
87

88
### Component Configuration Errors
89

90
**X_SSR_NO_TELEPORT_TARGET**: Indicates a teleport component is missing its required 'to' prop.
91

92
Common causes:
93
- `<teleport>` element without a `to` attribute
94
- Dynamic `to` prop that cannot be resolved at compile time
95
- Invalid teleport target specification
96

97
```typescript
98
// Example usage in teleport transform
99
if (!hasToProp(teleportNode)) {
100
  context.onError(createSSRCompilerError(
101
    SSRErrorCodes.X_SSR_NO_TELEPORT_TARGET,
102
    teleportNode.loc
103
  ));
104
}
105
```
106

107
### AST Processing Errors
108

109
**X_SSR_INVALID_AST_NODE**: Indicates an invalid or unexpected AST node during SSR transformation.
110

111
Common causes:
112
- Malformed template AST nodes
113
- Unsupported node types in SSR context
114
- Corrupted AST structure during transformation
115

116
```typescript
117
// Example usage in transform processing
118
if (!isSupportedNodeType(node)) {
119
  context.onError(createSSRCompilerError(
120
    SSRErrorCodes.X_SSR_INVALID_AST_NODE,
121
    node.loc
122
  ));
123
}
124
```
125

126
## Error Handling Best Practices
127

128
### Error Context
129

130
Always provide source location information when creating errors to help developers identify the exact location of issues in their templates:
131

132
```typescript
133
// Good: Include location information
134
context.onError(createSSRCompilerError(
135
  SSRErrorCodes.X_SSR_UNSAFE_ATTR_NAME,
136
  attr.loc
137
));
138

139
// Less helpful: No location information
140
context.onError(createSSRCompilerError(
141
  SSRErrorCodes.X_SSR_UNSAFE_ATTR_NAME
142
));
143
```
144

145
### Error Recovery
146

147
The SSR compiler attempts to recover from errors when possible, allowing compilation to continue and report multiple issues:
148

149
```typescript
150
// Transform continues after error reporting
151
try {
152
  processUnsafeAttribute(attr, context);
153
} catch (error) {
154
  context.onError(createSSRCompilerError(
155
    SSRErrorCodes.X_SSR_UNSAFE_ATTR_NAME,
156
    attr.loc
157
  ));
158
  // Continue processing other attributes
159
}
160
```
161

162
### Custom Error Handling
163

164
Developers can provide custom error handlers through compiler options:
165

166
```typescript
167
import { compile } from "@vue/compiler-ssr";
168

169
const result = compile(template, {
170
  onError: (error) => {
171
    if (error.code === SSRErrorCodes.X_SSR_UNSAFE_ATTR_NAME) {
172
      // Custom handling for unsafe attribute names
173
      console.warn(`Unsafe attribute detected: ${error.message}`);
174
    } else {
175
      // Default error handling
176
      throw error;
177
    }
178
  }
179
});
180
```
181

182
## Error Code Extension
183

184
The SSR error codes extend the base `DOMErrorCodes` from `@vue/compiler-dom` starting at the extension point (65). This ensures no conflicts with existing error codes while maintaining consistency with the broader Vue compiler error system.
185

186
```typescript
187
// Error code numbering starts after DOMErrorCodes extension point
188
if (__TEST__) {
189
  if (SSRErrorCodes.X_SSR_UNSAFE_ATTR_NAME < DOMErrorCodes.__EXTEND_POINT__) {
190
    throw new Error(
191
      `SSRErrorCodes need to be updated to match extension point from core DOMErrorCodes.`
192
    );
193
  }
194
}
195
```