Migration build (#1033)

Author: NataliaTepluhina

src/.vuepress/config.js

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

src/guide/migration/array-refs.md

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

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

@@ -38,3 +38,7 @@ 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).
+
+## Migration Strategy
+
+[Migration build flag: `INSTANCE_CHILDREN`](migration-build.html#compat-configuration)

src/guide/migration/custom-directives.md

@@ -103,3 +103,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 custom 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

@@ -111,6 +111,8 @@ In 3.0, the result will be:
 }
 ```
 
+[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

@@ -79,3 +79,5 @@ export default {
 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

@@ -117,3 +117,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:
@@ -115,6 +118,8 @@ In Vue 3, the check of whether an element is a component or not has been moved t
 - 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`
 
 In Vue 2, `Vue.prototype` was commonly used to add properties that would be accessible in all components.
@@ -134,6 +139,58 @@ 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` Removed
+
+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. In Vue 3.x, we don't have the concept of component constructors anymore. Mounting a component should always use the `createApp` global API:
+
+```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
+const Profile = {
+  template: '<p>{{firstName}} {{lastName}} aka {{alias}}</p>',
+  data() {
+    return {
+      firstName: 'Walter',
+      lastName: 'White',
+      alias: 'Heisenberg'
+    }
+  }
+}
+
+Vue.createApp(Profile).mount('#mount-point')
+```
+
+#### Type Inference
+
+In Vue 2, `Vue.extend` was also used for providing TypeScript type inference for the component options. In Vue 3, the `defineComponent` global API can be used in place of `Vue.extend` for the same purpose.
+
+Note that although the return type of `defineComponent` is a constructor-like type, it is only used for TSX inference. At runtime `defineComponent` is largely a noop and will return the options object as-is.
+
+#### Component Inheritance
+
+In Vue 3, we strongly recommend favoring composition via [Composition API](/api/composition-api.html) over inheritance and mixins. If for some reason you still need component inheritance, you can use the [`extends` option](/api/options-composition.html#extends) instead of `Vue.extend`.
+
+[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 +244,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:

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)