vueuse / Vue Demi

Vue Demi (half in French) is a developing utility
allows you to write Universal Vue Libraries for Vue 2 & 3
See more details in this blog post

Usage

Install this as your plugin's dependency:

npm i vue-demi
# or
yarn add vue-demi

Add vue and @vue/composition-api to your plugin's peer dependencies to specify what versions you support.

{
  "dependencies": {
    "vue-demi": "latest"
  },
  "peerDependencies": {
    "@vue/composition-api": "^1.0.0-beta.1",
    "vue": "^2.0.0 || >=3.0.0-rc.0"
  },
  "peerDependenciesMeta": {
    "@vue/composition-api": {
      "optional": true
    }
  },
  "devDependencies": {
    "vue": "^3.0.0" // or "^2.6.0" base on your preferred working environment
  },
}

Import everything related to Vue from it, it will redirect to [email protected] + @vue/composition-api or [email protected] based on users' environments.

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

Publish your plugin and all is done!

Extra APIs

Vue Demi provides extra APIs to help distinguishing users' environments and to do some version-specific logics.

isVue2 isVue3

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

if (isVue2) {
  // Vue 2 only
} else {
  // Vue 3 only
}

Vue2

To avoid bringing in all the tree-shakable modules, we provide a Vue2 export to support access to Vue 2's global API. (See #41.)

import { Vue2 } from 'vue-demi'

if (Vue2) {
  Vue2.config.ignoredElements.push('x-foo')
}

install()

Composition API in Vue 2 is provided as a plugin and need to install to Vue instance before using. Normally, vue-demi will try to install it automatically. For some usages that you might need to ensure the plugin get installed correctly, the install() API is exposed to as a safe version of Vue.use(CompositionAPI). install() in Vue 3 environment will be an empty function (no-op).

import { install } from 'vue-demi'

install()

CLI

Manually Switch Versions

To explicitly switch the redirecting version, you can use these commands in your project's root.

npx vue-demi-switch 2
# or
npx vue-demi-switch 3

Package Aliasing

If you would like to import vue under an alias, you can use the following command

npx vue-demi-switch 2 vue2
# or
npx vue-demi-switch 3 vue3

Then vue-demi will redirect APIs from the alias name you specified, for example:

import * as Vue from 'vue3'

var isVue2 = false
var isVue3 = true
var Vue2 = undefined

export * from 'vue3'
export {
  Vue,
  Vue2,
  isVue2,
  isVue3,
}

Auto Fix

If the postinstall hook doesn't get triggered or you have updated the Vue version, try to run the following command to resolve the redirecting.

npx vue-demi-fix

Isomorphic Testings

You can support testing for both versions by adding npm alias in your dev dependencies. For example:

{
  "scripts": {
    "test:2": "vue-demi-switch 2 vue2 && jest",
    "test:3": "vue-demi-switch 3 && jest",
  },
  "devDependencies": {
    "vue": "^3.0.0",
    "vue2": "npm:[email protected]"
  },
}

or

{
  "scripts": {
    "test:2": "vue-demi-switch 2 && jest",
    "test:3": "vue-demi-switch 3 vue3 && jest",
  },
  "devDependencies": {
    "vue": "^2.6.0",
    "vue3": "npm:[email protected]"
  },
}

Examples

See examples.

Who are using this?

• VueUse - Collection of Composition API utils
• @vue/apollo-composable - Apollo GraphQL functions for Vue Composition API
• vuelidate - Simple, lightweight model-based validation
• vue-composition-test-utils - Simple vue composition api unit test utilities
• vue-use-stripe - Stripe Elements wrapper for Vue.js
• @opd/g2plot-vue - G2plot for vue
• vue-echarts - Vue.js component for Apache ECharts.

open a PR to add your library ;)

Underhood

See the blog post.

License

MIT License © 2020 Anthony Fu