0
# Advanced Features
1

2
Advanced macros and transformations for enhanced Vue development.
3

4
## Capabilities
5

6
### Better Define
7

8
Enhanced integration between Options API and Composition API.
9

10
```typescript { .api }
11
/**
12
 * Better integration for defineProps and defineEmits
13
 * Converts runtime props/emits to type-only when possible
14
 */
15
declare function betterDefine(): void;
16

17
// Configuration options
18
interface OptionsBetterDefine extends BaseOptions {
19
  /** Enable reactive props destructuring */
20
  reactivePropsDestructure?: boolean;
21
}
22
```
23

24
**Usage Examples:**
25

26
```vue
27
<script setup>
28
// Better define automatically optimizes these
29
const props = defineProps({
30
  name: String,
31
  age: Number,
32
  config: Object,
33
});
34

35
const emit = defineEmits(['update', 'change', 'delete']);
36

37
// Reactive destructuring (when enabled)
38
const { name, age } = props; // Automatically reactive
39

40
// Better define optimizes the above to:
41
// const props = defineProps<{ name?: string; age?: number; config?: object }>();
42
// const emit = defineEmits<{ update: []; change: []; delete: [] }>();
43
</script>
44
```
45

46
### Reactivity Transform
47

48
Transform reactivity syntax with `$` prefix.
49

50
```typescript { .api }
51
/**
52
 * Reactivity transform with $ prefix syntax
53
 */
54
declare const $ref: typeof ref;
55
declare const $shallowRef: typeof shallowRef;
56
declare const $computed: typeof computed;
57
declare const $customRef: typeof customRef;
58
declare const $toRef: typeof toRef;
59

60
// Transform macros
61
declare function $$(expr: any): any; // Escape reactivity transform
62
declare function $(expr: any): any;   // Force reactivity transform
63

64
// Configuration options
65
interface OptionsReactivityTransform extends BaseOptions {
66
  /** File patterns to include */
67
  include?: string | RegExp | (string | RegExp)[];
68
  /** File patterns to exclude */
69
  exclude?: string | RegExp | (string | RegExp)[];
70
}
71
```
72

73
**Usage Examples:**
74

75
```vue
76
<script setup>
77
// Reactivity transform syntax
78
let count = $ref(0);              // Same as: const count = ref(0);
79
let doubled = $computed(() => count * 2);  // Same as: const doubled = computed(() => count.value * 2);
80
let name = $ref('Vue');           // Same as: const name = ref('Vue');
81

82
// Direct access without .value
83
console.log(count);               // No need for count.value
84
count++;                          // No need for count.value++
85

86
// In templates, works normally
87
// <template>{{ count }}</template>
88

89
// Escape when needed
90
const rawRef = $$(someRef);       // Get the actual ref object
91

92
// Arrays and objects
93
let items = $ref([1, 2, 3]);
94
let user = $ref({ name: 'John', age: 30 });
95

96
items.push(4);                    // Reactive
97
user.age++;                       // Reactive
98

99
// Computed with complex logic
100
let filteredItems = $computed(() => {
101
  return items.filter(item => item > count);
102
});
103

104
// Custom ref
105
let myCustom = $customRef((track, trigger) => ({
106
  get() {
107
    track();
108
    return count;
109
  },
110
  set(newValue) {
111
    count = newValue;
112
    trigger();
113
  },
114
}));
115
</script>
116
```
117

118
### Setup Component
119

120
Component-level setup syntax.
121

122
```typescript { .api }
123
/**
124
 * Setup component with enhanced syntax
125
 * @param options - Setup component options
126
 */
127
declare function setupComponent<T = {}>(
128
  options: SetupComponentOptions<T>
129
): void;
130

131
interface SetupComponentOptions<T = {}> {
132
  name?: string;
133
  props?: T;
134
  emits?: string[] | Record<string, any>;
135
  setup?: (props: T, context: SetupContext) => any;
136
}
137

138
// Configuration options
139
interface OptionsSetupComponent extends BaseOptions {
140
  /** Enable component-level setup */
141
  enabled?: boolean;
142
}
143
```
144

145
**Usage Examples:**
146

147
```vue
148
<script setup>
149
// Setup component syntax
150
setupComponent({
151
  name: 'MyAdvancedComponent',
152
  
153
  props: {
154
    title: String,
155
    items: Array,
156
  },
157
  
158
  emits: ['update', 'change'],
159
  
160
  setup(props, { emit, slots }) {
161
    const internalState = ref('internal');
162
    
163
    const processedItems = computed(() => {
164
      return props.items?.map(item => ({
165
        ...item,
166
        processed: true,
167
      }));
168
    });
169
    
170
    function handleUpdate(value: any) {
171
      emit('update', value);
172
    }
173
    
174
    return {
175
      internalState,
176
      processedItems,
177
      handleUpdate,
178
    };
179
  },
180
});
181
</script>
182
```
183

184
### Setup SFC
185

186
Single File Component setup enhancements.
187

188
```typescript { .api }
189
/**
190
 * Setup SFC with enhanced capabilities
191
 */
192
declare function setupSFC(): void;
193

194
// Configuration options
195
interface OptionsSetupSFC extends BaseOptions {
196
  /** Enable SFC-level enhancements */
197
  enabled?: boolean;
198
}
199
```
200

201
### Setup Block
202

203
Experimental setup block syntax.
204

205
```typescript { .api }
206
/**
207
 * Setup block for component logic separation
208
 */
209
declare function setupBlock(): void;
210

211
// Configuration options  
212
interface OptionsSetupBlock extends BaseOptions {
213
  /** Enable setup block syntax */
214
  enabled?: boolean;
215
}
216
```
217

218
**Usage Examples:**
219

220
```vue
221
<!-- Setup block syntax -->
222
<setup>
223
const count = ref(0);
224
const doubled = computed(() => count.value * 2);
225

226
function increment() {
227
  count.value++;
228
}
229

230
return {
231
  count,
232
  doubled,
233
  increment,
234
};
235
</setup>
236

237
<template>
238
  <div>
239
    <p>Count: {{ count }}</p>
240
    <p>Doubled: {{ doubled }}</p>
241
    <button @click="increment">Increment</button>
242
  </div>
243
</template>
244
```
245

246
### Hoist Static
247

248
Static hoisting optimizations.
249

250
```typescript { .api }
251
/**
252
 * Hoist static elements and expressions for performance
253
 */
254
interface OptionsHoistStatic extends BaseOptions {
255
  /** Enable static hoisting */
256
  enabled?: boolean;
257
  /** Hoist static props */
258
  hoistStaticProps?: boolean;
259
}
260
```
261

262
### Export Features
263

264
Enhanced export capabilities for component composition.
265

266
```typescript { .api }
267
/**
268
 * Export props for parent access
269
 * @param props - Props to export
270
 */
271
declare function exportProps<T>(props: T): void;
272

273
/**
274
 * Export render function
275
 * @param render - Render function to export
276
 */
277
declare function exportRender(render: RenderFunction): void;
278

279
// Configuration options
280
interface OptionsExportProps extends BaseOptions {
281
  /** Enable export props */
282
  enabled?: boolean;
283
}
284

285
interface OptionsExportRender extends BaseOptions {
286
  /** Enable export render */
287
  enabled?: boolean;
288
}
289
```
290

291
**Usage Examples:**
292

293
```vue
294
<script setup>
295
// Export props for parent component
296
const myProps = defineProps<{
297
  title: string;
298
  items: any[];
299
}>();
300

301
exportProps(myProps); // Parent can access via ref
302

303
// Export render function
304
const customRender = () => h('div', 'Custom content');
305
exportRender(customRender);
306
</script>
307
```
308

309
### Script Language Extensions
310

311
Enhanced script language support.
312

313
```typescript { .api }
314
/**
315
 * Extended script language capabilities
316
 */
317
interface OptionsScriptLang extends BaseOptions {
318
  /** Enable script language extensions */
319
  enabled?: boolean;
320
  /** Supported languages */
321
  languages?: string[];
322
}
323
```
324

325
### JSX Directive Support
326

327
JSX directive transformations.
328

329
```typescript { .api }
330
/**
331
 * JSX directive support for Vue directives in JSX
332
 */
333
interface OptionsJsxDirective extends BaseOptions {
334
  /** Enable JSX directive transformations */
335
  enabled?: boolean;
336
  /** Custom directive mappings */
337
  directives?: Record<string, string>;
338
}
339
```
340

341
**Usage Examples:**
342

343
```tsx
344
// JSX with Vue directives
345
function MyComponent() {
346
  const isVisible = ref(true);
347
  const inputRef = ref();
348
  
349
  return (
350
    <div>
351
      <input 
352
        ref={inputRef}
353
        v-show={isVisible.value}
354
        v-focus
355
        onInput={(e) => console.log(e.target.value)}
356
      />
357
      <button v-on:click={() => isVisible.value = !isVisible.value}>
358
        Toggle
359
      </button>
360
    </div>
361
  );
362
}
363
```
364

365
### Named Template (Deprecated)
366

367
Template reuse functionality (deprecated - use createReusableTemplate from VueUse instead).
368

369
```typescript { .api }
370
/**
371
 * Named template functionality (deprecated)
372
 * @deprecated Use createReusableTemplate from VueUse instead
373
 */
374
interface OptionsNamedTemplate extends BaseOptions {
375
  /** Enable named template */
376
  enabled?: boolean;
377
}
378
```
379

380
## Type Definitions
381

382
Supporting types for advanced features.
383

384
```typescript { .api }
385
// Base configuration interface
386
interface BaseOptions {
387
  /** Vue version override */
388
  version?: string;
389
  /** Enable production optimizations */
390
  isProduction?: boolean;
391
  /** Root directory */
392
  root?: string;
393
}
394

395
// Setup context from Vue
396
interface SetupContext<E = EmitsOptions> {
397
  attrs: Data;
398
  slots: Slots;
399
  emit: EmitFunction<E>;
400
  expose: (exposed?: Record<string, any>) => void;
401
}
402

403
// Reactivity transform types
404
type RefSymbol = unique symbol;
405

406
interface TransformRef<T> {
407
  [RefSymbol]: T;
408
}
409

410
// Custom ref types
411
type CustomRefFactory<T> = (
412
  track: () => void,
413
  trigger: () => void
414
) => {
415
  get: () => T;
416
  set: (value: T) => void;
417
};
418

419
// JSX types
420
namespace JSX {
421
  interface IntrinsicElements {
422
    [elem: string]: any;
423
  }
424
  
425
  interface ElementAttributesProperty {
426
    $props: {};
427
  }
428
  
429
  interface IntrinsicAttributes {
430
    key?: string | number;
431
    ref?: any;
432
  }
433
}
434
```