{"id":12316,"library":"unplugin-vue-macros","title":"Vue Macros Unplugin","description":"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.","status":"active","version":"2.14.5","language":"javascript","source_language":"en","source_url":"https://github.com/vue-macros/vue-macros","tags":["javascript","vue-macros","macros","vue","sfc","setup","script-setup","unplugin","typescript"],"install":[{"cmd":"npm install unplugin-vue-macros","lang":"bash","label":"npm"},{"cmd":"yarn add unplugin-vue-macros","lang":"bash","label":"yarn"},{"cmd":"pnpm add unplugin-vue-macros","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for Vue.js projects, supporting both Vue 2.7+ and Vue 3.2.25+.","package":"vue","optional":false}],"imports":[{"note":"For Vite, import the plugin from the '/vite' entry point. Similar paths exist for other bundlers like '/webpack', '/rollup', and '/esbuild'.","wrong":"import VueMacros from 'unplugin-vue-macros'","symbol":"VueMacros","correct":"import VueMacros from 'unplugin-vue-macros/vite'"},{"note":"A resolver might be needed for automatic component imports with `unplugin-vue-components`. The exact path may vary or be part of sub-packages.","wrong":"import { VueMacrosResolver } from 'unplugin-vue-macros'","symbol":"VueMacrosResolver","correct":"import { VueMacrosResolver } from 'unplugin-vue-macros/dist/resolvers'"},{"note":"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.","wrong":"import 'unplugin-vue-macros/macros-global'","symbol":"macros-global.d.ts","correct":"/// <reference types=\"unplugin-vue-macros/macros-global\" />"}],"quickstart":{"code":"import { defineConfig } from 'vite';\nimport Vue from '@vitejs/plugin-vue';\nimport VueMacros from 'unplugin-vue-macros/vite';\nimport AutoImport from 'unplugin-auto-import/vite';\n\nexport default defineConfig({\n  plugins: [\n    VueMacros({\n      // The `plugins` option is essential for Vue Macros to correctly process Vue SFCs.\n      // It should include the `@vitejs/plugin-vue` instance.\n      plugins: {\n        vue: Vue(),\n        // vueJsx: VueJsx(), // Uncomment if you are using JSX\n      },\n      // You can also enable/disable specific macros here\n      defineOptions: true,\n      defineModels: true,\n    }),\n    // Optional: AutoImport can be used to automatically import Vue Macros APIs\n    AutoImport({\n      imports: ['vue', '@vue/composition-api'],\n      dts: './auto-imports.d.ts',\n      macros: {\n        // Enable definePropsRefs if you use it globally or want auto-import\n        // definePropsRefs: true,\n      },\n      eslintrc: {\n        enabled: true,\n        filepath: './.eslintrc-auto-import.json',\n      },\n    }),\n  ],\n});","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Review your component emit declarations; adapt to standard Vue 3.3+ `defineEmits` usage if `shortEmits` was previously relied upon.","message":"The `shortEmits` macro functionality was disabled in Vue 3.3 for `unplugin-vue-macros` v3.0.0.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your development and build environments use Node.js version 20.19.0 or higher.","message":"With the v3 release, the minimum Node.js requirement was raised to `20.19.0`.","severity":"breaking","affected_versions":">=3.0.0"},{"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'`.","message":"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`).","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"To ensure proper TypeScript support for global macros (like `defineOptions`, `defineModels`), you need to configure `tsconfig.json` to include the `macros-global` types.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change the import statement to include the bundler, e.g., `import VueMacros from 'unplugin-vue-macros/vite'` for Vite.","cause":"Attempting to import the plugin without specifying the bundler-specific entry point.","error":"Error: Cannot find module 'unplugin-vue-macros'"},{"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`.","cause":"The `defineOptions` macro or other Vue Macros features are not recognized by the compiler or IDE.","error":"ReferenceError: defineOptions is not defined"},{"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.","cause":"The `shortEmits` macro was disabled in Vue 3.3 for Vue Macros v3, but the older syntax is still being used.","error":"Vue 3: 'defineEmits' is not defined in current scope (when using shortEmits)"},{"fix":"Upgrade your Node.js version to 20.19.0 or higher.","cause":"Your Node.js environment does not meet the minimum requirement for Vue Macros v3.","error":"Node.js version x.y.z is not supported. Required Node.js >=20.19.0"}],"ecosystem":"npm"}