{"id":12315,"library":"unplugin-vue-define-options","title":"Vue Define Options Macro Unplugin","description":"unplugin-vue-define-options is a build tool macro that enables the use of the `defineOptions` API within Vue 3's `<script setup>` syntax. This macro allows developers to define component options like `name`, `props`, `emits`, and `render` directly within the setup script, bridging the gap between Options API and Composition API for certain configurations. It is currently at version 3.1.2 and is part of the broader Vue Macros project, which sees frequent updates and feature additions, often with minor version bumps and occasional major releases (like v3.0.0) that introduce breaking changes. Its key differentiators include broad bundler support (Vite, Webpack, Rollup, esbuild via unplugin), full TypeScript compatibility, and support for both Vue 2.7 (though dropping in v3) and Vue 3.","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","define-options","unplugin","typescript"],"install":[{"cmd":"npm install unplugin-vue-define-options","lang":"bash","label":"npm"},{"cmd":"yarn add unplugin-vue-define-options","lang":"bash","label":"yarn"},{"cmd":"pnpm add unplugin-vue-define-options","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime dependency for Vue components; this package enhances Vue SFCs.","package":"vue","optional":false},{"reason":"Core dependency for integrating with various build tools.","package":"unplugin","optional":false}],"imports":[{"note":"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.","wrong":"import { DefineOptions } from 'unplugin-vue-define-options'","symbol":"DefineOptions","correct":"import DefineOptions from 'unplugin-vue-define-options/vite'"},{"note":"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.","symbol":"defineOptions","correct":"defineOptions({ name: 'MyComponent' })"},{"note":"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.","symbol":"VueMacros","correct":"import VueMacros from 'unplugin-vue-macros'"}],"quickstart":{"code":"import { defineConfig } from 'vite';\nimport vue from '@vitejs/plugin-vue';\nimport DefineOptions from 'unplugin-vue-define-options/vite';\n\nexport default defineConfig({\n  plugins: [\n    vue(),\n    DefineOptions()\n  ]\n});\n\n// src/components/MyComponent.vue\n// <script setup lang=\"ts\">\n// import { ref } from 'vue';\n//\n// defineOptions({\n//   name: 'MyComponent',\n//   inheritAttrs: false,\n//   customOption: 'hello'\n// });\n//\n// const count = ref(0);\n//\n// const increment = () => {\n//   count.value++;\n// };\n//\n// </script>\n//\n// <template>\n//   <div>\n//     <p>Count: {{ count }}</p>\n//     <button @click=\"increment\">Increment</button>\n//   </div>\n// </template>","lang":"typescript","description":"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`."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"ReferenceError: defineOptions is not defined"},{"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.","cause":"Attempting to use `unplugin-vue-define-options` version 3 or later with an unsupported Node.js version.","error":"Error: Node.js 16.x is not supported by Vue Macros v3. Please upgrade to Node.js >=20.19.0."},{"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.","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.","error":"[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."}],"ecosystem":"npm"}