Vue Demi: Universal Vue Library Helper

Common errors

• [plugin:vite:dep-scan] Cannot find module 'vue-demi' or [Vue warn]: Failed to resolve component: ...

  cause Vite's dependency pre-bundling interferes with `vue-demi`'s dynamic module resolution.
  fix Add `exclude: ['vue-demi']` to the `optimizeDeps` option in your `vite.config.js`.

• TypeError: Vue.use is not a function (in Vue 2) or [Vue warn]: Failed to resolve plugin: CompositionApi

  cause The `@vue/composition-api` plugin was not correctly installed in a Vue 2 environment.
  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.

• TypeError: Vue.set is not a function (or Vue.delete is not a function)

  cause Attempting to use Vue 2-specific global reactivity methods directly in a Vue 3 environment.
  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(...) }`.

• ReferenceError: globalThis is not defined

  cause Running `vue-demi` in an extremely old browser environment lacking `globalThis` support.
  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.

Warnings

• breaking 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.
  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 }`).
• gotcha 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.
  Fix: Add `exclude: ['vue-demi']` to the `optimizeDeps` configuration in your `vite.config.js` or `vite.config.ts`.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha Older browser environments (pre-Chrome 52 / Firefox 55) may not support `globalThis`, leading to `ReferenceError: globalThis is not defined`.
  Fix: Ensure you are using `vue-demi` version `0.14.9` or newer, as recent updates include fixes for broader compatibility regarding `globalThis`.

Install

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

Imports

• ref, reactive, defineComponent
  wrong:

  import { ref } from 'vue'; import { reactive } from '@vue/composition-api'

  correct:

  import { ref, reactive, defineComponent } from 'vue-demi'

  This is the primary way to import core Composition API utilities universally across Vue 2 and Vue 3.
• isVue2, isVue3, version
  wrong:

  if (Vue.version.startsWith('2'))

  correct:

  import { isVue2, isVue3, version } from 'vue-demi'

  Provides reliable runtime environment detection for conditional logic within universal libraries. `version` maps to `Vue.version`.
• Vue2

  import { Vue2 } from 'vue-demi'

  `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)`.
• install

  import { install } from 'vue-demi'

  Explicitly installs the Composition API plugin for Vue 2.x, which `vue-demi` often handles automatically. It is a no-op in Vue 3.

Quickstart

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.

import { ref, computed, isVue2, isVue3, version as vueVersion, getCurrentInstance } from 'vue-demi';

/**
 * A universal composable that provides a reactive counter.
 * Works across Vue 2 (with Composition API) and Vue 3.
 */
export function useUniversalCounter(initialValue: number = 0) {
  const count = ref(initialValue);
  const double = computed(() => count.value * 2);

  const increment = () => {
    count.value++;
  };

  // Demonstrate version-specific logic
  if (isVue2) {
    console.log(`[Vue Demi] Running in Vue 2 (version: ${vueVersion}).`);
    // Example of accessing Vue 2 instance if needed (caution: not always universal)
    const vm = getCurrentInstance()?.proxy;
    if (vm) {
      console.log('Vue 2 VM detected:', vm.$options.name);
    }
  } else if (isVue3) {
    console.log(`[Vue Demi] Running in Vue 3 (version: ${vueVersion}).`);
    // Example of accessing Vue 3 instance (different structure)
    const instance = getCurrentInstance();
    if (instance) {
      console.log('Vue 3 instance detected:', instance.type.name);
    }
  }

  return {
    count,
    double,
    increment,
    isVue2,
    isVue3,
    vueVersion
  };
}

// To test in a Vue 3 environment:
// npm install vue@3 vue-demi
// npx vue-demi-switch 3
// Then integrate `useUniversalCounter` into a Vue 3 component.

// To test in a Vue 2 environment (requires Composition API plugin):
// npm install vue@2 @vue/composition-api vue-demi
// npx vue-demi-switch 2
// Make sure @vue/composition-api is installed for Vue 2.6.x.
// Then integrate `useUniversalCounter` into a Vue 2 component.