Vue Define Options Macro Unplugin

Common errors

• ReferenceError: defineOptions is not defined

  cause The `unplugin-vue-define-options` plugin is not correctly configured or loaded by the bundler, preventing the `defineOptions` macro from being transformed during compilation.
  fix Double-check your bundler configuration (e.g., `vite.config.ts`, `webpack.config.js`) to ensure the `DefineOptions()` plugin is imported from the correct bundler-specific path and added to the `plugins` array. For Vite, ensure `@vitejs/plugin-vue` is also present and correctly configured.

• Error: Node.js 16.x is not supported by Vue Macros v3. Please upgrade to Node.js >=20.19.0.

  cause Attempting to use `unplugin-vue-define-options` version 3 or later with an unsupported Node.js version.
  fix Upgrade your Node.js environment to version `20.19.0` or higher. Alternatively, downgrade `unplugin-vue-define-options` to a `^2.x` version which supports Node.js 16/18.

• [Vue warn]: Component provided a 'name' option that is already set. This is most likely due to a compiler error where 'name' is being set twice.

  cause The component is already receiving a `name` property from another source (e.g., a build tool setting it automatically, or another macro), and `defineOptions` is attempting to set it again.
  fix Review your build configuration and other Vue macros. Ensure only one source is providing the `name` option. If you are using `unplugin-vue-macros` in combination, ensure there are no conflicting options being set for component names.

Warnings

• breaking Version 3.0.0 introduced significant breaking changes, including dropping support for Vue 2, Webpack 4, Node.js 16, and Node.js 18. Projects relying on these older environments must remain on v2 or earlier.
  Fix: Upgrade your project to Vue 3, Webpack 5+, and Node.js >=20.19.0 (as of v3.0.0-rc.0). Alternatively, stick to `unplugin-vue-define-options@^2.x`.
• breaking The `shortEmits` feature was disabled in Vue 3.3 by this package due to changes in Vue itself, which might affect projects relying on that specific macro behavior.
  Fix: Review your `emits` definitions and adapt them to Vue 3.3's standard `defineEmits` usage, avoiding the `shortEmits` syntax if you've upgraded Vue.
• gotcha This package is an 'unplugin', meaning its integration method differs based on your bundler (Vite, Webpack, Rollup, etc.). Incorrect import paths or plugin registration can lead to the macro not being processed.
  Fix: Always import the plugin from its bundler-specific entry point (e.g., `unplugin-vue-define-options/vite` for Vite, `unplugin-vue-define-options/webpack` for Webpack) and ensure it's added to your bundler's plugin array correctly.
• gotcha The `defineOptions` macro, while syntactically similar to standard JavaScript, is a compile-time transformation. It will not work without the unplugin correctly configured in your build setup, leading to runtime errors if Vue encounters an unrecognized global function.
  Fix: Ensure `unplugin-vue-define-options` is properly installed and configured in your `vite.config.ts`, `webpack.config.js`, or similar build configuration file. Verify that your project's build process is successfully running the unplugin transformations.

Install

• npm install unplugin-vue-define-options npm
• yarn add unplugin-vue-define-options yarn
• pnpm add unplugin-vue-define-options pnpm

Imports

• DefineOptions
  wrong:

  import { DefineOptions } from 'unplugin-vue-define-options'

  correct:

  import DefineOptions from 'unplugin-vue-define-options/vite'

  The unplugin is typically imported from a bundler-specific entry point (e.g., '/vite', '/webpack'). The main package export is not directly used for configuration.
• defineOptions

  defineOptions({ name: 'MyComponent' })

  This is a global macro provided by the unplugin, not an explicit import in the Vue component file itself. The unplugin transforms this macro during compilation.
• VueMacros

  import VueMacros from 'unplugin-vue-macros'

  While `unplugin-vue-define-options` is a standalone package, it's often used as part of the `unplugin-vue-macros` bundle for a comprehensive set of macros. If using the combined package, the specific macro might not need direct import.

Quickstart

Demonstrates how to configure `unplugin-vue-define-options` in a Vite project and use the `defineOptions` macro in a Vue Single File Component (SFC) to set component options like `name`.

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import DefineOptions from 'unplugin-vue-define-options/vite';

export default defineConfig({
  plugins: [
    vue(),
    DefineOptions()
  ]
});

// src/components/MyComponent.vue
// <script setup lang="ts">
// import { ref } from 'vue';
//
// defineOptions({
//   name: 'MyComponent',
//   inheritAttrs: false,
//   customOption: 'hello'
// });
//
// const count = ref(0);
//
// const increment = () => {
//   count.value++;
// };
//
// </script>
//
// <template>
//   <div>
//     <p>Count: {{ count }}</p>
//     <button @click="increment">Increment</button>
//   </div>
// </template>