0
# Vue Compat
1

2
Vue Compat (@vue/compat) is a build of Vue 3 that provides configurable Vue 2 compatible behavior. It runs in Vue 2 mode by default with runtime warnings for deprecated features, enabling gradual migration from Vue 2 to Vue 3 while maintaining production stability during the transition process.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
import Vue from "@vue/compat";
15
```
16

17
For compatibility configuration:
18

19
```javascript
20
import Vue, { configureCompat } from "@vue/compat";
21
```
22

23
Runtime-only build (no template compiler):
24

25
```javascript
26
import Vue from "@vue/compat/dist/vue.runtime.esm-bundler.js";
27
```
28

29
For migration utilities:
30

31
```javascript
32
import { compatUtils, DeprecationTypes } from "vue";
33
```
34

35
CommonJS:
36

37
```javascript
38
const Vue = require("@vue/compat");
39
```
40

41
## Basic Usage
42

43
```javascript
44
import Vue, { configureCompat } from "@vue/compat";
45

46
// Configure compatibility features globally
47
configureCompat({
48
  MODE: 2, // Vue 2 mode by default
49
  GLOBAL_MOUNT: false, // Disable specific warnings
50
});
51

52
// Create Vue 2-style instance
53
const app = new Vue({
54
  data() {
55
    return {
56
      message: "Hello from Vue Compat!",
57
    };
58
  },
59
  template: "<div>{{ message }}</div>",
60
});
61

62
// Mount to DOM
63
app.$mount("#app");
64
```
65

66
## Architecture
67

68
Vue Compat is built around several key components:
69

70
- **CompatVue Constructor**: Vue 2-style constructor with instance-based API
71
- **Configuration System**: Fine-grained control over compatibility features through feature flags
72
- **Migration Warnings**: Runtime warnings for deprecated Vue 2 patterns that need updating
73
- **Compatibility Utilities**: Helper functions for checking and managing compatibility modes
74
- **Legacy API Support**: Full support for Vue 2 APIs including global methods, instance methods, and lifecycle hooks
75

76
## Capabilities
77

78
### Vue 2-Style Constructor and Instance API
79

80
Complete Vue 2 constructor interface with instance methods, lifecycle hooks, and component options. Supports both legacy patterns and modern Vue 3 features.
81

82
```javascript { .api }
83
declare const Vue: CompatVue;
84

85
interface CompatVue {
86
  new (options?: ComponentOptions): LegacyPublicInstance;
87
  version: string;
88
  config: AppConfig & LegacyConfig;
89
  nextTick: typeof nextTick;
90
  compile(template: string): RenderFunction;
91
  configureCompat(config: CompatConfig): void;
92
}
93
```
94

95
[Constructor and Instance API](./constructor-api.md)
96

97
### Global API Methods
98

99
Vue 2 global API methods including plugin system, component registration, directive registration, and deprecated utilities like Vue.extend, Vue.set, and Vue.delete.
100

101
```javascript { .api }
102
interface CompatVue {
103
  use<Options extends unknown[]>(plugin: Plugin<Options>, ...options: Options): CompatVue;
104
  use<Options>(plugin: Plugin<Options>, options: Options): CompatVue;
105
  mixin(mixin: ComponentOptions): CompatVue;
106
  component(name: string): Component | undefined;
107
  component(name: string, component: Component): CompatVue;
108
  directive<T, V>(name: string): Directive<T, V> | undefined;
109
  directive<T, V>(name: string, directive: Directive<T, V>): CompatVue;
110
  extend(options?: ComponentOptions): CompatVue;
111
  set(target: any, key: PropertyKey, value: any): void;
112
  delete(target: any, key: PropertyKey): void;
113
  observable: typeof reactive;
114
  filter(name: string, arg?: any): null;
115
  
116
  // Internal properties
117
  cid: number;
118
  options: ComponentOptions;
119
  util: any;
120
  super: CompatVue;
121
}
122
```
123

124
[Global API Methods](./global-api.md)
125

126
### Compatibility Configuration
127

128
Fine-grained compatibility feature management with global and per-component configuration options. Control exactly which Vue 2 behaviors to maintain and which to migrate to Vue 3.
129

130
```javascript { .api }
131
function configureCompat(config: CompatConfig): void;
132

133
type CompatConfig = Partial<Record<DeprecationTypes, boolean | 'suppress-warning'>> & {
134
  MODE?: 2 | 3 | ((comp: Component | null) => 2 | 3);
135
};
136
```
137

138
[Compatibility Configuration](./configuration.md)
139

140
### Migration Utilities
141

142
Helper functions and utilities for managing migration process, checking compatibility modes, and integrating with Vue 3 features during the transition.
143

144
```javascript { .api }
145
declare const compatUtils: {
146
  warnDeprecation: (key: DeprecationTypes, instance, ...args) => void;
147
  isCompatEnabled: (key: DeprecationTypes, instance, enableForBuiltIn?) => boolean;
148
  checkCompatEnabled: (key: DeprecationTypes, instance) => boolean;
149
  softAssertCompatEnabled: (key: DeprecationTypes, instance) => boolean;
150
  createCompatVue: (createApp, wrappedCreateApp) => CompatVue;
151
};
152
```
153

154
[Migration Utilities](./migration-helpers.md)
155

156
## Types
157

158
### ComponentOptions
159

160
```typescript { .api }
161
interface ComponentOptions {
162
  data?: () => Record<string, any>;
163
  props?: string[] | Record<string, any>;
164
  computed?: Record<string, any>;
165
  methods?: Record<string, Function>;
166
  watch?: Record<string, any>;
167
  created?(): void;
168
  mounted?(): void;
169
  updated?(): void;
170
  destroyed?(): void;
171
  beforeDestroy?(): void;
172
  template?: string;
173
  render?: Function;
174
  compatConfig?: CompatConfig;
175
}
176
```
177

178
### Plugin
179

180
```typescript { .api }
181
interface Plugin<Options = any> {
182
  install(app: CompatVue, ...options: Options[]): void;
183
}
184
```
185

186
### LegacyConfig
187

188
```typescript { .api }
189
interface LegacyConfig {
190
  silent?: boolean;
191
  devtools?: boolean;
192
  ignoredElements?: (string | RegExp)[];
193
  keyCodes?: Record<string, number | number[]>;
194
  productionTip?: boolean;
195
}
196
```