0
# Vue Composition API
1

2
Vue Composition API provides Vue 3's modern composition-based component logic to Vue 2 applications. It enables reactive state management, lifecycle hooks, computed properties, watchers, and dependency injection using a function-based API instead of the traditional options-based approach. This compatibility layer allows developers to adopt Vue 3 patterns while maintaining Vue 2 compatibility.
3

4
## Package Information
5

6
- **Package Name**: @vue/composition-api
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install @vue/composition-api`
10

11
## Core Imports
12

13
```typescript
14
import VueCompositionAPI from "@vue/composition-api";
15
import { ref, reactive, computed, watch, onMounted } from "@vue/composition-api";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const VueCompositionAPI = require("@vue/composition-api");
22
const { ref, reactive, computed, watch, onMounted } = require("@vue/composition-api");
23
```
24

25
## Basic Usage
26

27
```typescript
28
import Vue from "vue";
29
import VueCompositionAPI, { ref, reactive, computed, watch, onMounted } from "@vue/composition-api";
30

31
// Install the plugin
32
Vue.use(VueCompositionAPI);
33

34
// Use in component
35
export default {
36
  setup() {
37
    // Reactive state
38
    const count = ref(0);
39
    const user = reactive({ name: "Alice", age: 25 });
40

41
    // Computed property
42
    const doubleCount = computed(() => count.value * 2);
43

44
    // Watcher
45
    watch(count, (newValue, oldValue) => {
46
      console.log(`Count changed from ${oldValue} to ${newValue}`);
47
    });
48

49
    // Lifecycle hook
50
    onMounted(() => {
51
      console.log("Component mounted");
52
    });
53

54
    // Methods
55
    const increment = () => {
56
      count.value++;
57
    };
58

59
    return {
60
      count,
61
      user,
62
      doubleCount,
63
      increment,
64
    };
65
  },
66
};
67
```
68

69
## Architecture
70

71
Vue Composition API is structured around several key systems:
72

73
- **Installation Plugin**: Vue.use() plugin that patches Vue 2 with composition API support
74
- **Reactivity System**: Reactive proxies, refs, and computed values with dependency tracking
75
- **Lifecycle Hooks**: Function-based alternatives to component lifecycle options
76
- **Watch System**: Advanced watching capabilities for reactive data sources
77
- **Dependency Injection**: Provide/inject pattern for component communication
78
- **Effect Scopes**: Advanced effect management and cleanup organization
79

80
## Capabilities
81

82
### Plugin Installation
83

84
Main Vue plugin that enables Composition API support in Vue 2 applications.
85

86
```typescript { .api }
87
interface VueCompositionAPIPlugin {
88
  install(Vue: VueConstructor): void;
89
}
90

91
declare const Plugin: VueCompositionAPIPlugin;
92
export default Plugin;
93

94
function install(Vue: VueConstructor): void;
95
```
96

97
### Reactive State Management
98

99
Core reactivity system providing reactive objects, refs, and readonly proxies with automatic dependency tracking.
100

101
```typescript { .api }
102
function reactive<T extends object>(obj: T): UnwrapRef<T>;
103
function ref<T>(value: T): Ref<UnwrapRef<T>>;
104
function readonly<T extends object>(obj: T): DeepReadonly<UnwrapNestedRefs<T>>;
105

106
interface Ref<T = any> {
107
  value: T;
108
}
109
```
110

111
[Reactive State](./reactive-state.md)
112

113
### Computed Properties
114

115
Derived reactive state that automatically updates when dependencies change, with support for both read-only and writable computed properties.
116

117
```typescript { .api }
118
function computed<T>(getter: () => T): ComputedRef<T>;
119
function computed<T>(options: WritableComputedOptions<T>): WritableComputedRef<T>;
120

121
interface ComputedRef<T = any> extends WritableComputedRef<T> {
122
  readonly value: T;
123
}
124

125
interface WritableComputedOptions<T> {
126
  get: () => T;
127
  set: (value: T) => void;
128
}
129
```
130

131
[Computed Properties](./computed.md)
132

133
### Watchers and Effects
134

135
Advanced watching system for tracking reactive data changes with configurable timing and cleanup.
136

137
```typescript { .api }
138
function watch<T>(
139
  source: WatchSource<T>,
140
  callback: WatchCallback<T>,
141
  options?: WatchOptions
142
): WatchStopHandle;
143

144
function watchEffect(effect: WatchEffect): WatchStopHandle;
145

146
type WatchSource<T> = Ref<T> | ComputedRef<T> | (() => T);
147
type WatchCallback<T> = (value: T, oldValue: T) => void;
148
type WatchStopHandle = () => void;
149
```
150

151
[Watchers and Effects](./watchers.md)
152

153
### Lifecycle Hooks
154

155
Function-based lifecycle hooks that integrate with Vue 2's component lifecycle system.
156

157
```typescript { .api }
158
function onBeforeMount(hook: () => void, target?: ComponentInternalInstance): Function | undefined;
159
function onMounted(hook: () => void, target?: ComponentInternalInstance): Function | undefined;
160
function onBeforeUpdate(hook: () => void, target?: ComponentInternalInstance): Function | undefined;
161
function onUpdated(hook: () => void, target?: ComponentInternalInstance): Function | undefined;
162
function onBeforeUnmount(hook: () => void, target?: ComponentInternalInstance): Function | undefined;
163
function onUnmounted(hook: () => void, target?: ComponentInternalInstance): Function | undefined;
164
function onErrorCaptured(hook: (error: Error, instance: ComponentInstance, info: string) => boolean | void, target?: ComponentInternalInstance): Function | undefined;
165
function onActivated(hook: () => void, target?: ComponentInternalInstance): Function | undefined;
166
function onDeactivated(hook: () => void, target?: ComponentInternalInstance): Function | undefined;
167
function onServerPrefetch(hook: () => Promise<any> | void, target?: ComponentInternalInstance): Function | undefined;
168
```
169

170
[Lifecycle Hooks](./lifecycle.md)
171

172
### Dependency Injection
173

174
Provide/inject system for passing data down the component tree without explicit prop drilling.
175

176
```typescript { .api }
177
function provide<T>(key: InjectionKey<T> | string, value: T): void;
178
function inject<T>(key: InjectionKey<T> | string): T | undefined;
179
function inject<T>(key: InjectionKey<T> | string, defaultValue: T): T;
180

181
interface InjectionKey<T> extends Symbol {}
182
```
183

184
[Dependency Injection](./dependency-injection.md)
185

186
### Component Utilities
187

188
Utilities for component definition, setup context access, and Vue 3 compatibility features.
189

190
```typescript { .api }
191
function defineComponent<Props, RawBindings = object>(
192
  setup: SetupFunction<Props, RawBindings>
193
): ComponentOptions<Vue>;
194

195
function getCurrentInstance(): ComponentInternalInstance | null;
196
function nextTick(callback?: () => void): Promise<void>;
197

198
interface SetupContext {
199
  attrs: Record<string, any>;
200
  slots: Slots;
201
  emit: (event: string, ...args: any[]) => void;
202
}
203
```
204

205
[Component Utilities](./component-utilities.md)
206

207
### Advanced Features
208

209
Effect scopes, CSS modules, app instances, and other advanced composition features.
210

211
```typescript { .api }
212
function effectScope(detached?: boolean): EffectScope;
213
function getCurrentScope(): EffectScope | undefined;
214
function createApp(rootComponent: any, rootProps?: any): App;
215
function useCssModule(name?: string): Record<string, string>;
216
```
217

218
[Advanced Features](./advanced-features.md)
219

220
### Utilities
221

222
Development and debugging utilities for Vue composition functions.
223

224
```typescript { .api }
225
function warn(message: string): void;
226
function nextTick(callback?: () => void): Promise<void>;
227
```
228

229
### Types and Interfaces
230

231
Core type definitions used throughout the composition API.
232

233
```typescript { .api }
234
type UnwrapRef<T> = T extends Ref<infer V>
235
  ? UnwrapRefSimple<V>
236
  : UnwrapRefSimple<T>;
237

238
type ToRefs<T = any> = { [K in keyof T]: Ref<T[K]> };
239

240
interface ComponentInternalInstance {
241
  proxy: ComponentInstance | null;
242
  setupState: Record<string, any>;
243
}
244

245
type SetupFunction<Props, RawBindings> = (
246
  props: Readonly<Props>,
247
  ctx: SetupContext
248
) => RawBindings | (() => VNode | null) | void;
249
```
250

251
[Types and Interfaces](./types.md)