0
# String Rendering
1
2
Core string rendering functionality for converting Vue applications and VNodes to complete HTML strings. This is the most straightforward rendering approach, ideal for simple SSR setups and when you need the complete HTML upfront.
3
4
## Capabilities
5
6
### renderToString
7
8
Renders a Vue application or VNode to a complete HTML string asynchronously. Handles the full rendering lifecycle including teleport resolution and watcher cleanup.
9
10
```typescript { .api }
11
/**
12
* Renders a Vue application or VNode to a complete HTML string
13
* @param input - Vue application instance or VNode to render
14
* @param context - Optional SSR context for teleports and additional data
15
* @returns Promise resolving to the complete HTML string
16
*/
17
function renderToString(
18
input: App | VNode,
19
context?: SSRContext
20
): Promise<string>;
21
22
interface SSRContext {
23
[key: string]: any;
24
/** Teleported content after rendering */
25
teleports?: Record<string, string>;
26
/** Internal teleport buffers (do not use directly) */
27
__teleportBuffers?: Record<string, SSRBuffer>;
28
/** Internal watcher handles (do not use directly) */
29
__watcherHandles?: (() => void)[];
30
}
31
```
32
33
**Usage Examples:**
34
35
```typescript
36
import { createSSRApp } from "vue";
37
import { renderToString } from "@vue/server-renderer";
38
39
// Basic string rendering
40
const app = createSSRApp({
41
data: () => ({ title: "My App", count: 0 }),
42
template: `
43
<div>
44
<h1>{{ title }}</h1>
45
<p>Count: {{ count }}</p>
46
</div>
47
`,
48
});
49
50
const html = await renderToString(app);
51
console.log(html);
52
// Output: <div><h1>My App</h1><p>Count: 0</p></div>
53
54
// Rendering with SSR context
55
const context = {};
56
const htmlWithContext = await renderToString(app, context);
57
58
// Check for teleported content
59
if (context.teleports) {
60
console.log("Teleported content:", context.teleports);
61
}
62
63
// Rendering a VNode directly
64
import { h } from "vue";
65
66
const vnode = h('div', { class: 'container' }, [
67
h('h1', 'Hello World'),
68
h('p', 'This is rendered from a VNode')
69
]);
70
71
const vnodeHtml = await renderToString(vnode);
72
console.log(vnodeHtml);
73
// Output: <div class="container"><h1>Hello World</h1><p>This is rendered from a VNode</p></div>
74
```
75
76
### SSR Context Usage
77
78
The SSR context allows passing data between server and client, and automatically handles teleported content.
79
80
```typescript
81
import { createSSRApp } from "vue";
82
import { renderToString } from "@vue/server-renderer";
83
84
const app = createSSRApp({
85
template: `
86
<div>
87
<h1>Main Content</h1>
88
<Teleport to="#modal">
89
<div class="modal">This will be teleported</div>
90
</Teleport>
91
</div>
92
`,
93
});
94
95
const context = {
96
// Custom data available during rendering
97
user: { name: "John", role: "admin" },
98
apiUrl: "https://api.example.com",
99
};
100
101
const html = await renderToString(app, context);
102
103
// Main content HTML
104
console.log(html);
105
// <div><h1>Main Content</h1><!--teleport start--><!--teleport end--></div>
106
107
// Teleported content is available in context
108
console.log(context.teleports);
109
// { '#modal': '<div class="modal">This will be teleported</div>' }
110
111
// Inject teleported content into your HTML template
112
const fullHtml = `
113
<!DOCTYPE html>
114
<html>
115
<head><title>My App</title></head>
116
<body>
117
${html}
118
<div id="modal">${context.teleports?.['#modal'] || ''}</div>
119
</body>
120
</html>
121
`;
122
```
123
124
### Error Handling
125
126
String rendering automatically handles errors and cleanup, but you should wrap calls in try-catch for proper error handling.
127
128
```typescript
129
import { createSSRApp } from "vue";
130
import { renderToString } from "@vue/server-renderer";
131
132
const app = createSSRApp({
133
setup() {
134
throw new Error("Component error during SSR");
135
},
136
template: `<div>Never reached</div>`,
137
});
138
139
try {
140
const html = await renderToString(app);
141
} catch (error) {
142
console.error("SSR Error:", error.message);
143
// Handle error - render fallback HTML, log error, etc.
144
}
145
```
146
147
## Advanced Usage
148
149
### Component-Level SSR Context Access
150
151
Components can access the SSR context during rendering using the `ssrContext` injection key.
152
153
```typescript
154
import { createSSRApp, inject } from "vue";
155
import { renderToString, ssrContextKey } from "@vue/server-renderer";
156
157
const app = createSSRApp({
158
setup() {
159
const ssrContext = inject(ssrContextKey);
160
161
// Access context data during rendering
162
const user = ssrContext?.user;
163
164
return { user };
165
},
166
template: `<div>Hello {{ user?.name }}!</div>`,
167
});
168
169
const context = { user: { name: "Alice" } };
170
const html = await renderToString(app, context);
171
// Output: <div>Hello Alice!</div>
172
```
173
174
### Performance Considerations
175
176
- **Memory Usage**: String rendering loads the entire HTML into memory before returning
177
- **Blocking**: The function waits for all async components to resolve before returning
178
- **Best For**: Simple applications, static content, or when you need the complete HTML upfront
179
- **Not Ideal For**: Large applications where streaming would provide better user experience