Vue Macros Unplugin

2.14.5 · active · verified Sun Apr 19

unplugin-vue-macros is a comprehensive collection of macros and syntax sugar designed to enhance the developer experience in Vue.js projects. It operates as an `unplugin`, providing broad compatibility across various bundlers like Vite, Webpack, Rollup, and esbuild. This library introduces experimental and advanced features that may not yet be officially adopted by Vue's core, simplifying common patterns and offering more expressive ways to write components. The current stable version, as per the recent changelog, is v3.1.2. The project maintains an active release cadence, frequently pushing minor bug fixes and features, with significant breaking changes typically occurring in major version bumps. Key differentiators include its modular design, allowing developers to pick and choose specific macros, its seamless integration via the `unplugin` system, and robust TypeScript and Volar support.

Common errors

```
Error: Cannot find module 'unplugin-vue-macros'
```
cause Attempting to import the plugin without specifying the bundler-specific entry point.

fix Change the import statement to include the bundler, e.g., `import VueMacros from 'unplugin-vue-macros/vite'` for Vite.
```
ReferenceError: defineOptions is not defined
```
cause The `defineOptions` macro or other Vue Macros features are not recognized by the compiler or IDE.

fix Ensure `unplugin-vue-macros` is correctly configured in your bundler and that TypeScript type references (`tsconfig.json` `types` array or `/// <reference>`) are set up for `macros-global`.
```
Vue 3: 'defineEmits' is not defined in current scope (when using shortEmits)
```
cause The `shortEmits` macro was disabled in Vue 3.3 for Vue Macros v3, but the older syntax is still being used.

fix Update your `defineEmits` syntax to the standard Vue 3.3+ approach, or verify if an alternative macro is available and enabled in your configuration.
```
Node.js version x.y.z is not supported. Required Node.js >=20.19.0
```
cause Your Node.js environment does not meet the minimum requirement for Vue Macros v3.

fix Upgrade your Node.js version to 20.19.0 or higher.

Warnings

breaking Version 3.0.0 of unplugin-vue-macros introduced significant breaking changes, dropping support for Vue 2, Webpack 4, and Node.js versions 16 and 18. Users must migrate their projects to Vue 3, Webpack 5+, and Node.js 20.19.0+ when upgrading to v3.
Fix: Upgrade your project to Vue 3 (>=3.2.25), Webpack 5+, and Node.js >=20.19.0. Refer to the official migration guide from v2 to v3 for detailed steps.
breaking The `shortEmits` macro functionality was disabled in Vue 3.3 for `unplugin-vue-macros` v3.0.0.
Fix: Review your component emit declarations; adapt to standard Vue 3.3+ `defineEmits` usage if `shortEmits` was previously relied upon.
breaking With the v3 release, the minimum Node.js requirement was raised to `20.19.0`.
Fix: Ensure your development and build environments use Node.js version 20.19.0 or higher.
gotcha When integrating `unplugin-vue-macros` into a bundler, you must use the correct bundler-specific entry point (e.g., `unplugin-vue-macros/vite`, `unplugin-vue-macros/webpack`).
Fix: Always import the plugin from its specific bundler entry point in your `vite.config.ts`, `webpack.config.js`, etc., for example: `import VueMacros from 'unplugin-vue-macros/vite'`.
gotcha To ensure proper TypeScript support for global macros (like `defineOptions`, `defineModels`), you need to configure `tsconfig.json` to include the `macros-global` types.
Fix: Add `"unplugin-vue-macros/macros-global"` to the `compilerOptions.types` array in your `tsconfig.json` or add a triple-slash directive to a `.d.ts` file.

Install

npm install unplugin-vue-macros npm
yarn add unplugin-vue-macros yarn
pnpm add unplugin-vue-macros pnpm

Imports

VueMacros
wrong:
```
import VueMacros from 'unplugin-vue-macros'
```
correct:
```
import VueMacros from 'unplugin-vue-macros/vite'
```
For Vite, import the plugin from the '/vite' entry point. Similar paths exist for other bundlers like '/webpack', '/rollup', and '/esbuild'.
VueMacrosResolver
wrong:
```
import { VueMacrosResolver } from 'unplugin-vue-macros'
```
correct:
```
import { VueMacrosResolver } from 'unplugin-vue-macros/dist/resolvers'
```
A resolver might be needed for automatic component imports with `unplugin-vue-components`. The exact path may vary or be part of sub-packages.
macros-global.d.ts
wrong:
```
import 'unplugin-vue-macros/macros-global'
```
correct:
```
/// <reference types="unplugin-vue-macros/macros-global" />
```
For TypeScript support, add a reference to `macros-global` in your `tsconfig.json`'s `types` array or directly in a `.d.ts` file to enable global macro types.

Quickstart

This Vite configuration demonstrates how to integrate `unplugin-vue-macros` into a Vue 3 TypeScript project, enabling various macros and optionally setting up auto-imports.

import { defineConfig } from 'vite';
import Vue from '@vitejs/plugin-vue';
import VueMacros from 'unplugin-vue-macros/vite';
import AutoImport from 'unplugin-auto-import/vite';

export default defineConfig({
  plugins: [
    VueMacros({
      // The `plugins` option is essential for Vue Macros to correctly process Vue SFCs.
      // It should include the `@vitejs/plugin-vue` instance.
      plugins: {
        vue: Vue(),
        // vueJsx: VueJsx(), // Uncomment if you are using JSX
      },
      // You can also enable/disable specific macros here
      defineOptions: true,
      defineModels: true,
    }),
    // Optional: AutoImport can be used to automatically import Vue Macros APIs
    AutoImport({
      imports: ['vue', '@vue/composition-api'],
      dts: './auto-imports.d.ts',
      macros: {
        // Enable definePropsRefs if you use it globally or want auto-import
        // definePropsRefs: true,
      },
      eslintrc: {
        enabled: true,
        filepath: './.eslintrc-auto-import.json',
      },
    }),
  ],
});

view raw JSON →