{"id":12524,"library":"vue-macros","title":"Vue Macros: Enhanced SFC Syntax Sugar","description":"Vue Macros is a collection of experimental and advanced compiler macros and syntax sugar designed to significantly enhance the development experience for Vue.js Single File Components (SFCs). It serves as a playground for new language features and proposals that extend Vue's capabilities beyond its official API, often simplifying boilerplate and improving reactivity patterns. The current stable version is 3.1.2, with an active release cadence reflecting ongoing development and frequent updates. Key differentiators include its modular nature, allowing developers to selectively enable specific macros, and its integration as an `unplugin`, providing broad compatibility across various build tools like Vite, Rollup, Webpack, and Nuxt. It brings features like `defineOptions`, `defineModels`, and `definePropsRefs` that streamline component definition and data flow, offering type safety and improved developer ergonomics.","status":"active","version":"3.1.2","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 vue-macros","lang":"bash","label":"npm"},{"cmd":"yarn add vue-macros","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-macros","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for Vue Macros to operate within a Vue project, supporting both Vue 2.7 and Vue 3 environments.","package":"vue","optional":false}],"imports":[{"note":"The primary way to use Vue Macros is by importing the plugin factory tailored for your specific build tool (e.g., '/vite', '/rollup', '/webpack'). Named imports from the root 'unplugin-vue-macros' are incorrect for plugin setup.","wrong":"import { VueMacros } from 'unplugin-vue-macros'","symbol":"VueMacros","correct":"import VueMacros from 'unplugin-vue-macros/vite'"},{"note":"While CommonJS `require` might work in some older setups, Vue Macros primarily targets modern ESM environments and build tools. Using `import` syntax is the idiomatic and recommended approach.","wrong":"const VueMacros = require('unplugin-vue-macros/rollup')","symbol":"VueMacros","correct":"import VueMacros from 'unplugin-vue-macros/rollup'"},{"note":"For TypeScript support and global macro type inference in your project (e.g., for `defineOptions` in SFCs), you typically add a `types` entry to your `tsconfig.json` or use a triple-slash directive for global types, rather than a direct import in a `.ts` or `.vue` file.","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';\n\nexport default defineConfig({\n  plugins: [\n    VueMacros({\n      plugins: {\n        vue: vue(), // Required for Vue 3 projects\n      },\n    }),\n  ],\n});\n\n// src/components/MyComponent.vue\n<script setup lang=\"ts\">\nimport { ref } from 'vue';\n\ndefineOptions({\n  name: 'MyComponent',\n  inheritAttrs: false,\n});\n\nconst count = ref(0);\nconst increment = () => count.value++;\n</script>\n\n<template>\n  <div>\n    <h1>{{ defineOptions.name }} Example</h1>\n    <p>Count: {{ count }}</p>\n    <button @click=\"increment\">Increment</button>\n  </div>\n</template>\n\n<style scoped>\ndiv {\n  padding: 1em;\n  border: 1px solid #eee;\n  border-radius: 8px;\n  text-align: center;\n}\nbutton {\n  margin-top: 10px;\n  padding: 0.5em 1em;\n  font-size: 1em;\n  cursor: pointer;\n}\n</style>","lang":"typescript","description":"Demonstrates how to configure Vue Macros in a Vite project and use the `defineOptions` macro in a Vue 3 SFC to set component options directly within `<script setup>`."},"warnings":[{"fix":"Upgrade Node.js to version >=20.19.0. Migrate Vue.js projects to Vue 3.x and ensure your build tool (e.g., Webpack) is on a compatible version (Webpack 5+).","message":"Vue Macros v3.x dropped official support for Vue 2, Webpack 4, and Node.js versions 16 and 18. Users on these older environments should remain on Vue Macros v2.x or upgrade their project dependencies.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update your Node.js environment to version 20.19.0 or higher. Consider using a Node Version Manager (nvm) for easy switching.","message":"Starting with Vue Macros v3.0.0-rc.0, the minimum required Node.js version is `20.19.0`. Running with older Node.js versions will result in errors.","severity":"breaking","affected_versions":">=3.0.0-rc.0"},{"fix":"For Vue 3.3+, use the officially provided `defineEmits` features or check Vue Macros documentation for any alternative configuration to re-enable or replace `shortEmits` functionality.","message":"The `shortEmits` macro is disabled by default in Vue 3.3 and later due to official integration or conflicts. If you relied on this specific macro, its behavior might change or require explicit re-enabling if supported.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update import paths (e.g., `unplugin-vue-macros/vite` instead of `vue-macros` directly if used as a plugin) and ensure your project uses ESM-compatible bundling. Review the migration guide for specific package name changes.","message":"The main package name was renamed in v3, and the CJS build was dropped for most packages, excluding volar-related ones. This impacts how packages are imported and bundled.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your `tsconfig.json` includes `\"types\": [\"unplugin-vue-macros/macros-global\"]` and your Volar/Vue Language Features (Volar) extension in VSCode is updated. For ESLint, ensure `eslint-plugin-vue` is up-to-date and configured for compiler macros.","message":"Some macros introduce new syntax that IDEs and linters might not immediately understand without proper configuration. This can lead to false positive errors or lack of type inference.","severity":"gotcha","affected_versions":">=2.x"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `unplugin-vue-macros` is installed as a development dependency: `npm install -D unplugin-vue-macros` or `yarn add -D unplugin-vue-macros`. Verify the import path in your build configuration matches your bundler (e.g., `unplugin-vue-macros/vite` for Vite).","cause":"The `unplugin-vue-macros` package or its specific bundler integration was not installed or is incorrectly referenced.","error":"Error: Cannot find module 'unplugin-vue-macros/vite'"},{"fix":"Add `\"unplugin-vue-macros/macros-global\"` to the `types` array in your `tsconfig.json`. For ESLint, ensure `eslint-plugin-vue` is updated to at least v8 and configure your `.eslintrc` to recognize `vue/setup-compiler-macros` if still relevant for older setups.","cause":"ESLint is not configured to recognize global compiler macros introduced by Vue Macros, or the TypeScript environment isn't set up for global types.","error":"ESLint: 'defineOptions' is not defined. (no-undef)"},{"fix":"Relocate the macro call (e.g., `defineModels`, `defineOptions`) into a `<script setup>` block in your Single File Component. These are compiler macros and are not intended for use in regular `<script>` blocks or JavaScript/TypeScript files.","cause":"Many Vue Macros, especially those related to component options and reactivity, are designed exclusively for use within Vue's `<script setup>` block.","error":"Syntax Error: Using 'defineModels' outside of <script setup>."}],"ecosystem":"npm"}