Vue Demi

Vue Demi lets library authors write a single codebase that works whether the consuming app runs Vue 2 (with @vue/composition-api), Vue 2.7 (which has Composition API built in), or Vue 3. Instead of maintaining separate builds or branching logic per Vue major version, a library imports Composition API primitives (ref, reactive, defineComponent, etc.) from vue-demi, which resolves at install time to whichever Vue version the consumer actually has installed.

It became a foundational dependency across the Vue ecosystem — VueUse, vue-apollo-composable, vuelidate, and dozens of other libraries depend on it — precisely because it let package maintainers support both major Vue versions from one source tree during the multi-year Vue 2-to-3 migration window. The maintainers now flag it as no longer recommended for new projects, since Vue 2 has reached end-of-life and most libraries can target Vue 3 exclusively.

What You Get

• A drop-in replacement import (import { ref, reactive } from 'vue-demi') that redirects to the correct Vue 2/2.7/3 implementation at install time
• isVue2 / isVue3 boolean exports for writing version-specific branches when needed
• A Vue2 export for accessing Vue 2’s global API surface without importing all of Vue 2 directly
• An install() helper that safely installs the Composition API plugin on Vue 2 (a no-op under Vue 3)
• CLI tools (vue-demi-switch, vue-demi-fix) for manually switching or repairing which Vue version a project resolves against
• A postinstall hook that automatically detects the consumer’s installed Vue version and wires up the correct redirect

Common Use Cases

• Publishing a Vue component or composable library that needs to support both Vue 2 and Vue 3 consumers from one codebase
• Testing a library against both Vue 2 and Vue 3 in CI by aliasing the peer dependency and re-running the same test suite
• Maintaining legacy Vue 2 projects that still depend on libraries built against vue-demi’s dual-version redirect
• Diagnosing and fixing Vue version-resolution issues in a monorepo via the vue-demi-fix CLI when bundlers like Vite pre-bundle it incorrectly

Under The Hood

Architecture - Vue Demi ships three parallel implementations under lib/v2, lib/v2.7, and lib/v3, each re-exporting the Composition API surface appropriate to that Vue version; a postinstall script (scripts/postinstall.js) inspects the consumer’s installed vue version and copies or symlinks the matching implementation into the package’s main entry point, so import ... from 'vue-demi' always resolves to version-correct code without any runtime branching cost. This install-time redirection (rather than runtime feature detection) is the core design decision that makes the shim nearly free at runtime.

Tech Stack - Implemented in plain JavaScript with pre-built CJS (lib/index.cjs), ESM (lib/index.mjs), and IIFE (for CDN use via jsdelivr/unpkg) outputs, plus TypeScript declarations (lib/index.d.ts). The scripts/ directory contains the postinstall detection logic and a small CLI (bin/vue-demi-switch.js, bin/vue-demi-fix.js) built on plain Node.js fs operations rather than a larger CLI framework, keeping the whole package dependency-light apart from its Vue peer dependencies.

Code Quality - The codebase is intentionally small and the redirect mechanism is documented in depth in the README and a companion blog post by the author, which is important given how much of the Vue ecosystem depends on this package working correctly. There is no visible automated test suite in the repository; correctness is instead validated indirectly through the large number of downstream libraries (VueUse, vuelidate, and others) that exercise it in their own CI. Development has slowed significantly since Vue 2’s end-of-life, consistent with the maintainers’ own guidance that it’s no longer the recommended approach for new libraries.

API Design - The API design goal was zero-friction adoption: a library author changes their imports from vue to vue-demi and adds vue-demi plus peer dependencies, with no other code changes required for basic Composition API usage. The isVue2/isVue3/Vue2 escape hatches exist for the minority of cases where version-specific behavior is unavoidable, keeping the common path trivial while still allowing edge cases to be handled explicitly.