0
# Compatibility Configuration
1

2
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.
3

4
## Capabilities
5

6
### configureCompat Function
7

8
Configure global compatibility options for the entire application.
9

10
```javascript { .api }
11
/**
12
 * Configure global compatibility options
13
 * @param config - Compatibility configuration object
14
 */
15
function configureCompat(config: CompatConfig): void;
16

17
type CompatConfig = Partial<Record<DeprecationTypes, boolean | 'suppress-warning'>> & {
18
  MODE?: 2 | 3 | ((comp: Component | null) => 2 | 3);
19
};
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
import { configureCompat } from "@vue/compat";
26

27
// Default to Vue 2 mode, disable specific warnings
28
configureCompat({
29
  MODE: 2,
30
  GLOBAL_MOUNT: false,
31
  INSTANCE_EVENT_EMITTER: false
32
});
33

34
// Default to Vue 3 mode, enable only specific Vue 2 features
35
configureCompat({
36
  MODE: 3,
37
  GLOBAL_EXTEND: true,
38
  INSTANCE_LISTENERS: true
39
});
40

41
// Dynamic mode per component
42
configureCompat({
43
  MODE: (comp) => {
44
    // Use Vue 2 mode for legacy components
45
    return comp && comp.name.startsWith('Legacy') ? 2 : 3;
46
  }
47
});
48

49
// Suppress warnings without disabling features
50
configureCompat({
51
  GLOBAL_PROTOTYPE: 'suppress-warning',
52
  CONFIG_IGNORED_ELEMENTS: 'suppress-warning'
53
});
54
```
55

56
### Compatibility Modes
57

58
#### MODE Configuration
59

60
Controls the default behavior mode for the application.
61

62
```javascript { .api }
63
/**
64
 * Compatibility mode configuration
65
 * - 2: Vue 2 mode (default) - Most APIs behave like Vue 2
66
 * - 3: Vue 3 mode - All APIs behave like Vue 3 unless explicitly enabled
67
 * - Function: Dynamic mode based on component
68
 */
69
MODE?: 2 | 3 | ((comp: Component | null) => 2 | 3);
70
```
71

72
### Feature Flag Values
73

74
Each compatibility feature can be configured with specific values:
75

76
```javascript { .api }
77
/**
78
 * Feature flag values
79
 * - true: Enable the compatibility behavior
80
 * - false: Disable the compatibility behavior (Vue 3 mode)
81
 * - 'suppress-warning': Enable compatibility but suppress warnings
82
 */
83
type FeatureFlagValue = boolean | 'suppress-warning';
84
```
85

86
## Deprecation Types
87

88
Complete list of compatibility features that can be individually controlled:
89

90
### Global API Deprecations
91

92
```javascript { .api }
93
enum DeprecationTypes {
94
  /** new Vue() -> createApp() */
95
  GLOBAL_MOUNT = 'GLOBAL_MOUNT',
96
  /** Mounted application container behavior */
97
  GLOBAL_MOUNT_CONTAINER = 'GLOBAL_MOUNT_CONTAINER',
98
  /** Vue.extend -> defineComponent */
99
  GLOBAL_EXTEND = 'GLOBAL_EXTEND',
100
  /** Vue.prototype -> app.config.globalProperties */
101
  GLOBAL_PROTOTYPE = 'GLOBAL_PROTOTYPE',
102
  /** Vue.set removal */
103
  GLOBAL_SET = 'GLOBAL_SET',
104
  /** Vue.delete removal */
105
  GLOBAL_DELETE = 'GLOBAL_DELETE',
106
  /** Vue.observable -> reactive */
107
  GLOBAL_OBSERVABLE = 'GLOBAL_OBSERVABLE',
108
  /** Vue.util deprecation */
109
  GLOBAL_PRIVATE_UTIL = 'GLOBAL_PRIVATE_UTIL',
110
}
111
```
112

113
### Configuration Deprecations
114

115
```javascript { .api }
116
enum DeprecationTypes {
117
  /** config.silent removal */
118
  CONFIG_SILENT = 'CONFIG_SILENT',
119
  /** Build-time devtools flag */
120
  CONFIG_DEVTOOLS = 'CONFIG_DEVTOOLS',
121
  /** config.keyCodes removal */
122
  CONFIG_KEY_CODES = 'CONFIG_KEY_CODES',
123
  /** config.productionTip removal */
124
  CONFIG_PRODUCTION_TIP = 'CONFIG_PRODUCTION_TIP',
125
  /** config.ignoredElements -> isCustomElement */
126
  CONFIG_IGNORED_ELEMENTS = 'CONFIG_IGNORED_ELEMENTS',
127
  /** Whitespace handling changes */
128
  CONFIG_WHITESPACE = 'CONFIG_WHITESPACE',
129
  /** Option merge strategy changes */
130
  CONFIG_OPTION_MERGE_STRATS = 'CONFIG_OPTION_MERGE_STRATS',
131
}
132
```
133

134
### Instance API Deprecations
135

136
```javascript { .api }
137
enum DeprecationTypes {
138
  /** vm.$set removal */
139
  INSTANCE_SET = 'INSTANCE_SET',
140
  /** vm.$delete removal */
141
  INSTANCE_DELETE = 'INSTANCE_DELETE',
142
  /** vm.$destroy changes */
143
  INSTANCE_DESTROY = 'INSTANCE_DESTROY',
144
  /** Event system changes ($on, $off, $once) */
145
  INSTANCE_EVENT_EMITTER = 'INSTANCE_EVENT_EMITTER',
146
  /** Event hook changes */
147
  INSTANCE_EVENT_HOOKS = 'INSTANCE_EVENT_HOOKS',
148
  /** vm.$children deprecation */
149
  INSTANCE_CHILDREN = 'INSTANCE_CHILDREN',
150
  /** vm.$listeners deprecation */
151
  INSTANCE_LISTENERS = 'INSTANCE_LISTENERS',
152
  /** Scoped slots changes */
153
  INSTANCE_SCOPED_SLOTS = 'INSTANCE_SCOPED_SLOTS',
154
  /** Attribute inheritance changes */
155
  INSTANCE_ATTRS_CLASS_STYLE = 'INSTANCE_ATTRS_CLASS_STYLE',
156
}
157
```
158

159
### Component Options Deprecations
160

161
```javascript { .api }
162
enum DeprecationTypes {
163
  /** Data function changes */
164
  OPTIONS_DATA_FN = 'OPTIONS_DATA_FN',
165
  /** Data merging changes */
166
  OPTIONS_DATA_MERGE = 'OPTIONS_DATA_MERGE',
167
  /** beforeDestroy -> beforeUnmount */
168
  OPTIONS_BEFORE_DESTROY = 'OPTIONS_BEFORE_DESTROY',
169
  /** destroyed -> unmounted */
170
  OPTIONS_DESTROYED = 'OPTIONS_DESTROYED',
171
}
172
```
173

174

175
### Other Deprecations
176

177
```javascript { .api }
178
enum DeprecationTypes {
179
  /** Array watching changes */
180
  WATCH_ARRAY = 'WATCH_ARRAY',
181
  /** Props default this context */
182
  PROPS_DEFAULT_THIS = 'PROPS_DEFAULT_THIS',
183
  /** Keycode modifier deprecation */
184
  V_ON_KEYCODE_MODIFIER = 'V_ON_KEYCODE_MODIFIER',
185
  /** Custom directive changes */
186
  CUSTOM_DIR = 'CUSTOM_DIR',
187
  /** Attribute false value handling */
188
  ATTR_FALSE_VALUE = 'ATTR_FALSE_VALUE',
189
  /** Attribute coercion changes */
190
  ATTR_ENUMERATED_COERCION = 'ATTR_ENUMERATED_COERCION',
191
  /** Transition class changes */
192
  TRANSITION_CLASSES = 'TRANSITION_CLASSES',
193
  /** TransitionGroup root element */
194
  TRANSITION_GROUP_ROOT = 'TRANSITION_GROUP_ROOT',
195
  /** Async component changes */
196
  COMPONENT_ASYNC = 'COMPONENT_ASYNC',
197
  /** Functional component changes */
198
  COMPONENT_FUNCTIONAL = 'COMPONENT_FUNCTIONAL',
199
  /** v-model component changes */
200
  COMPONENT_V_MODEL = 'COMPONENT_V_MODEL',
201
  /** Render function changes */
202
  RENDER_FUNCTION = 'RENDER_FUNCTION',
203
  /** Filter deprecation */
204
  FILTERS = 'FILTERS',
205
  /** Private API access */
206
  PRIVATE_APIS = 'PRIVATE_APIS',
207
}
208
```
209

210
## Per-Component Configuration
211

212
Components can override global compatibility settings using the `compatConfig` option:
213

214
```javascript { .api }
215
interface ComponentOptions {
216
  /**
217
   * Per-component compatibility configuration
218
   * Overrides global settings for this component only
219
   */
220
  compatConfig?: CompatConfig;
221
}
222
```
223

224
**Usage Examples:**
225

226
```javascript
227
// Legacy component using Vue 2 mode
228
export default {
229
  name: 'LegacyComponent',
230
  compatConfig: {
231
    MODE: 2,
232
    INSTANCE_LISTENERS: true,
233
    INSTANCE_CHILDREN: true
234
  },
235
  data() {
236
    return { count: 0 };
237
  },
238
  mounted() {
239
    // Access legacy properties
240
    console.log(this.$listeners);
241
    console.log(this.$children);
242
  }
243
};
244

245
// Modern component using Vue 3 mode
246
export default {
247
  name: 'ModernComponent',
248
  compatConfig: {
249
    MODE: 3
250
  },
251
  setup() {
252
    // Use Vue 3 Composition API
253
    const count = ref(0);
254
    return { count };
255
  }
256
};
257

258
// Hybrid component with specific feature flags
259
export default {
260
  name: 'HybridComponent',
261
  compatConfig: {
262
    MODE: 3,
263
    INSTANCE_EVENT_EMITTER: true, // Still use $on/$off
264
    GLOBAL_MOUNT: 'suppress-warning' // Keep compatibility, no warnings
265
  }
266
};
267
```
268

269
## Legacy Config Properties
270

271
Vue 2 global configuration properties (deprecated but supported):
272

273
```javascript { .api }
274
interface LegacyConfig {
275
  /** Suppress all Vue logs and warnings */
276
  silent?: boolean;
277
  /** Enable devtools in production */
278
  devtools?: boolean;
279
  /** Ignore custom elements */
280
  ignoredElements?: (string | RegExp)[];
281
  /** Custom key codes for v-on */
282
  keyCodes?: Record<string, number | number[]>;
283
  /** Show production tip */
284
  productionTip?: boolean;
285
}
286
```
287

288
**Usage Example:**
289

290
```javascript
291
import Vue from "@vue/compat";
292

293
// Configure legacy options (deprecated)
294
Vue.config.silent = false;
295
Vue.config.devtools = true;
296
Vue.config.ignoredElements = ['custom-element'];
297
Vue.config.keyCodes = {
298
  'media-play-pause': 179
299
};
300
```
301

302
## Build Configuration
303

304
For build-time compatibility features, configure through bundler options:
305

306
```javascript
307
// Vue CLI configuration
308
module.exports = {
309
  chainWebpack: config => {
310
    config.resolve.alias.set('vue', '@vue/compat');
311
    
312
    config.module
313
      .rule('vue')
314
      .use('vue-loader')
315
      .tap(options => ({
316
        ...options,
317
        compilerOptions: {
318
          compatConfig: {
319
            MODE: 2,
320
            COMPILER_V_IF_V_FOR_PRECEDENCE: false
321
          }
322
        }
323
      }));
324
  }
325
};
326
```