Registry / web-framework / unplugin-vue-define-options

unplugin-vue-define-options

library3.1.2jsnpmunverified

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.

web-framework

npm install unplugin-vue-define-options

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · UNPLUGIN-VUE-DEFIN

unplugin-vue-define-options

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.

DefineOptions

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

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

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.

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>

Debug

Known issues

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

affects: >=3.0.0

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

affects: >=3.0.0

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

affects: >=1.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: defineOptions is not defined

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.

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.

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.

Upgrade

Version history

3.1.2latest on npm

Audit

Dependencies

vuerequiredRuntime dependency for Vue components; this package enhances Vue SFCs.

unpluginrequiredCore dependency for integrating with various build tools.

Agent activity

11 hits · last 30 days

node

Resources

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

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

homepagehttps://vue-macros.dev/guide/macros/define-options.html ↗