In Vue's migration build, how do configureCompat() and a component's compatConfig option interact, and what do MODE 2, MODE 3 and 'suppress-warning' change?

## Two levels of configuration The migration build (`@vue/compat`) decides, for each **deprecation ID** such as `WATCH_ARRAY`, `RENDER_FUNCTION` or `COMPONENT_V_MODEL`, whether to keep the Vue 2 behaviour. That decision reads two configuration objects: - **global** — changed with `configureCompat({ ... })`, which you import from `vue` because the bundler aliases `vue` to `@vue/compat`; - **per component** — a `compatConfig` option on the component definition, with the same shape. Resolution happens **one key at a time**: if the component's `compatConfig` contains the key, its value is used; otherwise the global value is. A component that sets only `MODE` therefore still inherits any feature keys set globally. ## MODE sets the default `MODE` is itself a key, resolved the same way, and it defines what an unmentioned feature means. The global default is `MODE: 2`. | feature value | under `MODE: 2` | under `MODE: 3` | |---|---|---| | not set | Vue 2 behaviour, warns | Vue 3 behaviour | | `true` | Vue 2 behaviour, warns | Vue 2 behaviour, warns | | `'suppress-warning'` | Vue 2 behaviour, silent | Vue 2 behaviour, silent | | `false` | Vue 3 behaviour | Vue 3 behaviour | Two consequences: - `'suppress-warning'` is the tool for **accepted debt** — a feature you will not fix yet and do not want flooding the console; - `MODE` also accepts a **function** that receives the component definition and returns `2` or `3`, so a rule can decide per component without editing every file. ## Migrating component by component Some features cannot be satisfied for both versions at once: the render function API and the component `v-model` contract have mutually exclusive Vue 2 and Vue 3 behaviour. The per-component config lets one component move ahead: ```js export default { compatConfig: { MODE: 3 }, // this component now behaves as Vue 3 props: ['modelValue'], emits: ['update:modelValue'] } ``` or, more narrowly, `compatConfig: { COMPONENT_V_MODEL: false }` to switch only the `v-model` contract. The `COMPONENT_V_MODEL` warning itself suggests exactly this opt-in when it sees a component declaring a `modelValue` prop. The end game flips the global switch: `configureCompat({ MODE: 3, FEATURE_A: true })` makes Vue 3 the default and keeps only named leftovers on Vue 2 behaviour, until they are gone and the alias can be removed. ## What happens when you switch a feature off too early Switching a feature to `false` while code still depends on it fails in one of three ways, depending on how the build checks that feature: 1. **Soft-asserted features** — old usage still runs, but in development Vue logs the deprecation followed by a console error: `^ The above deprecation's compat behavior is disabled and will likely lead to runtime errors.` 2. **Hard-asserted features** — APIs removed entirely in Vue 3; the compat shim throws `<ID> compat has been disabled.` when the old API is called. 3. **Mutually exclusive features** such as `RENDER_FUNCTION` — these warn only while compat is **on**. Once off, Vue 3 semantics simply apply and nothing is logged, so an unconverted render function fails without any hint pointing at the setting. So a feature is switched off after its warnings are gone, not before — and for the third kind, after the code has been converted, because the warnings disappear the moment you flip it. ## Rules that trip people up - **`COMPILER_*` keys belong to the template compiler.** With a build setup, SFC templates are compiled at build time, so these keys go in the bundler's `compilerOptions.compatConfig`. Setting one through `configureCompat()` in a runtime-only build triggers a warning telling you to move it. - **The compiler's MODE defaults to 3**, separately from the runtime's default of 2 — the reason build configs pass `MODE: 2` explicitly. - **`OPTIONS_DATA_MERGE` is global-only**; setting it in a component's `compatConfig` produces a warning. - **Unknown keys** produce an `Invalid deprecation config` warning, which catches typos in feature IDs. - **Built-in components** such as `<Transition>` skip most compat checks for themselves; compat is aimed at your code and your dependencies. ## A worked rollout A typical sequence using only these two levers: 1. **Start** with the global default `MODE: 2` and no feature keys, and collect the warning IDs from dev and test runs. 2. **Silence deliberate debt** with `'suppress-warning'` — for example an event bus built on `$on` that will be replaced later — so new warnings stay visible. 3. **Convert components** one at a time; each one gets `compatConfig: { MODE: 3 }` or a single-feature opt-out when it is done, so a regression in a converted component shows up as a Vue 3 failure rather than being papered over by compat. 4. **Flip the global default** to `MODE: 3` once most components are converted, keeping only the named leftovers set to `true`. 5. **Remove the alias** when no key is left enabled and the app behaves the same on the standard build. Each step is reversible by changing configuration, which is what makes the migration build safe to ship between steps.