@vue/composition-api

What is @vue/composition-api?

@vue/composition-api is a plugin that provides Vue 2.x users with the Composition API, which is a set of APIs that allows you to use Vue 3's reactivity system and component logic composition in Vue 2.x applications.

What are @vue/composition-api's main functionalities?

Reactive State

The `reactive` function is used to create a reactive state object. This allows you to manage state in a reactive manner, similar to Vue 3.

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

export default {
  setup() {
    const state = reactive({ count: 0 });
    return { state };
  }
};
```

Computed Properties

The `computed` function is used to create computed properties that automatically update when their dependencies change.

```javascript
import { computed } from '@vue/composition-api';

export default {
  setup() {
    const state = reactive({ count: 0 });
    const doubleCount = computed(() => state.count * 2);
    return { state, doubleCount };
  }
};
```

Watchers

The `watch` function is used to perform side effects in response to reactive state changes.

```javascript
import { watch } from '@vue/composition-api';

export default {
  setup() {
    const state = reactive({ count: 0 });
    watch(() => state.count, (newValue, oldValue) => {
      console.log(`Count changed from ${oldValue} to ${newValue}`);
    });
    return { state };
  }
};
```

Lifecycle Hooks

The `onMounted` and `onUnmounted` functions are used to register lifecycle hooks within the setup function.

```javascript
import { onMounted, onUnmounted } from '@vue/composition-api';

export default {
  setup() {
    onMounted(() => {
      console.log('Component is mounted');
    });
    onUnmounted(() => {
      console.log('Component is unmounted');
    });
  }
};
```

Other packages similar to @vue/composition-api

vue-function-api

The `vue-function-api` package provides a similar Composition API for Vue 2.x. It allows you to use Vue 3's Composition API features in Vue 2.x applications. However, `@vue/composition-api` is the official plugin provided by the Vue team, making it more reliable and better supported.

vue-hooks

The `vue-hooks` package offers a way to use hooks in Vue components, similar to React hooks. While it provides some similar functionality to the Composition API, it is not as comprehensive or integrated as `@vue/composition-api`.

README

Vue Composition API

Vue 2 plugin for Composition API in Vue 3.

English | 中文文档 / Composition API RFC

Note: the primary goal of this package is to allow the community to experiment with the API and provide feedback before it's finalized. The implementation may contain minor inconsistencies with the RFC as the latter gets updated. We do not recommend using this package for production yet at this stage.

---

Navigation

• Installation
• Usage
• TypeScript
  • TSX
• Limitations
• Changelog

Installation

npm

npm install @vue/composition-api

yarn

yarn add @vue/composition-api

CDN

<script src="https://unpkg.com/@vue/composition-api/dist/vue-composition-api.umd.js"></script>

By using the global variable window.vueCompositionApi

Usage

You must install @vue/composition-api via Vue.use() before using other APIs:

import Vue from 'vue';
import VueCompositionApi from '@vue/composition-api';

Vue.use(VueCompositionApi);

After installing the plugin you can use the Composition API to compose your component.

TypeScript

This plugin requires TypeScript version >3.5.1. If you are using vetur, make sure to set vetur.useWorkspaceDependencies to true.

To let TypeScript properly infer types inside Vue component options, you need to define components with defineComponent:

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

const Component = defineComponent({
  // type inference enabled
});

const Component = {
  // this will NOT have type inference,
  // because TypeScript can't tell this is options for a Vue component.
};

TSX

:rocket: An Example Repository with TS and TSX support is provided to help you start.

To support TSX, create a declaration file with following content in your project.

// file: shim-tsx.d.ts
import Vue, { VNode } from 'vue';
import { ComponentRenderProxy } from '@vue/composition-api';

declare global {
  namespace JSX {
    // tslint:disable no-empty-interface
    interface Element extends VNode {}
    // tslint:disable no-empty-interface
    interface ElementClass extends ComponentRenderProxy {}
    interface ElementAttributesProperty {
      $props: any; // specify the property name to use
    }
    interface IntrinsicElements {
      [elem: string]: any;
    }
  }
}

Limitations

Ref Unwrap

Unwrap is not working with Array index.

Should not store ref as a direct child of Array:

const state = reactive({
  list: [ref(0)],
});
// no unwrap, `.value` is required
state.list[0].value === 0; // true

state.list.push(ref(1));
// no unwrap, `.value` is required
state.list[1].value === 1; // true

Should not use ref in a plain object when working with Array:

const a = {
  count: ref(0),
};
const b = reactive({
  list: [a], // `a.count` will not unwrap!!
});

// no unwrap for `count`, `.value` is required
b.list[0].count.value === 0; // true

const b = reactive({
  list: [
    {
      count: ref(0), // no unwrap!!
    },
  ],
});

// no unwrap for `count`, `.value` is required
b.list[0].count.value === 0; // true

Should always use ref in a reactive when working with Array:

const a = reactive({
  count: ref(0),
});
const b = reactive({
  list: [a],
});
// unwrapped
b.list[0].count === 0; // true

b.list.push(
  reactive({
    count: ref(1),
  })
);
// unwrapped
b.list[1].count === 1; // true

Using reactive will mutate the origin object

This is an limitation of using Vue.observable in Vue 2.

Vue 3 will return an new proxy object.

---

watch() API

onTrack and onTrigger are not available in WatchOptions.

---

Template Refs

:white_check_mark: Support     :x: Not Supported

:white_check_mark: String ref && return it from setup():

<template>
  <div ref="root"></div>
</template>

<script>
  export default {
    setup() {
      const root = ref(null);

      onMounted(() => {
        // the DOM element will be assigned to the ref after initial render
        console.log(root.value); // <div/>
      });

      return {
        root,
      };
    },
  };
</script>

:white_check_mark: String ref && return it from setup() && Render Function / JSX:

export default {
  setup() {
    const root = ref(null);

    onMounted(() => {
      // the DOM element will be assigned to the ref after initial render
      console.log(root.value); // <div/>
    });

    return {
      root,
    };
  },
  render() {
    // with JSX
    return () => <div ref="root" />;
  },
};

:x: Function ref:

<template>
  <div :ref="el => root = el"></div>
</template>

<script>
  export default {
    setup() {
      const root = ref(null);

      return {
        root,
      };
    },
  };
</script>

:x: Render Function / JSX in setup():

export default {
  setup() {
    const root = ref(null);

    return () =>
      h('div', {
        ref: root,
      });

    // with JSX
    return () => <div ref={root} />;
  },
};

If you really want to use template refs in this case, you can access vm.$refs via SetupContext.refs.

:warning: Warning: The SetupContext.refs won't exist in Vue 3.0. @vue/composition-api provide it as a workaround here.

export default {
  setup(initProps, setupContext) {
    const refs = setupContext.refs;
    onMounted(() => {
      // the DOM element will be assigned to the ref after initial render
      console.log(refs.root); // <div/>
    });

    return () =>
      h('div', {
        ref: 'root',
      });

    // with JSX
    return () => <div ref="root" />;
  },
};

You may also need to augment the SetupContext when working with TypeScript:

import Vue from 'vue';
import VueCompositionApi from '@vue/composition-api';

Vue.use(VueCompositionApi);

declare module '@vue/composition-api/dist/component/component' {
  interface SetupContext {
    readonly refs: { [key: string]: Vue | Element | Vue[] | Element[] };
  }
}

SSR

Even if there is no definitive Vue 3 API for SSR yet, this plugin implements the onServerPrefetch lifecycle hook that allows you to use the serverPrefetch hook found in the classic API.

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

export default {
  setup (props, { ssrContext }) {
    const result = ref();

    onServerPrefetch(async () => {
      result.value = await callApi(ssrContext.someId);
    });

    return {
      result,
    };
  },
};

Changelog

0.6.3 (2020-06-12)

Bug Fixes

• unwrapRefProxy native objects handling (#376) (8322fc7), closes #375

<a name="0.6.2"></a>