0
# unplugin-vue-macros
1

2
unplugin-vue-macros is a comprehensive collection of macros and syntax sugar for Vue.js that extends the capabilities of `<script setup>` and Single File Components (SFCs). It provides 20+ macros including `defineOptions`, `defineProps`, `defineEmit`, `defineModels`, and many more, along with advanced features like reactivity transform, JSX directive support, and setup component syntax.
3

4
## Package Information
5

6
- **Package Name**: unplugin-vue-macros
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install unplugin-vue-macros`
10
- **Vue Compatibility**: Vue 2.7+ and Vue 3
11

12
## Core Imports
13

14
For bundler plugins:
15

16
```typescript
17
// Vite
18
import VueMacros from "unplugin-vue-macros/vite";
19

20
// Webpack
21
import VueMacros from "unplugin-vue-macros/webpack";
22

23
// Rollup
24
import VueMacros from "unplugin-vue-macros/rollup";
25

26
// esbuild  
27
import VueMacros from "unplugin-vue-macros/esbuild";
28

29
// Rspack
30
import VueMacros from "unplugin-vue-macros/rspack";
31

32
// Rolldown
33
import VueMacros from "unplugin-vue-macros/rolldown";
34
```
35

36
For configuration and types:
37

38
```typescript
39
import { defineConfig, resolveOptions, type Options } from "unplugin-vue-macros";
40
```
41

42
For runtime utilities:
43

44
```typescript
45
import { useRef } from "unplugin-vue-macros/runtime";
46
```
47

48
For Volar integration:
49

50
```typescript
51
import { define } from "unplugin-vue-macros/volar";
52
```
53

54
## Basic Usage
55

56
### Bundler Setup
57

58
**Vite Configuration:**
59

60
```typescript
61
import { defineConfig } from "vite";
62
import vue from "@vitejs/plugin-vue";
63
import VueMacros from "unplugin-vue-macros/vite";
64

65
export default defineConfig({
66
  plugins: [
67
    VueMacros({
68
      plugins: {
69
        vue: vue(),
70
        // Additional plugin options
71
      },
72
    }),
73
  ],
74
});
75
```
76

77
**Nuxt Configuration:**
78

79
```typescript
80
// nuxt.config.ts
81
export default defineNuxtConfig({
82
  modules: [
83
    "@vue-macros/nuxt",
84
  ],
85
});
86
```
87

88
### Vue Component Usage
89

90
**Basic Macro Usage:**
91

92
```vue
93
<script setup>
94
// Define component options
95
defineOptions({
96
  name: "MyComponent",
97
  inheritAttrs: false,
98
});
99

100
// Define props with defaults and validation
101
const { name, age = 18 } = defineProps<{
102
  name: string;
103
  age?: number;
104
}>();
105

106
// Define emits
107
const emit = defineEmit<{
108
  update: [value: string];
109
  delete: [];
110
}>();
111

112
// Define models (Vue 3.4+ style with macro)
113
const modelValue = defineModel<string>();
114
const checked = defineModel<boolean>("checked");
115

116
// Define slots with types
117
const slots = defineSlots<{
118
  default(): any;
119
  header(props: { title: string }): any;
120
}>();
121

122
// Chain call for props
123
const { count } = $defineProps<{ count: number }>();
124
</script>
125
```
126

127
## Architecture
128

129
Vue Macros uses the unplugin architecture combined with Vue's transform pipeline:
130

131
- **Unplugin Core**: Universal plugin system providing adapters for all major bundlers
132
- **Transform Pipeline**: Multi-stage AST transformation processing Vue SFCs and JavaScript/TypeScript files
133
- **Macro Registry**: Centralized system managing 20+ macro plugins
134
- **Configuration System**: Flexible options resolution with per-macro configuration
135
- **Type System**: Complete TypeScript integration with Vue 2.7 and Vue 3 type definitions
136
- **Volar Integration**: Language server support for IDE features
137

138
## Capabilities
139

140
### Main Plugin
141

142
The combined plugin instance that includes all macro plugins.
143

144
```typescript { .api }
145
declare const plugin: UnpluginCombineInstance<Options | undefined>;
146

147
// Bundler-specific exports
148
export default plugin;
149
```
150

151
### Configuration System
152

153
Comprehensive configuration options for all macros.
154

155
```typescript { .api }
156
/**
157
 * Define configuration for Vue Macros
158
 * @param options - Configuration options
159
 * @returns Configuration object
160
 */
161
function defineConfig(options: Options): Options;
162

163
/**
164
 * Resolve configuration options with defaults
165
 * @param options - User configuration options  
166
 * @param cwd - Current working directory
167
 * @returns Resolved configuration
168
 */
169
function resolveOptions(options?: Options, cwd?: string): OptionsResolved;
170

171
interface Options extends OptionsCommon {
172
  // Props & Models
173
  chainCall?: boolean | OptionsChainCall;
174
  defineProps?: boolean | OptionsDefineProps;
175
  definePropsRefs?: boolean | OptionsDefinePropsRefs;
176
  defineModels?: boolean | OptionsDefineModels;
177
  defineProp?: boolean | OptionsDefineProp;
178
  
179
  // Component Options
180
  defineOptions?: boolean | OptionsDefineOptions;
181
  defineSlots?: boolean | OptionsDefineSlots;
182
  defineEmit?: boolean | OptionsDefineEmit;
183
  defineRender?: boolean | OptionsDefineRender;
184
  
185
  // Advanced Features
186
  betterDefine?: boolean | OptionsBetterDefine;
187
  reactivityTransform?: boolean | OptionsReactivityTransform;
188
  setupComponent?: boolean | OptionsSetupComponent;
189
  setupSFC?: boolean | OptionsSetupSFC;
190
  setupBlock?: boolean | OptionsSetupBlock;
191
  
192
  // Syntax Sugar
193
  shortEmits?: boolean | OptionsShortEmits;
194
  shortVmodel?: boolean | OptionsShortVmodel;
195
  shortBind?: boolean | OptionsShortBind;
196
  booleanProp?: boolean | OptionsBooleanProp;
197
  
198
  // Export Features
199
  exportExpose?: boolean | OptionsExportExpose;
200
  exportProps?: boolean | OptionsExportProps;
201
  exportRender?: boolean | OptionsExportRender;
202
  
203
  // Optimization
204
  hoistStatic?: boolean | OptionsHoistStatic;
205
  
206
  // JSX Features
207
  jsxDirective?: boolean | OptionsJsxDirective;
208
  
209
  // Language Features
210
  scriptLang?: boolean | OptionsScriptLang;
211
  
212
  // Styling
213
  defineStyleX?: boolean | OptionsDefineStyleX;
214
  
215
  // Templates
216
  namedTemplate?: boolean | OptionsNamedTemplate;
217
}
218

219
interface OptionsCommon {
220
  root?: string;
221
  plugins?: {
222
    vue?: any;
223
    vueJsx?: any;
224
    vueRouter?: any;
225
  };
226
}
227
```
228

229
[Configuration](./configuration.md)
230

231
### Props and Models Macros
232

233
Enhanced props and model definition capabilities.
234

235
```typescript { .api }
236
// Chain call syntax for props
237
declare const $defineProps: typeof definePropsChainCall;
238
declare const defineProps: DefineProps;
239

240
// Props refs for easy reactive access
241
declare function definePropsRefs<T>(): PropsRefs<T>;
242

243
// Individual prop definition
244
declare function defineProp<T>(name: string, options?: PropOptions<T>): T;
245

246
// Enhanced models
247
declare function defineModels<T>(): Models<T>;
248
```
249

250
[Props and Models](./props-models.md)
251

252
### Component Definition Macros
253

254
Core macros for component definition.
255

256
```typescript { .api }
257
// Define component options (Vue 2.7+ / Vue 3.0-3.2)
258
declare function defineOptions(options: ComponentOptions): void;
259

260
// Define component slots with types
261
declare function defineSlots<T>(): Slots<T>;
262

263
// Define single emit function
264
declare function defineEmit<T>(name: string): EmitFunction<T>;
265

266
// Define render function
267
declare function defineRender(render: RenderFunction): void;
268
```
269

270
[Component Definition](./component-definition.md)
271

272
### Advanced Features
273

274
Advanced macros and transformations.
275

276
```typescript { .api }
277
// Better define integration
278
declare function betterDefine(): void;
279

280
// Reactivity transform
281
declare const $ref: typeof ref;
282
declare const $computed: typeof computed;
283
declare const $shallowRef: typeof shallowRef;
284

285
// Setup component syntax
286
declare function setupComponent(options: SetupComponentOptions): void;
287

288
// Setup SFC
289
declare function setupSFC(): void;
290
```
291

292
[Advanced Features](./advanced-features.md)
293

294
### Syntax Sugar
295

296
Shorthand syntax and convenience features.
297

298
```typescript { .api }
299
// Short emits: emits(eventName, ...args)
300
declare function emits<T>(name: keyof T, ...args: any[]): void;
301

302
// Short v-model: ::modelValue
303
// Short bind: :prop-name
304

305
// Boolean props: +prop-name
306
```
307

308
[Syntax Sugar](./syntax-sugar.md)
309

310
### Runtime Utilities
311

312
Runtime helper functions and references.
313

314
```typescript { .api }
315
/**
316
 * Alias for shallowRef from Vue
317
 */
318
export const useRef: typeof shallowRef;
319
```
320

321
### Type Definitions
322

323
Complete TypeScript integration with utility types.
324

325
```typescript { .api }
326
// Feature option types
327
type FeatureName = keyof FeatureOptionsMap;
328
type FeatureOptions = FeatureOptionsMap[FeatureName];
329

330
// Configuration types
331
type OptionsResolved = Required<OptionsCommon> & {
332
  [K in keyof FeatureOptionsMap]: false | FeatureOptionsMap[K];
333
};
334

335
// Props utilities
336
type PropsRefs<T> = {
337
  [K in keyof T]: Ref<T[K]>;
338
};
339

340
// Model utilities  
341
type Models<T> = {
342
  [K in keyof T]: WritableComputedRef<T[K]>;
343
};
344

345
// Generic utilities
346
type RecordToUnion<T> = T[keyof T];
347
type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
348
```