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
```