0
# Vue REPL
1

2
Vue REPL provides a Vue 3 Single File Component (SFC) REPL (Read-Eval-Print Loop) that enables developers to create interactive Vue.js code editors and playgrounds. It offers two editor options: CodeMirror for lightweight editing experiences and Monaco Editor with full Volar language service support including autocomplete, type inference, and semantic highlighting.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { Repl } from "@vue/repl";
15
import CodeMirror from "@vue/repl/codemirror-editor";
16
import Monaco from "@vue/repl/monaco-editor";
17
```
18

19
For core utilities:
20

21
```typescript
22
import { useStore, File, useVueImportMap } from "@vue/repl/core";
23
```
24

25
For standalone preview:
26

27
```typescript
28
import { Sandbox } from "@vue/repl";
29
```
30

31
## Basic Usage
32

33
### CodeMirror Editor (Lightweight)
34

35
```typescript
36
import { Repl } from "@vue/repl";
37
import CodeMirror from "@vue/repl/codemirror-editor";
38

39
// In your Vue component template
40
<template>
41
  <Repl :editor="CodeMirror" />
42
</template>
43
```
44

45
### Monaco Editor (Full Language Service)
46

47
```typescript
48
import { Repl } from "@vue/repl";
49
import Monaco from "@vue/repl/monaco-editor";
50

51
// In your Vue component template
52
<template>
53
  <Repl :editor="Monaco" :showCompileOutput="true" />
54
</template>
55
```
56

57
### Advanced Store Configuration
58

59
```typescript
60
import { Repl, useStore, useVueImportMap } from "@vue/repl";
61
import Monaco from "@vue/repl/monaco-editor";
62

63
const { importMap, vueVersion } = useVueImportMap({
64
  runtimeDev: 'custom-vue-runtime-url',
65
  vueVersion: '3.4.0'
66
});
67

68
const store = useStore({
69
  builtinImportMap: importMap,
70
  vueVersion,
71
  showOutput: ref(true),
72
  outputMode: ref('preview')
73
}, location.hash);
74

75
// In template
76
<template>
77
  <Repl :store="store" :editor="Monaco" />
78
</template>
79
```
80

81
## Architecture
82

83
Vue REPL is built around several key components:
84

85
- **REPL Component**: Main interface orchestrating editor and preview panels
86
- **Store System**: Reactive state management for files, compilation, and configuration
87
- **Editor Abstraction**: Pluggable editor system supporting CodeMirror and Monaco
88
- **Compilation Engine**: Real-time Vue SFC compilation with error reporting
89
- **Preview System**: Sandboxed iframe execution environment with runtime error handling
90
- **Import Map Management**: Dynamic module resolution and Vue version switching
91

92
## Capabilities
93

94
### REPL Component
95

96
Main REPL interface component that provides a complete code editing and preview experience with configurable layout, themes, and features.
97

98
```typescript { .api }
99
interface ReplProps {
100
  theme?: 'dark' | 'light';
101
  previewTheme?: boolean;
102
  editor: EditorComponentType;
103
  store?: Store;
104
  autoResize?: boolean; 
105
  showCompileOutput?: boolean;
106
  showOpenSourceMap?: boolean;
107
  showImportMap?: boolean;
108
  showSsrOutput?: boolean;
109
  showTsConfig?: boolean;
110
  clearConsole?: boolean;
111
  layout?: 'horizontal' | 'vertical';
112
  layoutReverse?: boolean;
113
  ssr?: boolean;
114
  previewOptions?: PreviewOptions;
115
  editorOptions?: EditorOptions;
116
  splitPaneOptions?: SplitPaneOptions;
117
}
118

119
interface PreviewOptions {
120
  headHTML?: string;
121
  bodyHTML?: string;
122
  placeholderHTML?: string;
123
  customCode?: {
124
    importCode?: string;
125
    useCode?: string;
126
  };
127
  showRuntimeError?: boolean;
128
  showRuntimeWarning?: boolean;
129
}
130

131
interface EditorOptions {
132
  showErrorText?: string | false;
133
  autoSaveText?: string | false;
134
  monacoOptions?: monaco.editor.IStandaloneEditorConstructionOptions;
135
}
136

137
interface SplitPaneOptions {
138
  codeTogglerText?: string;
139
  outputTogglerText?: string;
140
}
141
```
142

143
[REPL Component](./repl-component.md)
144

145
### Store Management
146

147
Reactive store system for managing files, compilation state, and REPL configuration with serialization support for URL persistence.
148

149
```typescript { .api }
150
function useStore(
151
  state?: Partial<StoreState>,
152
  serializedState?: string
153
): ReplStore;
154

155
interface ReplStore {
156
  // File management
157
  files: Record<string, File>;
158
  activeFile: File;
159
  activeFilename: string;
160
  mainFile: string;
161
  
162
  // Compilation state
163
  errors: (string | Error)[];
164
  compiler: typeof defaultCompiler;
165
  loading: boolean;
166
  
167
  // Methods
168
  init(): void;
169
  setActive(filename: string): void;
170
  addFile(filename: string | File): void;
171
  deleteFile(filename: string): void;
172
  renameFile(oldFilename: string, newFilename: string): void;
173
  serialize(): string;
174
  deserialize(serializedState: string): void;
175
  getFiles(): Record<string, string>;
176
  setFiles(newFiles: Record<string, string>, mainFile?: string): Promise<void>;
177
}
178
```
179

180
[Store Management](./store-management.md)
181

182
### Preview System
183

184
Standalone preview and sandbox components for displaying compiled Vue components with runtime error handling and theme support.
185

186
```typescript { .api }
187
interface SandboxProps {
188
  store: Store;
189
  show?: boolean;
190
  ssr?: boolean;
191
  clearConsole?: boolean;
192
  theme?: 'dark' | 'light';
193
  previewOptions?: PreviewOptions;
194
  autoStoreInit?: boolean;
195
}
196
```
197

198
[Preview System](./preview-system.md)
199

200
### File System
201

202
File model and utilities for managing code files with compilation results and editor state persistence.
203

204
```typescript { .api }
205
class File {
206
  filename: string;
207
  code: string;
208
  hidden: boolean;
209
  compiled: {
210
    js: string;
211
    css: string;
212
    ssr: string;
213
    clientMap: string;
214
    ssrMap: string;
215
  };
216
  editorViewState: editor.ICodeEditorViewState | null;
217
  readonly language: string;
218
  
219
  constructor(filename: string, code?: string, hidden?: boolean);
220
}
221

222
function compileFile(store: Store, file: File): Promise<(string | Error)[]>;
223
```
224

225
[File System](./file-system.md)
226

227
### Import Map Management
228

229
Vue-specific import map utilities for managing CDN URLs, version switching, and module resolution in the browser environment.
230

231
```typescript { .api }
232
function useVueImportMap(defaults?: {
233
  runtimeDev?: string | (() => string);
234
  runtimeProd?: string | (() => string);
235
  serverRenderer?: string | (() => string);
236
  vueVersion?: string | null;
237
}): {
238
  productionMode: Ref<boolean>;
239
  importMap: ComputedRef<ImportMap>;
240
  vueVersion: Ref<string | null>;
241
  defaultVersion: string;
242
};
243

244
interface ImportMap {
245
  imports?: Record<string, string | undefined>;
246
  scopes?: Record<string, Record<string, string>>;
247
}
248

249
function mergeImportMap(a: ImportMap, b: ImportMap): ImportMap;
250
```
251

252
[Import Map Management](./import-map-management.md)
253

254
### Editor Components
255

256
Pluggable editor system with CodeMirror and Monaco implementations, both conforming to a standard interface for seamless switching.
257

258
```typescript { .api }
259
interface EditorProps {
260
  value: string;
261
  filename: string;
262
  readonly?: boolean;
263
  mode?: EditorMode;
264
}
265

266
interface EditorEmits {
267
  (e: 'change', code: string): void;
268
}
269

270
type EditorComponentType = Component<EditorProps>;
271
type EditorMode = 'js' | 'css' | 'ssr';
272
```
273

274
[Editor Components](./editor-components.md)
275

276
## Constants
277

278
```typescript { .api }
279
/** Version of Vue language service used for Monaco editor integration */
280
const languageToolsVersion: string;
281
```
282

283
## Types
284

285
```typescript { .api }
286
type OutputModes = 'preview' | 'ssr output' | EditorMode;
287

288
interface SFCOptions {
289
  script?: Partial<SFCScriptCompileOptions>;
290
  style?: Partial<SFCAsyncStyleCompileOptions>;
291
  template?: Partial<SFCTemplateCompileOptions>;
292
}
293

294
interface StoreState {
295
  files: Record<string, File>;
296
  activeFilename: string;
297
  mainFile: string;
298
  template: {
299
    welcomeSFC?: string;
300
    newSFC?: string;
301
  };
302
  builtinImportMap: ImportMap;
303
  errors: (string | Error)[];
304
  showOutput: boolean;
305
  outputMode: OutputModes;
306
  sfcOptions: SFCOptions;
307
  ssrOutput: {
308
    html: string;
309
    context: unknown;
310
  };
311
  compiler: typeof defaultCompiler;
312
  vueVersion: string | null;
313
  locale: string | undefined;
314
  typescriptVersion: string;
315
  dependencyVersion: Record<string, string>;
316
  reloadLanguageTools?: (() => void) | undefined;
317
}
318
```