0
# Preview System
1

2
The preview system provides standalone components for displaying compiled Vue components in a sandboxed iframe environment. It includes runtime error handling, theme support, and SSR rendering capabilities.
3

4
## Capabilities
5

6
### Sandbox Component
7

8
Standalone sandbox component for preview-only mode without the editor interface.
9

10
```typescript { .api }
11
/**
12
 * Standalone sandbox component for preview-only mode
13
 * Provides iframe-based Vue component execution with error handling
14
 * @param props - Configuration options for the sandbox
15
 */
16
interface SandboxProps {
17
  /** Store instance containing files and compilation state */
18
  store: Store;
19
  /** Whether to display the sandbox (useful for mobile responsive behavior) */
20
  show?: boolean;
21
  /** Enable server-side rendering mode */
22
  ssr?: boolean;
23
  /** Clear console output on file changes */
24
  clearConsole?: boolean;
25
  /** Theme for the preview iframe */
26
  theme?: 'dark' | 'light';
27
  /** Preview customization options */
28
  previewOptions?: PreviewOptions;
29
  /** Whether to automatically initialize the store (default: true) */
30
  autoStoreInit?: boolean;
31
}
32

33
interface PreviewOptions {
34
  /** Custom HTML to inject into iframe head section */
35
  headHTML?: string;
36
  /** Custom HTML to inject into iframe body section */
37
  bodyHTML?: string;
38
  /** HTML content to show while preview is loading */
39
  placeholderHTML?: string;
40
  /** Advanced code injection options */
41
  customCode?: {
42
    /** Custom import statements for the preview context */
43
    importCode?: string;
44
    /** Custom code to execute in the preview environment */
45
    useCode?: string;
46
  };
47
  /** Whether to display runtime JavaScript errors */
48
  showRuntimeError?: boolean;
49
  /** Whether to display runtime console warnings */
50
  showRuntimeWarning?: boolean;
51
}
52
```
53

54
**Usage Examples:**
55

56
```typescript
57
import { Sandbox, useStore } from "@vue/repl";
58

59
// Basic sandbox usage
60
<template>
61
  <Sandbox :store="store" />
62
</template>
63

64
<script setup>
65
const store = useStore({}, location.hash);
66
</script>
67

68
// Advanced sandbox with custom options
69
<template>
70
  <Sandbox 
71
    :store="store"
72
    theme="dark"
73
    :clearConsole="true"
74
    :previewOptions="{
75
      headHTML: '<meta name=\"viewport\" content=\"width=device-width\">',
76
      bodyHTML: '<div id=\"app\"></div>',
77
      showRuntimeError: true,
78
      showRuntimeWarning: false,
79
      customCode: {
80
        importCode: 'import { createApp } from \"vue\";',
81
        useCode: 'app.config.errorHandler = (err) => console.error(err);'
82
      }
83
    }"
84
  />
85
</template>
86
```
87

88
### Preview Component
89

90
Wrapper around Sandbox component used within the full REPL interface.
91

92
```typescript { .api }
93
/**
94
 * Preview wrapper component used within REPL interface
95
 * Provides theme integration and reload functionality
96
 * @param props - Preview configuration
97
 */
98
interface PreviewProps {
99
  /** Whether to show the preview panel */
100
  show: boolean;
101
  /** Enable server-side rendering mode */
102
  ssr: boolean;
103
}
104
```
105

106
**Usage Example:**
107

108
```typescript
109
// Used internally by Repl component
110
<Preview :show="showPreview" :ssr="ssrMode" />
111
```
112

113
### Sandbox Methods
114

115
Methods exposed by the Sandbox component for programmatic control.
116

117
```typescript { .api }
118
/**
119
 * Reload the preview iframe, clearing all runtime state
120
 */
121
function reload(): void;
122

123
/**
124
 * Get reference to the preview container DOM element
125
 * @returns HTMLDivElement container or null
126
 */
127
readonly container: ComputedRef<HTMLDivElement | null>;
128
```
129

130
**Usage Example:**
131

132
```typescript
133
<template>
134
  <Sandbox ref="sandbox" :store="store" />
135
  <button @click="$refs.sandbox.reload()">Reload Preview</button>
136
</template>
137

138
<script setup>
139
import { ref } from 'vue';
140

141
const sandbox = ref();
142

143
// Access container element
144
const containerEl = computed(() => sandbox.value?.container);
145
</script>
146
```
147

148
### Runtime Error Handling
149

150
The preview system includes comprehensive error handling for runtime issues.
151

152
```typescript { .api }
153
/**
154
 * Runtime error information captured in preview
155
 */
156
interface RuntimeError {
157
  /** Error message */
158
  message: string;
159
  /** Stack trace if available */
160
  stack?: string;
161
  /** Source filename */
162
  filename?: string;
163
  /** Line number */
164
  lineno?: number;
165
  /** Column number */
166
  colno?: number;
167
}
168

169
/**
170
 * Runtime warning information
171
 */
172
interface RuntimeWarning {
173
  /** Warning message */
174
  message: string;
175
  /** Warning type/category */
176
  type: string;
177
}
178
```
179

180
**Error Display:**
181

182
Runtime errors and warnings are displayed in the preview when enabled:
183

184
```typescript
185
// Enable error display
186
<Sandbox 
187
  :store="store"
188
  :previewOptions="{
189
    showRuntimeError: true,
190
    showRuntimeWarning: true
191
  }"
192
/>
193
```
194

195
### SSR Support
196

197
Server-side rendering support for testing SSR-compatible Vue components.
198

199
```typescript { .api }
200
/**
201
 * SSR output structure
202
 */
203
interface SSROutput {
204
  /** Rendered HTML string */
205
  html: string;
206
  /** SSR context object */
207
  context: unknown;
208
}
209
```
210

211
**Usage Example:**
212

213
```typescript
214
// Enable SSR mode
215
<template>
216
  <Sandbox :store="store" :ssr="true" />
217
</template>
218

219
// Access SSR output from store
220
<script setup>
221
const store = useStore();
222
console.log(store.ssrOutput.html); // Server-rendered HTML
223
</script>
224
```
225

226
### Preview Iframe Management
227

228
The preview system manages iframe creation, communication, and lifecycle.
229

230
**Iframe Features:**
231

232
- **Sandboxed execution**: Isolated JavaScript environment
233
- **Hot reloading**: Automatic refresh on code changes
234
- **Console integration**: Runtime logs displayed in REPL
235
- **Error boundaries**: Runtime error capture and display
236
- **Module resolution**: Dynamic import map support
237
- **Vue devtools**: Development tools integration when available
238

239
**Security Considerations:**
240

241
- All preview code runs in a sandboxed iframe
242
- No access to parent window or external domains
243
- Safe execution of untrusted user code
244
- XSS protection through iframe isolation
245

246
## Default Values
247

248
The Sandbox component provides sensible defaults:
249

250
- `show`: true
251
- `ssr`: false
252
- `theme`: 'light'
253
- `clearConsole`: true
254
- `previewOptions`: {} (empty object)
255
- `autoStoreInit`: true
256

257
## Integration with Store
258

259
The preview system integrates closely with the store system:
260

261
- **File watching**: Automatically recompiles and refreshes on file changes
262
- **Error reporting**: Compilation errors displayed in preview
263
- **Import map support**: Dynamic module resolution using store configuration
264
- **Vue version switching**: Automatic Vue runtime updates
265
- **State persistence**: Preview state maintained across store serialization