Vue Macros: Enhanced SFC Syntax Sugar

Common errors

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

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

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

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

Warnings

• breaking 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.
  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+).
• breaking 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.
  Fix: Update your Node.js environment to version 20.19.0 or higher. Consider using a Node Version Manager (nvm) for easy switching.
• breaking 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

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

Imports

• VueMacros
  wrong:

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

  correct:

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

  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
  wrong:

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

  correct:

  import VueMacros from '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
  wrong:

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

  correct:

  /// <reference types="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.

Quickstart

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>