From 426cf8bc2350629e4d7aa7c789d8acbe9c4ae70d Mon Sep 17 00:00:00 2001 From: NataliaTepluhina Date: Tue, 4 May 2021 17:52:11 +0200 Subject: [PATCH 01/17] feat: started adding migration flags --- src/guide/migration/global-api.md | 8 +++++--- src/guide/migration/migration-build.md | 3 +++ 2 files changed, 8 insertions(+), 3 deletions(-) create mode 100644 src/guide/migration/migration-build.md diff --git a/src/guide/migration/global-api.md b/src/guide/migration/global-api.md index 1d3a402799..cda6d8c804 100644 --- a/src/guide/migration/global-api.md +++ b/src/guide/migration/global-api.md @@ -84,7 +84,7 @@ An app instance exposes a subset of the Vue 2 global APIs. The rule of thumb is | Vue.directive | app.directive | | 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.prototype | app.config.globalProperties ([see below](#vue-prototype-replaced-by-config-globalproperties)) | | All other global APIs that do not globally mutate behavior are now named exports, as documented in [Global API Treeshaking](./global-api-treeshaking.html). @@ -113,7 +113,7 @@ 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. -::: + ::: ### `Vue.prototype` Replaced by `config.globalProperties` @@ -187,6 +187,8 @@ app.directive('focus', { app.mount('#app') ``` +[**Migration build flag**: `GLOBAL_MOUNT`](migration-build.html) + ## 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 +221,7 @@ import Bar from './Bar.vue' const createMyApp = options => { const app = createApp(options) - app.directive('focus', /* ... */) + app.directive('focus' /* ... */) return app } diff --git a/src/guide/migration/migration-build.md b/src/guide/migration/migration-build.md new file mode 100644 index 0000000000..4b59a93190 --- /dev/null +++ b/src/guide/migration/migration-build.md @@ -0,0 +1,3 @@ +## Migration Build + +This is a placeholder page for instructions on the Vue 3.1 migration build From fd9d821c1e3257f23f1b0ba7d90eb4df9266c519 Mon Sep 17 00:00:00 2001 From: NataliaTepluhina Date: Tue, 4 May 2021 18:12:15 +0200 Subject: [PATCH 02/17] feat: added flag and migration for extend --- src/guide/migration/global-api.md | 43 +++++++++++++++++++++++++++- src/guide/migration/mount-changes.md | 1 + 2 files changed, 43 insertions(+), 1 deletion(-) diff --git a/src/guide/migration/global-api.md b/src/guide/migration/global-api.md index cda6d8c804..72c66abc65 100644 --- a/src/guide/migration/global-api.md +++ b/src/guide/migration/global-api.md @@ -84,7 +84,8 @@ An app instance exposes a subset of the Vue 2 global APIs. The rule of thumb is | Vue.directive | app.directive | | 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.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). @@ -134,6 +135,46 @@ app.config.globalProperties.$http = () => {} Using `provide` (discussed [below](#provide-inject)) should also be considered as an alternative to `globalProperties`. +### `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: '

{{firstName}} {{lastName}} aka {{alias}}

', + 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: '

{{firstName}} {{lastName}} aka {{alias}}

', + data() { + return { + firstName: 'Walter', + lastName: 'White', + alias: 'Heisenberg' + } + } +}) +``` + +[**Migration build flag**: `GLOBAL_EXTEND`](migration-build.html) + ### 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: diff --git a/src/guide/migration/mount-changes.md b/src/guide/migration/mount-changes.md index 9b551aacc5..f4aadf60c3 100644 --- a/src/guide/migration/mount-changes.md +++ b/src/guide/migration/mount-changes.md @@ -92,3 +92,4 @@ When this app is mounted to the page that has a `div` with `id="app"`, this will ## See also - [`mount` API](/api/application-api.html#mount) + [**Migration build flag**: `GLOBAL_MOUNT_CONTAINER`](migration-build.html) From 37dfe8b68d7b97503e8b2da05240084ab9162faf Mon Sep 17 00:00:00 2001 From: NataliaTepluhina Date: Tue, 4 May 2021 18:16:28 +0200 Subject: [PATCH 03/17] feat: finished global API --- src/guide/migration/global-api.md | 6 ++++++ src/guide/migration/keycode-modifiers.md | 2 ++ 2 files changed, 8 insertions(+) diff --git a/src/guide/migration/global-api.md b/src/guide/migration/global-api.md index 72c66abc65..d69b73cd16 100644 --- a/src/guide/migration/global-api.md +++ b/src/guide/migration/global-api.md @@ -95,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) + ### `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: @@ -116,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) + ### `Vue.prototype` Replaced by `config.globalProperties` In Vue 2, `Vue.prototype` was commonly used to add properties that would be accessible in all components. @@ -135,6 +139,8 @@ 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) + ### `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` diff --git a/src/guide/migration/keycode-modifiers.md b/src/guide/migration/keycode-modifiers.md index 7d2131423e..5ab61ca9a2 100644 --- a/src/guide/migration/keycode-modifiers.md +++ b/src/guide/migration/keycode-modifiers.md @@ -54,3 +54,5 @@ 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 flag**: `CONFIG_KEY_CODES`](migration-build.html) From 874e3f540fe580adde3051ad367396ef67b67179 Mon Sep 17 00:00:00 2001 From: NataliaTepluhina Date: Wed, 5 May 2021 17:26:19 +0200 Subject: [PATCH 04/17] feat: added the full list of flags --- src/guide/migration/migration-build.md | 290 ++++++++++++++++++++++++- 1 file changed, 289 insertions(+), 1 deletion(-) diff --git a/src/guide/migration/migration-build.md b/src/guide/migration/migration-build.md index 4b59a93190..a81f7229ff 100644 --- a/src/guide/migration/migration-build.md +++ b/src/guide/migration/migration-build.md @@ -1,3 +1,291 @@ -## Migration Build +# Migration Build This is a placeholder page for instructions on the Vue 3.1 migration build + +## Migration Build Configuration Flags + +### `GLOBAL_MOUNT` + +The global app bootstrapping API has changed: `vm.$mount()` and the `el` option have been removed. Use `createApp(RootComponent).mount()` instead. + +[Learn more](/guide/migration/global-api.html#mounting-app-instance) + +### `GLOBAL_MOUNT_CONTAINER` + +Vue detected directives on the mount container. In Vue 3, the container is no longer considered part of the template and will not be processed/replaced. + +[Learn more](/guide/migration/mount-changes.html) + +### `GLOBAL_EXTEND` + +`Vue.extend()` has been removed in Vue 3. Use `defineComponent()` instead. + +[Learn more](/guide/migration/global-api.html#vue-extend-replaced-by-definecomponent) + +### `GLOBAL_PROTOTYPE` + +`Vue.prototype` is no longer available in Vue 3. Use `config.globalProperties` instead. + +[Learn more](/guide/migration/global-api.html#vue-prototype-replaced-by-config-globalproperties) + +### `GLOBAL_SET` + +`Vue.set()` has been removed as it is no longer needed in Vue 3. Simply use native JavaScript mutations. + +### `GLOBAL_DELETE` + +`Vue.delete()` has been removed as it is no longer needed in Vue 3. Simply use native JavaScript mutations.` + +### `GLOBAL_OBSERVABLE` + +`Vue.observable()` has been removed. Use `import { reactive } from 'vue'` from Composition API instead + +[Learn more](/api/basic-reactivity.html) + +### `GLOBAL_PRIVATE_UTIL` + +`Vue.util` has been removed. Please refactor to avoid its usage since it was an internal API even in Vue 2. + +### `CONFIG_SILENT` + +`config.silent` has been removed because it is not good practice to intentionally suppress warnings. You can use your browser console's filter features to focus on relevant messages. + +### `CONFIG_DEVTOOLS` + +`config.devtools` has been removed. To enable devtools for production, configure the `__VUE_PROD_DEVTOOLS__` compile-time flag + +[Learn more](https://github.com/vuejs/vue-next/tree/master/packages/vue#bundler-build-feature-flags) + +### `CONFIG_KEY_CODES` + +`config.keyCodes` has been removed. In Vue 3, you can directly use the kebab-case key names as v-on modifiers. + +[Learn more](/guide/migration/keycode-modifiers.html) + +### `CONFIG_PRODUCTION_TIP` + +`config.productionTip` has been removed. + +[Learn more](/guide/migration/global-api.html#config-productiontip-removed) + +### `CONFIG_IGNORED_ELEMENTS` + +`config.ignoredElements` has been removed. If you are using a runtime build, pass the `isCustomElement` option to `@vue/compiler-dom`. Otherwise, use `config.isCustomElement`. + +[Learn more](/migration/global-api.html#config-ignoredelements-is-now-config-iscustomelement) + +### `CONFIG_WHITESPACE` + +Vue 3 compiler's whitespace option will default to "condense" instead of "preserve". To suppress this warning, provide an explicit value for `config.compilerOptions.whitespace`. + +### `INSTANCE_SET` + +`vm.$set()` has been removed as it is no longer needed in Vue 3. Simply use native JavaScript mutations.` + +### `INSTANCE_DELETE` + +`vm.$delete()` has been removed as it is no longer needed in Vue 3. Simply use native JavaScript mutations. + +### `INSTANCE_DESTROY` + +`vm.$destroy()` has been removed. Use `app.unmount()` instead. + +[Learn more](/api/application-api.html#unmount) + +### `INSTANCE_EVENT_EMITTER` + +`vm.$on/$once/$off()` have been removed. Use an external event emitter library instead. + +[Learn more](/guide/migration/events-api.html) + +### `INSTANCE_EVENT_HOOKS` + +`${event}` lifecycle events are no longer supported. From templates use the `vnode` prefix instead of `hook:`. For example, `@${event}` should be changed to `@vnode-${event.slice(5)`. From JavaScript, use Composition API to dynamically register lifecycle hooks. + +[Learn more](/guide/migration/vnode-lifecycle-events.html) + +### `INSTANCE_CHILDREN` + +`vm.$children` has been removed. Consider refactoring your logic to avoid relying on direct access to child components. + +[Learn more](/guide/migration/children.html) + +### `INSTANCE_LISTENERS` + +`vm.$listeners` has been removed. In Vue 3, parent v-on listeners are included in `vm.$attrs` and it is no longer necessary to separately use `v-on="$listeners"` if you are already using `v-bind="$attrs"` (Note: the Vue 3 behavior only applies if this compatibility config is disabled)`. + +[Learn more](/guide/migration/listeners-removed.html) + +### `INSTANCE_SCOPED_SLOTS` + +`vm.$scopedSlots` has been removed. Use `vm.$slots` instead. + +[Learn more](/guide/migration/slots-unification.html) + +### `INSTANCE_ATTRS_CLASS_STYLE` + +Component has `inheritAttrs: false` but is relying on class/style fallthrough from parent. In Vue 3, class/style are now included in `$attrs` and will no longer fallthrough when `inheritAttrs` is false. If you are already using `v-bind="$attrs"` on component root, it should render the same end result. If you are binding `$attrs` to a non-root element and expecting class/style to fallthrough on root, you will need to now manually bind them on root via `:class="$attrs.class"`. + +[Learn more](/guide/migration/attrs-includes-class-style.html) + +### `OPTIONS_DATA_FN` + +The `data` option can no longer be a plain object. Always use a function. + +[Learn more](/guide/migration/data-option.html) + +### `OPTIONS_DATA_MERGE` + +Detected conflicting key when merging data option values. In Vue 3, data keys are merged shallowly and will override one another. + +[Learn more](/guide/migration/data-option.html#mixin-merge-behavior-change) + +### `OPTIONS_BEFORE_DESTROY` + +`beforeDestroy` has been renamed to `beforeUnmount`. + +### `OPTIONS_DESTROYED` + +`destroyed` has been renamed to `unmounted`. + +### `WATCH_ARRAY` + +`watch` option or `vm.$watch` on an array value will no longer trigger on array mutation unless the `deep` option is specified. + +[Learn more](/guide/migration/watch.html) + +### `PROPS_DEFAULT_THIS` + +`props` default value function no longer has access to `this`. The compatibility build only offers access to `this.$options`. + +[Learn more](/guide/migration/props-default-this.html) + +### `CUSTOM_DIR` + +Custom directive hook has been removed. Use the corresponding new hook instead. + +[Learn more](/guide/migration/custom-directives.html) + +### `V_FOR_REF` + +Ref usage on `v-for` no longer creates array ref values in Vue 3. Consider using function refs or refactor to avoid ref usage altogether. + +[Learn more](/guide/migration/array-refs.html) + +### `V_ON_KEYCODE_MODIFIER` + +Using `keyCode` as `v-on` modifier is no longer supported. Use kebab-case key name modifiers instead. + +[Learn more](/guide/migration/keycode-modifiers.html) + +### `ATTR_FALSE_VALUE` + +Attribute with `v-bind` value `false` will render `="false"` instead of removing it in Vue 3. To remove the attribute use `null` or `undefined` instead. + +[Learn more](/guide/migration/attribute-coercion.html) + +### `ATTR_ENUMERATED_COERSION` + +Enumerated attribute will be removed or render the value as-is instead of coercing the value in Vue 3. Always use explicit `true` or `false` values for enumerated attributes. + +[Learn more](/guide/migration/attribute-coercion.html) + +### `TRANSITION_CLASSES` + +This feature cannot be runtime-detected + +### `TRANSITION_GROUP_ROOT` + +`` no longer renders a root `` element by default if no `tag` prop is specified. + +[Learn more](/guide/migration/transition-group.html) + +### `COMPONENT_ASYNC` + +Async component should be explicitly created via `defineAsyncComponent()` in Vue 3. Plain functions will be treated as functional components in non-compat build. + +[Learn more](/guide/migration/async-components.html) + +### `COMPONENT_FUNCTIONAL` + +Functional component should be defined as a plain function in Vue 3. The `functional` component option has been removed. Before migrating to use plain functions for functional components, first make sure that all async components usage have been migrated and its compat behavior has been disabled. + +[Learn more](/guide/migration/functional-components.html) + +### `COMPONENT_V_MODEL` + +`v-model` usage on component has changed in Vue 3. Component that expects to work with `v-model` should now use the `modelValue` prop and emit the `update:modelValue` event. + +[Learn more](/guide/migration/v-model.html) + +### `RENDER_FUNCTION` + +Vue 3's render function API has changed + +[Learn more](/guide/migration/render-function-api.html) + +### `FILTERS` + +`filters` have been removed in Vue 3. The `|` symbol will be treated as native JavaScript bitwise OR operator. Use method calls or computed properties instead. + +[Learn more](/guide/migration/filters.html) + +### `PRIVATE_APIS` + +There are some Vue 2 private API that no longer exists in Vue 3. + +### `COMPILER_IS_ON_ELEMENT` + +Platform-native elements with `is` prop will no longer be treated as components in Vue 3 unless the `is` value is explicitly prefixed with `vue:`. + +[Learn more](/guide/migration/custom-elements-interop.html) + +### `COMPILER_V_BIND_SYNC` + +`.sync` modifier for `v-bind` has been removed. Use `v-model` with argument instead `v-bind:.sync` should be changed to `v-model:`. + +[Learn more](/guide/migration/v-model.html) + +### `COMPILER_V_BIND_PROP` + +`.prop` modifier for v-bind has been removed and no longer necessary. Vue 3 will automatically set a binding as DOM property when appropriate. + +### `COMPILER_V_BIND_OBJECT_ORDER` + +`v-bind="obj"` usage is now order sensitive and behaves like JavaScript object spread: it will now overwrite an existing non-mergeable attribute that appears before `v-bind` in the case of conflict. To retain 2.x behavior, move v-bind to make it the first attribute. + +[Learn more](/guide/migration/v-bind.html) + +### `COMPILER_V_ON_NATIVE` + +`.native` modifier for `v-on` has been removed as is no longer necessary. + +[Learn more](/guide/migration/v-on-native-modifier-removed.html) + +### `COMPILER_V_IF_V_FOR_PRECEDENCE` + +`v-if` / `v-for` precedence when used on the same element has changed in Vue 3: `v-if` now takes higher precedence and will no longer have access to `v-for` scope variables. It is best to avoid the ambiguity with `