From 6a6abb579d1b903995eb2597a7108f09fa274140 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Seggewi=C3=9F?= Date: Wed, 8 Nov 2023 07:38:52 +0100 Subject: [PATCH] NEXT-31267 - Vue3 update guide --- guides/updates/administration/index.md | 10 +++ guides/updates/administration/vue3.md | 116 +++++++++++++++++++++++++ guides/updates/index.md | 12 +++ 3 files changed, 138 insertions(+) create mode 100644 guides/updates/administration/index.md create mode 100644 guides/updates/administration/vue3.md create mode 100644 guides/updates/index.md diff --git a/guides/updates/administration/index.md b/guides/updates/administration/index.md new file mode 100644 index 0000000000..ab16bbfc78 --- /dev/null +++ b/guides/updates/administration/index.md @@ -0,0 +1,10 @@ +--- +nav: + title: Administration + position: 10 + +--- + +# Administration + +This section contains all update guides related to the Shopware Administration. \ No newline at end of file diff --git a/guides/updates/administration/vue3.md b/guides/updates/administration/vue3.md new file mode 100644 index 0000000000..dd368969df --- /dev/null +++ b/guides/updates/administration/vue3.md @@ -0,0 +1,116 @@ +--- +nav: + title: Vue 3 update + position: 10 + +--- + +# Vue 3 update + +## Introduction + +The Shopware administration uses Vue.js `2`, which will reach its end of life (EOL) on December 31st 2023. To deliver up-to-date and maintainable software, the administration will use Vue.js `3` from Shopware version `6.6` and upwards. If you are unfamiliar with the changes from Vue.js ` 2'to Vue.js `3`, please refer to this (official guide)[https://v3-migration.vuejs.org/]. + +## FAQ + +Let's start with some frequently asked questions. These will also help you figure out if this update affects you. + +### Which extensions are affected by the Vue 3 update? +App-based extensions aren't affected by these changes. However, if your extension is plugin-based and contains custom administration code, you likely need to do some refactoring. + +### Are there any breaking changes I should be aware of? +Yes, Vue 3 introduced breaking changes. It's crucial to review the migration guide provided by Vue.js and this document for detailed information. + +### What steps should I follow to update my Shopware plugin to Vue 3? +Typically, the process involves updating your project dependencies and modifying your code to adhere to Vue 3's API changes. Consult the Vue 3 documentation and this document's step-by-step instructions. + +### Can one plugin version be compatible with Shopware 6.5 and 6.6? +Your plugin requires a new version in the Store. For instance, version `1.x` is for Shopware `6.5.x`, while version `2.0` is compatible with Shopware `6.6` and newer. + +### How can I check if my Shopware extension is compatible with Vue 3? +You can verify compatibility by reviewing the extension's functionality and updating test suites according to this document. + +### Do I need to rewrite my extension to update to Vue 3? +While some changes are required, a complete rewrite is not necessary. The amount of effort is dictated by your use of Vue's internal API. + +### Are tools or libraries available to facilitate the migration to Vue 3? +Yes, there are tools and migration helpers that can automate certain aspects of the update process. You could start by enabling the Vue 3 rule set of `eslint`. + +### Where can I find support and community discussions about updating Shopware plugin to Vue 3? +You can participate in discussions and seek help on the Shopware community Slack. There is a dedicated channel for this topic called `#vue3-update`. + +## External resources + +Here is a handpicked selection of external resources. This list provides a handy reference, granting you access to all the essential materials you might need. + +- (Vue 3 migration guide)[https://v3-migration.vuejs.org] +- (Vue 3 breaking changes)[https://v3-migration.vuejs.org/breaking-changes/] +- (Vue router migration guide)[https://router.vuejs.org/guide/migration/] +- (Vue test utils migration guide)[https://test-utils.vuejs.org/migration/] + +## Step-by-step guide +::: warning +Depending on when you read this document, you still need to enable the `VUE3` feature flag. +To be safe, enable the `VUE3` feature flag and restart your watcher. +::: + +To follow along, you should have the following: + +- the latest Shopware `trunk` or an official release candidate +- installed and activated your plugin +- a running administration watcher (`composer run watch:admin`) + +### Update your plugin npm dependencies + +Make sure to align your `package.json` dependencies with the administration. + +### Verify the Admin is using Vue 3 + +If you evaluate the following expression in the browser dev tools, the value `true` must be returned. + +```javascript +Shopware.Application.view.vue3 +``` + +### Check your templates + +For your templates to work correctly, follow the following in no specific order: + +- Replace all `sw-field` usages with the corresponding components. +- (Check all v-models)[https://v3-migration.vuejs.org/breaking-changes/v-model.html] +- (Check for deprecated slot syntax)[https://eslint.vuejs.org/rules/no-deprecated-slot-attribute.html] +- (Check router-view transition combinations)[https://router.vuejs.org/guide/migration/#-router-view-keep-alive-and-transition-] +- (Check your key attributes)[https://v3-migration.vuejs.org/breaking-changes/key-attribute.html] + +### Check your code + +Most of your code should be unaffected by the update. You can start by searching for `this.$` usages. +If you have a lot of Vue internal API calls, check out the (Known issues section)[#known-issues]. +The best way to find errors is to test your application thoroughly, either by hand or automated. + +## Known issues + +### Lifecycle hooks +Lifecycle hooks such as `@hook:mounted` may be triggered multiple times if the component is loaded asynchronously. Vue 3 will emit the hook for the `AsyncComponentWrapper` and the underlying component. Expect lifecycle hooks to be triggered more than once. + +### Using slots programmatically +It is no longer sufficient to check if `this.$slots` has a property with the slot name to see if that slot exists. Instead, you must verify if your `slotName` contains an actual `v-node`. + +### this.$parent +`this.$parent` is prone to errors because Vue 3 wraps the `AsyncWrapperComponent` around asynchronous components. Leading to the virtual dom tree to differ from Vue 2 to Vue 3. Where in Vue 2, a `this.$parent` call was successful, in Vue 3, a `this.$parent.$parent` may be necessary. + +### Vue dev tools performance +Vue dev tools cause massive performance issues with huge Vue 3 applications. +There is an open (issue on Github)[https://github.com/vuejs/devtools/issues/1875] with next to no activity from the maintainers. + +### v-model changes +`v-model` has several breaking changes. Please consider the official (guide)[https://v3-migration.vuejs.org/breaking-changes/v-model.html] + +### vuex reactivity +Vuex stores lose reactivity if one or more getters alter state data. For more context, see (here)[https://vuejs.org/guide/essentials/reactivity-fundamentals.html#reactivity-fundamentals]. + +### Form field id's +Fields in the administration no longer have the previous ID almost exclusively used in tests. To fix any failing test, add the `name` attribute to your field with a unique identifier. + +### Prop default +Prop default functions no longer have access to the component's `this` scope. You can no longer call `this.$tc` in default functions. Use `Shopware.Snippet.tc` instead. \ No newline at end of file diff --git a/guides/updates/index.md b/guides/updates/index.md new file mode 100644 index 0000000000..bb01c21438 --- /dev/null +++ b/guides/updates/index.md @@ -0,0 +1,12 @@ +--- +nav: + title: Updates + position: 50 + +--- + +# Updates + +Software projects typically undergo changes and updates, for Shopware this is not different. +This section provides you with comprehensive update guides for specific technical changes. +