Migration build

src/.vuepress/config.js

@@ -171,6 +171,7 @@ const sidebar = {
   ],
   migration: [
     '/guide/migration/introduction',
+    '/guide/migration/migration-build',
     {
       title: 'Details',
       collapsable: false,

src/guide/migration/array-refs.md

@@ -1,7 +1,7 @@
 ---
 title: v-for Array Refs
 badges:
-- breaking
+  - breaking
 ---
 
 # {{ $frontmatter.title }} <MigrationBadges :badges="$frontmatter.badges" />
@@ -70,3 +70,10 @@ Note that:
 - `itemRefs` doesn't have to be an array: it can also be an object where the refs are set by their iteration keys.
 
 - This also allows `itemRefs` to be made reactive and watched, if needed.
+
+## Migration Strategy
+
+[Migration build flags:](migration-build.html#compat-configuration)
+
+- `V_FOR_REF`
+- `COMPILER_V_FOR_REF`

src/guide/migration/async-components.md

@@ -58,7 +58,7 @@ const asyncModalWithOptions = defineAsyncComponent({
 ```
 
 ::: tip NOTE
-Vue Router supports a similar mechanism for asynchronously loading route components, known as *lazy loading*. Despite the similarities, this feature is distinct from Vue's support for async components. You should **not** use `defineAsyncComponent` when configuring route components with Vue Router. You can read more about this in the [Lazy Loading Routes](https://next.router.vuejs.org/guide/advanced/lazy-loading.html) section of the Vue Router documentation.
+Vue Router supports a similar mechanism for asynchronously loading route components, known as _lazy loading_. Despite the similarities, this feature is distinct from Vue's support for async components. You should **not** use `defineAsyncComponent` when configuring route components with Vue Router. You can read more about this in the [Lazy Loading Routes](https://next.router.vuejs.org/guide/advanced/lazy-loading.html) section of the Vue Router documentation.
 :::
 
 Another change that has been made from 2.x is that the `component` option is now renamed to `loader` in order to accurately communicate that a component definition cannot be provided directly.
@@ -95,3 +95,4 @@ const asyncComponent = defineAsyncComponent(
 For more information on the usage of async components, see:
 
 - [Guide: Dynamic & Async Components](/guide/component-dynamic-async.html#dynamic-components-with-keep-alive)
+- [Migration build flag: `COMPONENT_ASYNC`](migration-build.html#compat-configuration)

src/guide/migration/attribute-coercion.md

@@ -137,3 +137,8 @@ In 3.x, `null` or `undefined` should be used to explicitly remove an attribute.
     </tr>
   </tbody>
 </table>
+
+[Migration build flags:](migration-build.html#compat-configuration)
+
+- `ATTR_FALSE_VALUE`
+- `ATTR_ENUMERATED_COERSION`

src/guide/migration/attrs-includes-class-style.md

@@ -60,6 +60,8 @@ when used like this:
 
 In components that use `inheritAttrs: false`, make sure that styling still works as intended. If you previously relied on the special behavior of `class` and `style`, some visuals might be broken as these attributes might now be applied to another element.
 
+[Migration build flag: `INSTANCE_ATTRS_CLASS_STYLE`](migration-build.html#compat-configuration)
+
 ## See also
 
 - [Relevant RFC](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0031-attr-fallthrough.md)

src/guide/migration/children.md

@@ -16,7 +16,7 @@ In 2.x, developers could access direct child components of the current instance
 ```vue
 <template>
   <div>
-    <img alt="Vue logo" src="./assets/logo.png">
+    <img alt="Vue logo" src="./assets/logo.png" />
     <my-button>Change logo</my-button>
   </div>
 </template>
@@ -37,4 +37,8 @@ export default {
 
 ## 3.x Update
 
-In 3.x, the `$children` property is removed and no longer supported. Instead, if you need to access a child component instance, we recommend using [$refs](/guide/component-template-refs.html#template-refs).
+In 3.x, the `$children` property is removed and no longer supported. Instead, if you need to access a child component instance, we recommend using [\$refs](/guide/component-template-refs.html#template-refs).
+
+## Migration Strategy
+
+[Migration build flag: `INSTANCE_CHILDREN`](migration-build.html#compat-configuration)

src/guide/migration/custom-directives.md

@@ -102,3 +102,7 @@ mounted(el, binding, vnode) {
 :::warning
 With [fragments](/guide/migration/fragments.html#overview) support, components can potentially have more than one root node. When applied to a multi-root component, a directive will be ignored and a warning will be logged.
 :::
+
+## Migration Strategy
+
+[Migration build flag: `CUSTOM_DIR`](migration-build.html#compat-configuration)

src/guide/migration/custom-elements-interop.md

@@ -96,6 +96,8 @@ In 3.0, we are limiting Vue's special treatment of the `is` prop to the `<compon
     document.createElement('button', { is: 'plastic-button' })
     ```
 
+[Migration build flag: `COMPILER_IS_ON_ELEMENT`](migration-build.html#compat-configuration)
+
 ## `v-is` for In-DOM Template Parsing Workarounds
 
 > Note: this section only affects cases where Vue templates are directly written in the page's HTML.

src/guide/migration/data-option.md

@@ -64,7 +64,7 @@ Using the example above, there would only be one possible implementation of the
 
 ## Mixin Merge Behavior Change
 
-In addition, when `data()` from a component and its mixins or extends base are merged, the merge is now performed *shallowly*:
+In addition, when `data()` from a component and its mixins or extends base are merged, the merge is now performed _shallowly_:
 
 ```js
 const Mixin = {
@@ -94,9 +94,9 @@ In Vue 2.x, the resulting `$data` is:
 
 ```json
 {
-  user: {
-    id: 2,
-    name: 'Jack'
+  "user": {
+    "id": 2,
+    "name": "Jack"
   }
 }
 ```
@@ -105,12 +105,14 @@ In 3.0, the result will be:
 
 ```json
 {
-  user: {
-    id: 2
+  "user": {
+    "id": 2
   }
 }
 ```
 
+[Migration build flag: `OPTIONS_DATA_FN`](migration-build.html#compat-configuration)
+
 ## Migration Strategy
 
 For users relying on the object declaration, we recommend:
@@ -119,3 +121,8 @@ For users relying on the object declaration, we recommend:
 - Rewrite references to the shared data to point to a new shared object
 
 For users relying on the deep merge behavior from mixins, we recommend refactoring your code to avoid such reliance altogether, since deep merges from mixins are very implicit and can make the code logic more difficult to understand and debug.
+
+[Migration build flags:](migration-build.html#compat-configuration)
+
+- `OPTIONS_DATA_FN`
+- `OPTIONS_DATA_MERGE`

src/guide/migration/events-api.md

@@ -72,10 +72,12 @@ export default {
   $on: (...args) => emitter.on(...args),
   $once: (...args) => emitter.once(...args),
   $off: (...args) => emitter.off(...args),
-  $emit: (...args) => emitter.emit(...args),
+  $emit: (...args) => emitter.emit(...args)
 }
 ```
 
 This provides the same event emitter API as in Vue 2.
 
 These methods may also be supported in a future compatibility build of Vue 3.
+
+[Migration build flag: `INSTANCE_EVENT_EMITTER`](migration-build.html#compat-configuration)

src/guide/migration/filters.md

@@ -73,6 +73,11 @@ Using the example above, here is one example of how it could be implemented.
 
 Instead of using filters, we recommend replacing them with computed properties or methods.
 
+[Migration build flags:](migration-build.html#compat-configuration)
+
+- `FILTERS`
+- `COMPILER_FILTERS`
+
 ### Global Filters
 
 If you are using filters that were globally registered and then used throughout your app, it's likely not convenient to replace them with computed properties or methods in each individual component.

src/guide/migration/functional-components.md

@@ -47,11 +47,7 @@ Or, for those who preferred the `<template>` in a single-file component:
 ```vue
 <!-- Vue 2 Functional Component Example with <template> -->
 <template functional>
-  <component
-    :is="`h${props.level}`"
-    v-bind="attrs"
-    v-on="listeners"
-  />
+  <component :is="`h${props.level}`" v-bind="attrs" v-on="listeners" />
 </template>
 
 <script>
@@ -93,10 +89,7 @@ Using our `<dynamic-heading>` example from before, here is how it would look now
 
 ```vue{1,3,4}
 <template>
-  <component
-    v-bind:is="`h${$props.level}`"
-    v-bind="$attrs"
-  />
+  <component v-bind:is="`h${$props.level}`" v-bind="$attrs" />
 </template>
 
 <script>
@@ -117,3 +110,4 @@ For more information on the usage of the new functional components and the chang
 
 - [Migration: Render Functions](/guide/migration/render-function-api.html)
 - [Guide: Render Functions](/guide/render-function.html)
+- [Migration build flag: `COMPONENT_FUNCTIONAL`](migration-build.html#compat-configuration)

src/guide/migration/global-api.md

@@ -85,6 +85,7 @@ An app instance exposes a subset of the Vue 2 global APIs. The rule of thumb is
 | Vue.mixin                  | app.mixin                                                                                       |
 | Vue.use                    | app.use ([see below](#a-note-for-plugin-authors))                                               |
 | Vue.prototype              | app.config.globalProperties ([see below](#vue-prototype-replaced-by-config-globalproperties))   |
+| Vue.extend                 | _removed_ ([see below](#vue-extend-replaced-by-definecomponent))                                |
 
 All other global APIs that do not globally mutate behavior are now named exports, as documented in [Global API Treeshaking](./global-api-treeshaking.html).
 
@@ -94,6 +95,8 @@ In Vue 3.x, the "use production build" tip will only show up when using the "dev
 
 For ES modules builds, since they are used with bundlers, and in most cases a CLI or boilerplate would have configured the production env properly, this tip will no longer show up.
 
+[Migration build flag: `CONFIG_PRODUCTION_TIP`](migration-build.html#compat-configuration)
+
 ### `config.ignoredElements` Is Now `config.isCustomElement`
 
 This config option was introduced with the intention to support native custom elements, so the renaming better conveys what it does. The new option also expects a function which provides more flexibility than the old string / RegExp approach:
@@ -113,7 +116,9 @@ In Vue 3, the check of whether an element is a component or not has been moved t
 
 - If `config.isCustomElement` is assigned to when using a runtime-only build, a warning will be emitted instructing the user to pass the option in the build setup instead;
 - This will be a new top-level option in the Vue CLI config.
-:::
+  :::
+
+[Migration build flag: `CONFIG_IGNORED_ELEMENTS`](migration-build.html#compat-configuration)
 
 ### `Vue.prototype` Replaced by `config.globalProperties`
 
@@ -134,6 +139,48 @@ app.config.globalProperties.$http = () => {}
 
 Using `provide` (discussed [below](#provide-inject)) should also be considered as an alternative to `globalProperties`.
 
+[Migration build flag: `GLOBAL_PROTOTYPE`](migration-build.html#compat-configuration)
+
+### `Vue.extend` Replaced by `defineComponent`
+
+In Vue 2.x, `Vue.extend` was used to create a "subclass" of the base Vue constructor with the argument that should be an object containing component options. Since in Vue 3.x we don't have a base constructor anymore, this functionality can be replaced with `defineComponent`
+
+```js
+// before - Vue 2
+
+// create constructor
+const Profile = Vue.extend({
+  template: '<p>{{firstName}} {{lastName}} aka {{alias}}</p>',
+  data() {
+    return {
+      firstName: 'Walter',
+      lastName: 'White',
+      alias: 'Heisenberg'
+    }
+  }
+})
+// create an instance of Profile and mount it on an element
+new Profile().$mount('#mount-point')
+```
+
+```js
+// after - Vue 3
+import { defineComponent } from 'vue'
+
+const Profile = defineComponent({
+  template: '<p>{{firstName}} {{lastName}} aka {{alias}}</p>',
+  data() {
+    return {
+      firstName: 'Walter',
+      lastName: 'White',
+      alias: 'Heisenberg'
+    }
+  }
+})
+```
+
+[Migration build flag: `GLOBAL_EXTEND`](migration-build.html#compat-configuration)
+
 ### A Note for Plugin Authors
 
 It is a common practice for plugin authors to install the plugins automatically in their UMD builds using `Vue.use`. For instance, this is how the official `vue-router` plugin installs itself in a browser environment:
@@ -187,6 +234,8 @@ app.directive('focus', {
 app.mount('#app')
 ```
 
+[Migration build flag: `GLOBAL_MOUNT`](migration-build.html#compat-configuration)
+
 ## Provide / Inject
 
 Similar to using the `provide` option in a 2.x root instance, a Vue 3 app instance can also provide dependencies that can be injected by any component inside the app:
@@ -219,7 +268,7 @@ import Bar from './Bar.vue'
 
 const createMyApp = options => {
   const app = createApp(options)
-  app.directive('focus', /* ... */)
+  app.directive('focus' /* ... */)
 
   return app
 }

src/guide/migration/inline-template-attribute.md

@@ -30,6 +30,8 @@ This feature will no longer be supported.
 
 Most of the use cases for `inline-template` assumes a no-build-tool setup, where all templates are written directly inside the HTML page.
 
+[Migration build flag: `COMPILER_INLINE_TEMPLATE`](migration-build.html#compat-configuration)
+
 ### Option #1: Use `<script>` tag
 
 The most straightforward workaround in such cases is using `<script>` with an alternative type:

src/guide/migration/introduction.md

@@ -7,6 +7,7 @@ New to Vue.js? Check out our [Essentials Guide](/guide/introduction.html) to get
 This guide is primarily for users with prior Vue 2 experience who want to learn about the new features and changes in Vue 3. **This is not something you have to read from top to bottom before trying out Vue 3.** While it looks like a lot has changed, a lot of what you know and love about Vue is still the same; but we wanted to be as thorough as possible and provide detailed explanations and examples for every documented change.
 
 - [Quickstart](#quickstart)
+- [Migration Build](#migration-build)
 - [Notable New Features](#notable-new-features)
 - [Breaking Changes](#breaking-changes)
 - [Supporting Libraries](#supporting-libraries)
@@ -20,6 +21,8 @@ Start learning Vue 3 at [Vue Mastery](https://www.vuemastery.com/courses-path/vu
 
 ## Quickstart
 
+If you want to quickly try out Vue 3 in a new project:
+
 - Via CDN: `<script src="https://unpkg.com/vue@next"></script>`
 - In-browser playground on [Codepen](https://codepen.io/yyx990803/pen/OJNoaZL)
 - In-browser Sandbox on [CodeSandbox](https://v3.vue.new)
@@ -37,6 +40,10 @@ Start learning Vue 3 at [Vue Mastery](https://www.vuemastery.com/courses-path/vu
   # select vue 3 preset
   ```
 
+## Migration Build
+
+If you have an existing Vue 2 project or library that you intend to upgrade to Vue 3, we provide a build of Vue 3 that offers Vue 2 compatible APIs. Check out the [Migration Build](./migration-build.html) page for more details.
+
 ## Notable New Features
 
 Some of the new features to keep an eye on in Vue 3 include:
@@ -53,10 +60,6 @@ Some of the new features to keep an eye on in Vue 3 include:
 
 ## Breaking Changes
 
-::: info INFO
-We are still working on a dedicated Migration Build of Vue 3 with Vue 2 compatible behavior and runtime warnings of incompatible usage. If you are planning to migrate a non-trivial Vue 2 app, we strongly recommend waiting for the Migration Build for a smoother experience.
-:::
-
 The following consists a list of breaking changes from 2.x:
 
 ### Global API

src/guide/migration/keycode-modifiers.md

@@ -54,3 +54,8 @@ As a result, this means that `config.keyCodes` is now also deprecated and will n
 ## Migration Strategy
 
 For those using `keyCode` in their codebase, we recommend converting them to their kebab-cased named equivalents.
+
+[Migration build flags:](migration-build.html#compat-configuration)
+
+- `CONFIG_KEY_CODES`
+- `V_ON_KEYCODE_MODIFIER`

src/guide/migration/listeners-removed.md

@@ -65,6 +65,8 @@ If this component received an `id` attribute and a `v-on:close` listener, the `$
 
 Remove all usages of `$listeners`.
 
+[Migration build flag: `INSTANCE_LISTENERS`](migration-build.html#compat-configuration)
+
 ## See also
 
 - [Relevant RFC](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0031-attr-fallthrough.md)