Registry / web-framework / unplugin-vue-macros

unplugin-vue-macros

library2.14.5jsnpmunverified

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.

web-framework

npm install unplugin-vue-macros

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · UNPLUGIN-VUE-MACRO

unplugin-vue-macros

web-frameworkjavascriptv2.14.5

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'

For Vite, import the plugin from the '/vite' entry point. Similar paths exist for other bundlers like '/webpack', '/rollup', and '/esbuild'.

VueMacrosResolver

✓ import { VueMacrosResolver } from 'unplugin-vue-macros/dist/resolvers'

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

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

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

✗ import '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.

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', }, }), ], });

Debug

Known issues

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

affects: >=3.0.0

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

affects: >=3.0.0

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

affects: >=3.0.0

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

affects: >=1.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

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

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

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)

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

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.

Upgrade

Version history

2.14.5latest on npm

Audit

Dependencies

vuerequiredPeer dependency for Vue.js projects, supporting both Vue 2.7+ and Vue 3.2.25+.

Agent activity

2 hits · last 30 days

node

Resources

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

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

homepagehttps://vue-macros.dev ↗