vue-macros

library3.1.2jsnpmunverified

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.

web-framework serialization

npm install vue-macros

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VUE-MACROS

vue-macros

web-frameworkjavascriptv3.1.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

VueMacros

✓ import VueMacros from 'unplugin-vue-macros/vite'

✗ import { VueMacros } from 'unplugin-vue-macros'

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.

VueMacros

✓ import VueMacros from 'unplugin-vue-macros/rollup'

✗ const VueMacros = require('unplugin-vue-macros/rollup')

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.

macros-global.d.ts

✓ /// <reference types="unplugin-vue-macros/macros-global" />

✗ import 'unplugin-vue-macros/macros-global'

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.

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>`.

import { defineConfig } from 'vite'; import vue from '@vitejs/plugin-vue'; import VueMacros from 'unplugin-vue-macros/vite'; export default defineConfig({ plugins: [ VueMacros({ plugins: { vue: vue(), // Required for Vue 3 projects }, }), ], }); // src/components/MyComponent.vue <script setup lang="ts"> import { ref } from 'vue'; defineOptions({ name: 'MyComponent', inheritAttrs: false, }); const count = ref(0); const increment = () => count.value++; </script> <template> <div> <h1>{{ defineOptions.name }} Example</h1> <p>Count: {{ count }}</p> <button @click="increment">Increment</button> </div> </template> <style scoped> div { padding: 1em; border: 1px solid #eee; border-radius: 8px; text-align: center; } button { margin-top: 10px; padding: 0.5em 1em; font-size: 1em; cursor: pointer; } </style>

Debug

Known issues

breakingVue 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.

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+).

affects: >=3.0.0

breakingStarting 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.

fix

Update your Node.js environment to version 20.19.0 or higher. Consider using a Node Version Manager (nvm) for easy switching.

affects: >=3.0.0-rc.0

breakingThe `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.

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.

affects: >=3.0.0

breakingThe 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.

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.

affects: >=3.0.0

gotchaSome 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.

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.

affects: >=2.x

Errors

Common errors & fixes

Error: Cannot find module 'unplugin-vue-macros/vite'

The `unplugin-vue-macros` package or its specific bundler integration was not installed or is incorrectly referenced.

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).

ESLint: 'defineOptions' is not defined. (no-undef)

ESLint is not configured to recognize global compiler macros introduced by Vue Macros, or the TypeScript environment isn't set up for global types.

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.

Syntax Error: Using 'defineModels' outside of <script setup>.

Many Vue Macros, especially those related to component options and reactivity, are designed exclusively for use within Vue's `<script setup>` block.

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.

Upgrade

Version history

3.1.2latest on npm

Audit

Dependencies

vuerequiredRequired peer dependency for Vue Macros to operate within a Vue project, supporting both Vue 2.7 and Vue 3 environments.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vue-macros/vue-macros ↗

packagehttps://www.npmjs.com/package/vue-macros ↗

homepagehttps://vue-macros.dev ↗