{"id":12455,"library":"vue-demi","title":"Vue Demi: Universal Vue Library Helper","description":"Vue Demi (French for 'half') is a foundational utility library designed for authors building universal Vue libraries that must operate seamlessly across both Vue 2 and Vue 3 environments. It intelligently abstracts away the underlying Vue version, redirecting common Composition API imports (e.g., `ref`, `reactive`, `defineComponent`) to the appropriate Vue runtime (`vue@2` with `@vue/composition-api` or `vue@3`). The current stable version is `0.14.10`, with a consistent and active release cadence that focuses on compatibility fixes, minor feature enhancements, and addressing edge cases, often seeing several patch releases per month. Its key differentiator is providing a single, unified API surface for Composition API features and core Vue utilities, enabling developers to write code once and deploy it to both major Vue versions without needing conditional imports or complex build setups. It also exposes utilities like `isVue2` and `isVue3` for version-specific logic and a `Vue2` export for safely accessing global Vue 2 APIs (e.g., `Vue.config`, `Vue.set`).","status":"active","version":"0.14.10","language":"javascript","source_language":"en","source_url":"https://github.com/antfu/vue-demi","tags":["javascript","typescript"],"install":[{"cmd":"npm install vue-demi","lang":"bash","label":"npm"},{"cmd":"yarn add vue-demi","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-demi","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Vue 2.x versions below 2.7 to provide the Composition API, as a peer dependency for libraries using vue-demi.","package":"@vue/composition-api","optional":true},{"reason":"The core Vue runtime, required as a peer dependency for any library consuming vue-demi.","package":"vue","optional":false}],"imports":[{"note":"This is the primary way to import core Composition API utilities universally across Vue 2 and Vue 3.","wrong":"import { ref } from 'vue'; import { reactive } from '@vue/composition-api'","symbol":"ref, reactive, defineComponent","correct":"import { ref, reactive, defineComponent } from 'vue-demi'"},{"note":"Provides reliable runtime environment detection for conditional logic within universal libraries. `version` maps to `Vue.version`.","wrong":"if (Vue.version.startsWith('2'))","symbol":"isVue2, isVue3, version","correct":"import { isVue2, isVue3, version } from 'vue-demi'"},{"note":"`Vue2` provides access to Vue 2's global API (e.g., `Vue2.set`). It is `undefined` in Vue 3 environments, so always check `if (Vue2)`.","symbol":"Vue2","correct":"import { Vue2 } from 'vue-demi'"},{"note":"Explicitly installs the Composition API plugin for Vue 2.x, which `vue-demi` often handles automatically. It is a no-op in Vue 3.","symbol":"install","correct":"import { install } from 'vue-demi'"}],"quickstart":{"code":"import { ref, computed, isVue2, isVue3, version as vueVersion, getCurrentInstance } from 'vue-demi';\n\n/**\n * A universal composable that provides a reactive counter.\n * Works across Vue 2 (with Composition API) and Vue 3.\n */\nexport function useUniversalCounter(initialValue: number = 0) {\n  const count = ref(initialValue);\n  const double = computed(() => count.value * 2);\n\n  const increment = () => {\n    count.value++;\n  };\n\n  // Demonstrate version-specific logic\n  if (isVue2) {\n    console.log(`[Vue Demi] Running in Vue 2 (version: ${vueVersion}).`);\n    // Example of accessing Vue 2 instance if needed (caution: not always universal)\n    const vm = getCurrentInstance()?.proxy;\n    if (vm) {\n      console.log('Vue 2 VM detected:', vm.$options.name);\n    }\n  } else if (isVue3) {\n    console.log(`[Vue Demi] Running in Vue 3 (version: ${vueVersion}).`);\n    // Example of accessing Vue 3 instance (different structure)\n    const instance = getCurrentInstance();\n    if (instance) {\n      console.log('Vue 3 instance detected:', instance.type.name);\n    }\n  }\n\n  return {\n    count,\n    double,\n    increment,\n    isVue2,\n    isVue3,\n    vueVersion\n  };\n}\n\n// To test in a Vue 3 environment:\n// npm install vue@3 vue-demi\n// npx vue-demi-switch 3\n// Then integrate `useUniversalCounter` into a Vue 3 component.\n\n// To test in a Vue 2 environment (requires Composition API plugin):\n// npm install vue@2 @vue/composition-api vue-demi\n// npx vue-demi-switch 2\n// Make sure @vue/composition-api is installed for Vue 2.6.x.\n// Then integrate `useUniversalCounter` into a Vue 2 component.","lang":"typescript","description":"This quickstart demonstrates creating a universal composable function using `vue-demi`'s reactivity APIs and version detection (`isVue2`, `isVue3`), suitable for libraries supporting both Vue 2 and Vue 3."},"warnings":[{"fix":"Refer to the `vue-demi` README for the exact `peerDependencies` and `peerDependenciesMeta` configuration (e.g., `\"vue\": \"^2.0.0 || >=3.0.0\"`, `\"@vue/composition-api\": { \"optional\": true }`).","message":"Library authors must correctly configure `vue` and `@vue/composition-api` as `peerDependencies` in their `package.json` to ensure `vue-demi` can correctly resolve the user's Vue environment and guide installations.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Add `exclude: ['vue-demi']` to the `optimizeDeps` configuration in your `vite.config.js` or `vite.config.ts`.","message":"When using `vue-demi` within a Vite project, it must be explicitly excluded from Vite's dependency pre-bundling to prevent module resolution issues and ensure dynamic version switching works correctly.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Call `install()` imported from `vue-demi` at your library's entry point or plugin registration. This function is a no-op in Vue 3, making it safe to call universally.","message":"While `vue-demi` typically auto-installs the Composition API plugin for Vue 2 environments, in specific complex plugin setups or environments where auto-installation is unreliable, manual installation might be required.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always check `if (Vue2)` before attempting to use any properties or methods from the `Vue2` object to avoid runtime errors in Vue 3 applications.","message":"The `Vue2` export from `vue-demi` is provided to access global Vue 2 APIs (like `Vue.set` or `Vue.del`) but will be `undefined` when running in a Vue 3 environment.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure you are using `vue-demi` version `0.14.9` or newer, as recent updates include fixes for broader compatibility regarding `globalThis`.","message":"Older browser environments (pre-Chrome 52 / Firefox 55) may not support `globalThis`, leading to `ReferenceError: globalThis is not defined`.","severity":"gotcha","affected_versions":"<0.14.9"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add `exclude: ['vue-demi']` to the `optimizeDeps` option in your `vite.config.js`.","cause":"Vite's dependency pre-bundling interferes with `vue-demi`'s dynamic module resolution.","error":"[plugin:vite:dep-scan] Cannot find module 'vue-demi' or [Vue warn]: Failed to resolve component: ..."},{"fix":"Ensure `@vue/composition-api` is correctly specified as a peer dependency and consider explicitly calling `install()` from `vue-demi` in your library's entry point.","cause":"The `@vue/composition-api` plugin was not correctly installed in a Vue 2 environment.","error":"TypeError: Vue.use is not a function (in Vue 2) or [Vue warn]: Failed to resolve plugin: CompositionApi"},{"fix":"For universal code, use reactive assignments or methods like `ref()` and `reactive()`. If Vue 2-specific global API access is needed, use `if (Vue2) { Vue2.set(...) }`.","cause":"Attempting to use Vue 2-specific global reactivity methods directly in a Vue 3 environment.","error":"TypeError: Vue.set is not a function (or Vue.delete is not a function)"},{"fix":"Update to a browser version that supports `globalThis` (e.g., Chrome 52+, Firefox 55+, Edge 15+, Safari 10.1+). Ensure `vue-demi` is updated to at least `0.14.9` which includes compatibility fixes.","cause":"Running `vue-demi` in an extremely old browser environment lacking `globalThis` support.","error":"ReferenceError: globalThis is not defined"}],"ecosystem":"npm"}