From 226fb60caabffdd6848d077fa5fb0a1264d965c3 Mon Sep 17 00:00:00 2001
From: Jannis Leifeld <j.leifeld@shopware.com>
Date: Wed, 5 Feb 2025 08:56:57 +0100
Subject: [PATCH 1/2] docs: Add documentation for the Vue migration build
 removal

---
 .../system-updates/vue-migration-build.md     | 147 ++++++++++++++++++
 1 file changed, 147 insertions(+)
 create mode 100644 guides/plugins/plugins/administration/system-updates/vue-migration-build.md

diff --git a/guides/plugins/plugins/administration/system-updates/vue-migration-build.md b/guides/plugins/plugins/administration/system-updates/vue-migration-build.md
new file mode 100644
index 000000000..36329209c
--- /dev/null
+++ b/guides/plugins/plugins/administration/system-updates/vue-migration-build.md
@@ -0,0 +1,147 @@
+---
+nav:
+  title: Removing Vue Migration Build
+  position: 260
+---
+
+# Future Development Roadmap: Removing Vue Migration Build
+
+> **Note:** The information provided in this article, including timelines and specific implementations, is subject to change.
+> This document serves as a general guideline for our development direction.
+
+## Introduction
+
+Prior to Shopware 6.7, we utilized the Vue migration build to facilitate the transition from Vue 2 to Vue 3 for plugin developers. This approach allowed most public APIs to behave similarly to Vue 2 while enabling gradual migration.
+
+With the release of Shopware 6.7, the Vue migration build will be removed. All plugins must be fully migrated to Vue 3 without relying on the migration build.
+
+## Why remove the Vue migration build?
+
+The Vue migration build was a temporary solution to help transition from Vue 2 to Vue 3. However, maintaining it indefinitely would introduce complexity, potential performance bottlenecks, and incompatibility with future Vue versions. Removing it ensures that all plugins fully adopt Vue 3, leveraging its improved reactivity system, better TypeScript support, and performance enhancements.
+
+## Migration guide
+
+Shopware's administration is built using Vue 3, and all plugins should be updated accordingly. We recommend referring to the official [Vue 3 migration guide](https://v3-migration.vuejs.org/) for detailed information on breaking changes and deprecations.
+
+Below are some of the most common changes observed in our codebase. This list is not exhaustive, so always consult the official guide for comprehensive migration steps.
+
+### Common Migration Changes
+
+#### `$listeners` removed
+
+In Vue 2, `$listeners` was used to access event listeners passed to a component. In Vue 3, event listeners are now included in `$attrs`.
+
+Before (Vue 2):
+
+```vue
+<template>
+    <sw-button v-on="$listeners">Click me</sw-button>
+</template>
+```
+
+After (Vue 3):
+
+```vue
+<template>
+    <sw-button v-bind="$attrs">Click me</sw-button>
+</template>
+```
+
+More detailed guide: https://v3-migration.vuejs.org/breaking-changes/listeners-removed.html
+
+#### `$scopedSlots` removed
+
+Previously, scoped slots were accessed using `$scopedSlots`. In Vue 3, `$slots` now unifies all slots and exposes them as functions.
+
+Before (Vue 2):
+
+```js
+this.$scopedSlots.header
+```
+
+After (Vue 3):
+
+```js
+this.$slots.header()
+```
+
+More detailed guide: https://v3-migration.vuejs.org/breaking-changes/slots-unification.html
+
+#### `$children` removed
+
+Vue 2 allowed access to child components using $children. In Vue 3, this is no longer supported, and you should use template refs instead.
+
+Before (Vue 2):
+
+```js
+this.$children.childrenMethod();
+```
+
+After (Vue 3):
+
+```js
+// <sw-child ref="childrenRef" />
+
+this.$refs.childrenRef.childrenMethod();
+```
+
+More detailed guide: https://v3-migration.vuejs.org/breaking-changes/children
+
+#### Some Events API removed
+
+The methods `$on`, `$off` and `$once` are removed in Vue 3 without a replacement. You can still use `$emit` to trigger event handlers declaratively attached by a parent component.
+
+Alternatively you can use inject/provide to pass down event handlers using a registration pattern.
+
+It is not possible to give a general guide for this change. You need to adjust your code based on your specific use case. Here is an example how you could adjust your code:
+
+Before (Vue 2):
+
+```js
+created() {
+  this.$parent.$on('doSomething', this.eventHandler);
+},
+
+beforeDestroy() {
+  this.$parent.$off('doSomething', this.eventHandler);
+}
+```
+
+After (Vue 3):
+
+```js
+// The parent component needs to provide the event handler
+inject: ['registerDoSomething', 'unregisterDoSomething'],
+
+created() {
+  this.registerDoSomething(this.eventHandler);
+},
+
+beforeDestroy() {
+  this.unregisterDoSomething(this.eventHandler);
+}
+```
+
+More detailed guide: https://v3-migration.vuejs.org/breaking-changes/events-api.html
+
+#### `$set`, `$delete` removed
+
+Vue 2 required `$set` and `$delete` for reactive property modifications. Vue 3’s new reactivity system, based on ES6 Proxies, removes the need for these methods.
+
+Before (Vue 2):
+
+```js
+this.$set(this.myObject, 'key', 'value');
+this.$delete(this.myObject, 'key');
+```
+
+After (Vue 3):
+
+```js
+this.myObject.key = 'value';
+delete this.myObject.key;
+```
+
+## Conclusion
+
+With Shopware 6.7, the Vue migration build will be fully removed. To ensure compatibility, all plugins must be updated to Vue 3 following the official migration guide. If you encounter challenges during migration, refer to the official Vue 3 documentation or seek assistance from the Shopware developer community.
\ No newline at end of file

From be96e0730a162777188640bf7be9fd0e44bc8b3f Mon Sep 17 00:00:00 2001
From: Jannis Leifeld <j.leifeld@shopware.com>
Date: Tue, 11 Feb 2025 07:59:43 +0100
Subject: [PATCH 2/2] Apply suggestions from code review

Co-authored-by: Bojan Rajh <117360292+bojanrajh@users.noreply.github.com>
---
 .wordlist.txt                                        |  1 +
 .../system-updates/vue-migration-build.md            | 12 ++++++------
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/.wordlist.txt b/.wordlist.txt
index b23c54743..b0e2a64aa 100644
--- a/.wordlist.txt
+++ b/.wordlist.txt
@@ -1135,6 +1135,7 @@ de
 debounce
 decoratable
 decrementing
+declaratively
 deepCopyObject
 deepMergeObject
 defaultConfig
diff --git a/guides/plugins/plugins/administration/system-updates/vue-migration-build.md b/guides/plugins/plugins/administration/system-updates/vue-migration-build.md
index 36329209c..ecdbbe522 100644
--- a/guides/plugins/plugins/administration/system-updates/vue-migration-build.md
+++ b/guides/plugins/plugins/administration/system-updates/vue-migration-build.md
@@ -47,7 +47,7 @@ After (Vue 3):
 </template>
 ```
 
-More detailed guide: https://v3-migration.vuejs.org/breaking-changes/listeners-removed.html
+More detailed guide about [`$listeners` breaking changes](https://v3-migration.vuejs.org/breaking-changes/listeners-removed.html).
 
 #### `$scopedSlots` removed
 
@@ -65,11 +65,11 @@ After (Vue 3):
 this.$slots.header()
 ```
 
-More detailed guide: https://v3-migration.vuejs.org/breaking-changes/slots-unification.html
+More detailed guide about [`$slots` unification breaking changes](https://v3-migration.vuejs.org/breaking-changes/slots-unification.html).
 
 #### `$children` removed
 
-Vue 2 allowed access to child components using $children. In Vue 3, this is no longer supported, and you should use template refs instead.
+Vue 2 allowed access to child components using `$children`. In Vue 3, this is no longer supported, and you should use template refs instead.
 
 Before (Vue 2):
 
@@ -85,7 +85,7 @@ After (Vue 3):
 this.$refs.childrenRef.childrenMethod();
 ```
 
-More detailed guide: https://v3-migration.vuejs.org/breaking-changes/children
+More detailed guide about [`$children` breaking changes](https://v3-migration.vuejs.org/breaking-changes/children).
 
 #### Some Events API removed
 
@@ -122,7 +122,7 @@ beforeDestroy() {
 }
 ```
 
-More detailed guide: https://v3-migration.vuejs.org/breaking-changes/events-api.html
+More detailed guide about [Events API breaking changes](https://v3-migration.vuejs.org/breaking-changes/events-api.html).
 
 #### `$set`, `$delete` removed
 
@@ -144,4 +144,4 @@ delete this.myObject.key;
 
 ## Conclusion
 
-With Shopware 6.7, the Vue migration build will be fully removed. To ensure compatibility, all plugins must be updated to Vue 3 following the official migration guide. If you encounter challenges during migration, refer to the official Vue 3 documentation or seek assistance from the Shopware developer community.
\ No newline at end of file
+With Shopware 6.7, the Vue migration build will be fully removed. To ensure compatibility, all plugins must be updated to Vue 3 following the official migration guide. If you encounter challenges during migration, refer to the official Vue 3 documentation or seek assistance from the Shopware developer community.