From d35b3045f74b7cec8d9106f71ad722a128111fa1 Mon Sep 17 00:00:00 2001 From: Sebastian Seggewiss Date: Tue, 31 Dec 2024 10:14:03 +0100 Subject: [PATCH] NEXT-37708 - Improve docs --- .wordlist.txt | 8 + .../add-rule-assignment-configuration.md | 0 .../add-shortcuts.md | 0 .../extending-webpack.md | 0 ...fy-blacklist-for-dynamic-product-groups.md | 0 .../handling-media.md | 0 .../search-custom-data.md | 0 .../the-shopware-object.md | 0 .../using-custom-fields.md | 0 .../using-data-handling.md | 0 .../using-the-data-grid-component.md | 0 .../using-vuex-state.md | 0 .../{ => mixins-directives}/add-mixins.md | 0 .../adding-directives.md | 0 .../{ => mixins-directives}/using-mixins.md | 0 .../add-custom-component.md | 0 .../add-custom-field.md | 0 .../add-custom-module.md | 0 .../customizing-components.md | 6 +- .../customizing-modules.md | 0 .../using-base-components.md | 0 .../add-acl-rules.md | 0 .../add-error-handling.md | 0 .../add-custom-route.md | 0 .../add-menu-entry.md | 0 .../{ => routing-navigation}/add-new-tab.md | 0 .../overriding-routes.md | 0 .../add-custom-service.md | 0 .../{ => services-utilities}/add-filter.md | 0 .../extending-services.md | 0 .../injecting-services.md | 0 .../the-sanitizer-helper.md | 0 .../{ => services-utilities}/using-filter.md | 0 .../{ => services-utilities}/using-utils.md | 0 .../administration/system-updates/vite.md | 119 ++++++ .../system-updates/vue-native.md | 340 ++++++++++++++++++ .../add-custom-styles.md | 0 .../adding-snippets.md | 0 .../{ => templates-styling}/using-assets.md | 0 .../writing-templates.md | 0 .../{ => ui-ux}/adding-responsive-behavior.md | 0 41 files changed, 470 insertions(+), 3 deletions(-) rename guides/plugins/plugins/administration/{ => advanced-configuration}/add-rule-assignment-configuration.md (100%) rename guides/plugins/plugins/administration/{ => advanced-configuration}/add-shortcuts.md (100%) rename guides/plugins/plugins/administration/{ => advanced-configuration}/extending-webpack.md (100%) rename guides/plugins/plugins/administration/{ => advanced-configuration}/modify-blacklist-for-dynamic-product-groups.md (100%) rename guides/plugins/plugins/administration/{ => data-handling-processing}/handling-media.md (100%) rename guides/plugins/plugins/administration/{ => data-handling-processing}/search-custom-data.md (100%) rename guides/plugins/plugins/administration/{ => data-handling-processing}/the-shopware-object.md (100%) rename guides/plugins/plugins/administration/{ => data-handling-processing}/using-custom-fields.md (100%) rename guides/plugins/plugins/administration/{ => data-handling-processing}/using-data-handling.md (100%) rename guides/plugins/plugins/administration/{ => data-handling-processing}/using-the-data-grid-component.md (100%) rename guides/plugins/plugins/administration/{ => data-handling-processing}/using-vuex-state.md (100%) rename guides/plugins/plugins/administration/{ => mixins-directives}/add-mixins.md (100%) rename guides/plugins/plugins/administration/{ => mixins-directives}/adding-directives.md (100%) rename guides/plugins/plugins/administration/{ => mixins-directives}/using-mixins.md (100%) rename guides/plugins/plugins/administration/{ => module-component-management}/add-custom-component.md (100%) rename guides/plugins/plugins/administration/{ => module-component-management}/add-custom-field.md (100%) rename guides/plugins/plugins/administration/{ => module-component-management}/add-custom-module.md (100%) rename guides/plugins/plugins/administration/{ => module-component-management}/customizing-components.md (99%) rename guides/plugins/plugins/administration/{ => module-component-management}/customizing-modules.md (100%) rename guides/plugins/plugins/administration/{ => module-component-management}/using-base-components.md (100%) rename guides/plugins/plugins/administration/{ => permissions-error-handling}/add-acl-rules.md (100%) rename guides/plugins/plugins/administration/{ => permissions-error-handling}/add-error-handling.md (100%) rename guides/plugins/plugins/administration/{ => routing-navigation}/add-custom-route.md (100%) rename guides/plugins/plugins/administration/{ => routing-navigation}/add-menu-entry.md (100%) rename guides/plugins/plugins/administration/{ => routing-navigation}/add-new-tab.md (100%) rename guides/plugins/plugins/administration/{ => routing-navigation}/overriding-routes.md (100%) rename guides/plugins/plugins/administration/{ => services-utilities}/add-custom-service.md (100%) rename guides/plugins/plugins/administration/{ => services-utilities}/add-filter.md (100%) rename guides/plugins/plugins/administration/{ => services-utilities}/extending-services.md (100%) rename guides/plugins/plugins/administration/{ => services-utilities}/injecting-services.md (100%) rename guides/plugins/plugins/administration/{ => services-utilities}/the-sanitizer-helper.md (100%) rename guides/plugins/plugins/administration/{ => services-utilities}/using-filter.md (100%) rename guides/plugins/plugins/administration/{ => services-utilities}/using-utils.md (100%) create mode 100644 guides/plugins/plugins/administration/system-updates/vite.md create mode 100644 guides/plugins/plugins/administration/system-updates/vue-native.md rename guides/plugins/plugins/administration/{ => templates-styling}/add-custom-styles.md (100%) rename guides/plugins/plugins/administration/{ => templates-styling}/adding-snippets.md (100%) rename guides/plugins/plugins/administration/{ => templates-styling}/using-assets.md (100%) rename guides/plugins/plugins/administration/{ => templates-styling}/writing-templates.md (100%) rename guides/plugins/plugins/administration/{ => ui-ux}/adding-responsive-behavior.md (100%) diff --git a/.wordlist.txt b/.wordlist.txt index 4748d2c6b..3df9f927e 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -34,6 +34,7 @@ AdminWorker adr ADR ADRs +add's Afile AfterLineItemAddedEvent AfterLineItemQuantityChangedEvent @@ -435,6 +436,7 @@ dereferenced DESC describeFeatures destructuring +destructure Deutsch dev devenv @@ -694,6 +696,7 @@ herokuapp hideCookieBar hmac HMAC +HMR Homebrew hono Hono @@ -1130,6 +1133,7 @@ PHPUnit phpunit's phpunitx PII +Pinia pluginlogger PluginManager png @@ -1160,6 +1164,7 @@ prem premapping Premapping PreparedPaymentHandlerInterface +prepend preprocessor preprocessors preselect @@ -1384,6 +1389,7 @@ setProductFixtureVisibility setSalesChannelDomain settingsItem setToInitialState +SFC SFTP sha SHA @@ -1584,6 +1590,7 @@ truthy tsx TTL TwigJS +twigjs typeAndCheck typeAndCheckSearchField TypeError @@ -1674,6 +1681,7 @@ viewportHeight viewports vimeo VirtualHosts +Vite Vitepress Vitest VM diff --git a/guides/plugins/plugins/administration/add-rule-assignment-configuration.md b/guides/plugins/plugins/administration/advanced-configuration/add-rule-assignment-configuration.md similarity index 100% rename from guides/plugins/plugins/administration/add-rule-assignment-configuration.md rename to guides/plugins/plugins/administration/advanced-configuration/add-rule-assignment-configuration.md diff --git a/guides/plugins/plugins/administration/add-shortcuts.md b/guides/plugins/plugins/administration/advanced-configuration/add-shortcuts.md similarity index 100% rename from guides/plugins/plugins/administration/add-shortcuts.md rename to guides/plugins/plugins/administration/advanced-configuration/add-shortcuts.md diff --git a/guides/plugins/plugins/administration/extending-webpack.md b/guides/plugins/plugins/administration/advanced-configuration/extending-webpack.md similarity index 100% rename from guides/plugins/plugins/administration/extending-webpack.md rename to guides/plugins/plugins/administration/advanced-configuration/extending-webpack.md diff --git a/guides/plugins/plugins/administration/modify-blacklist-for-dynamic-product-groups.md b/guides/plugins/plugins/administration/advanced-configuration/modify-blacklist-for-dynamic-product-groups.md similarity index 100% rename from guides/plugins/plugins/administration/modify-blacklist-for-dynamic-product-groups.md rename to guides/plugins/plugins/administration/advanced-configuration/modify-blacklist-for-dynamic-product-groups.md diff --git a/guides/plugins/plugins/administration/handling-media.md b/guides/plugins/plugins/administration/data-handling-processing/handling-media.md similarity index 100% rename from guides/plugins/plugins/administration/handling-media.md rename to guides/plugins/plugins/administration/data-handling-processing/handling-media.md diff --git a/guides/plugins/plugins/administration/search-custom-data.md b/guides/plugins/plugins/administration/data-handling-processing/search-custom-data.md similarity index 100% rename from guides/plugins/plugins/administration/search-custom-data.md rename to guides/plugins/plugins/administration/data-handling-processing/search-custom-data.md diff --git a/guides/plugins/plugins/administration/the-shopware-object.md b/guides/plugins/plugins/administration/data-handling-processing/the-shopware-object.md similarity index 100% rename from guides/plugins/plugins/administration/the-shopware-object.md rename to guides/plugins/plugins/administration/data-handling-processing/the-shopware-object.md diff --git a/guides/plugins/plugins/administration/using-custom-fields.md b/guides/plugins/plugins/administration/data-handling-processing/using-custom-fields.md similarity index 100% rename from guides/plugins/plugins/administration/using-custom-fields.md rename to guides/plugins/plugins/administration/data-handling-processing/using-custom-fields.md diff --git a/guides/plugins/plugins/administration/using-data-handling.md b/guides/plugins/plugins/administration/data-handling-processing/using-data-handling.md similarity index 100% rename from guides/plugins/plugins/administration/using-data-handling.md rename to guides/plugins/plugins/administration/data-handling-processing/using-data-handling.md diff --git a/guides/plugins/plugins/administration/using-the-data-grid-component.md b/guides/plugins/plugins/administration/data-handling-processing/using-the-data-grid-component.md similarity index 100% rename from guides/plugins/plugins/administration/using-the-data-grid-component.md rename to guides/plugins/plugins/administration/data-handling-processing/using-the-data-grid-component.md diff --git a/guides/plugins/plugins/administration/using-vuex-state.md b/guides/plugins/plugins/administration/data-handling-processing/using-vuex-state.md similarity index 100% rename from guides/plugins/plugins/administration/using-vuex-state.md rename to guides/plugins/plugins/administration/data-handling-processing/using-vuex-state.md diff --git a/guides/plugins/plugins/administration/add-mixins.md b/guides/plugins/plugins/administration/mixins-directives/add-mixins.md similarity index 100% rename from guides/plugins/plugins/administration/add-mixins.md rename to guides/plugins/plugins/administration/mixins-directives/add-mixins.md diff --git a/guides/plugins/plugins/administration/adding-directives.md b/guides/plugins/plugins/administration/mixins-directives/adding-directives.md similarity index 100% rename from guides/plugins/plugins/administration/adding-directives.md rename to guides/plugins/plugins/administration/mixins-directives/adding-directives.md diff --git a/guides/plugins/plugins/administration/using-mixins.md b/guides/plugins/plugins/administration/mixins-directives/using-mixins.md similarity index 100% rename from guides/plugins/plugins/administration/using-mixins.md rename to guides/plugins/plugins/administration/mixins-directives/using-mixins.md diff --git a/guides/plugins/plugins/administration/add-custom-component.md b/guides/plugins/plugins/administration/module-component-management/add-custom-component.md similarity index 100% rename from guides/plugins/plugins/administration/add-custom-component.md rename to guides/plugins/plugins/administration/module-component-management/add-custom-component.md diff --git a/guides/plugins/plugins/administration/add-custom-field.md b/guides/plugins/plugins/administration/module-component-management/add-custom-field.md similarity index 100% rename from guides/plugins/plugins/administration/add-custom-field.md rename to guides/plugins/plugins/administration/module-component-management/add-custom-field.md diff --git a/guides/plugins/plugins/administration/add-custom-module.md b/guides/plugins/plugins/administration/module-component-management/add-custom-module.md similarity index 100% rename from guides/plugins/plugins/administration/add-custom-module.md rename to guides/plugins/plugins/administration/module-component-management/add-custom-module.md diff --git a/guides/plugins/plugins/administration/customizing-components.md b/guides/plugins/plugins/administration/module-component-management/customizing-components.md similarity index 99% rename from guides/plugins/plugins/administration/customizing-components.md rename to guides/plugins/plugins/administration/module-component-management/customizing-components.md index 6a9ac45bc..cecc40baa 100644 --- a/guides/plugins/plugins/administration/customizing-components.md +++ b/guides/plugins/plugins/administration/module-component-management/customizing-components.md @@ -480,6 +480,6 @@ Shopware.Component.overrideComponentSetup()('sw-customer-list', (previousState, ## More interesting topics -* [Customizing templates](writing-templates) -* [Customizing via custom styles](add-custom-styles) -* [Using base components](using-base-components) +- [Customizing templates](writing-templates) +- [Customizing via custom styles](add-custom-styles) +- [Using base components](using-base-components) diff --git a/guides/plugins/plugins/administration/customizing-modules.md b/guides/plugins/plugins/administration/module-component-management/customizing-modules.md similarity index 100% rename from guides/plugins/plugins/administration/customizing-modules.md rename to guides/plugins/plugins/administration/module-component-management/customizing-modules.md diff --git a/guides/plugins/plugins/administration/using-base-components.md b/guides/plugins/plugins/administration/module-component-management/using-base-components.md similarity index 100% rename from guides/plugins/plugins/administration/using-base-components.md rename to guides/plugins/plugins/administration/module-component-management/using-base-components.md diff --git a/guides/plugins/plugins/administration/add-acl-rules.md b/guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.md similarity index 100% rename from guides/plugins/plugins/administration/add-acl-rules.md rename to guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.md diff --git a/guides/plugins/plugins/administration/add-error-handling.md b/guides/plugins/plugins/administration/permissions-error-handling/add-error-handling.md similarity index 100% rename from guides/plugins/plugins/administration/add-error-handling.md rename to guides/plugins/plugins/administration/permissions-error-handling/add-error-handling.md diff --git a/guides/plugins/plugins/administration/add-custom-route.md b/guides/plugins/plugins/administration/routing-navigation/add-custom-route.md similarity index 100% rename from guides/plugins/plugins/administration/add-custom-route.md rename to guides/plugins/plugins/administration/routing-navigation/add-custom-route.md diff --git a/guides/plugins/plugins/administration/add-menu-entry.md b/guides/plugins/plugins/administration/routing-navigation/add-menu-entry.md similarity index 100% rename from guides/plugins/plugins/administration/add-menu-entry.md rename to guides/plugins/plugins/administration/routing-navigation/add-menu-entry.md diff --git a/guides/plugins/plugins/administration/add-new-tab.md b/guides/plugins/plugins/administration/routing-navigation/add-new-tab.md similarity index 100% rename from guides/plugins/plugins/administration/add-new-tab.md rename to guides/plugins/plugins/administration/routing-navigation/add-new-tab.md diff --git a/guides/plugins/plugins/administration/overriding-routes.md b/guides/plugins/plugins/administration/routing-navigation/overriding-routes.md similarity index 100% rename from guides/plugins/plugins/administration/overriding-routes.md rename to guides/plugins/plugins/administration/routing-navigation/overriding-routes.md diff --git a/guides/plugins/plugins/administration/add-custom-service.md b/guides/plugins/plugins/administration/services-utilities/add-custom-service.md similarity index 100% rename from guides/plugins/plugins/administration/add-custom-service.md rename to guides/plugins/plugins/administration/services-utilities/add-custom-service.md diff --git a/guides/plugins/plugins/administration/add-filter.md b/guides/plugins/plugins/administration/services-utilities/add-filter.md similarity index 100% rename from guides/plugins/plugins/administration/add-filter.md rename to guides/plugins/plugins/administration/services-utilities/add-filter.md diff --git a/guides/plugins/plugins/administration/extending-services.md b/guides/plugins/plugins/administration/services-utilities/extending-services.md similarity index 100% rename from guides/plugins/plugins/administration/extending-services.md rename to guides/plugins/plugins/administration/services-utilities/extending-services.md diff --git a/guides/plugins/plugins/administration/injecting-services.md b/guides/plugins/plugins/administration/services-utilities/injecting-services.md similarity index 100% rename from guides/plugins/plugins/administration/injecting-services.md rename to guides/plugins/plugins/administration/services-utilities/injecting-services.md diff --git a/guides/plugins/plugins/administration/the-sanitizer-helper.md b/guides/plugins/plugins/administration/services-utilities/the-sanitizer-helper.md similarity index 100% rename from guides/plugins/plugins/administration/the-sanitizer-helper.md rename to guides/plugins/plugins/administration/services-utilities/the-sanitizer-helper.md diff --git a/guides/plugins/plugins/administration/using-filter.md b/guides/plugins/plugins/administration/services-utilities/using-filter.md similarity index 100% rename from guides/plugins/plugins/administration/using-filter.md rename to guides/plugins/plugins/administration/services-utilities/using-filter.md diff --git a/guides/plugins/plugins/administration/using-utils.md b/guides/plugins/plugins/administration/services-utilities/using-utils.md similarity index 100% rename from guides/plugins/plugins/administration/using-utils.md rename to guides/plugins/plugins/administration/services-utilities/using-utils.md diff --git a/guides/plugins/plugins/administration/system-updates/vite.md b/guides/plugins/plugins/administration/system-updates/vite.md new file mode 100644 index 000000000..a4dc20c7e --- /dev/null +++ b/guides/plugins/plugins/administration/system-updates/vite.md @@ -0,0 +1,119 @@ +--- +nav: + title: Changing from Webpack to Vite + position: 260 +--- + +# Future Development Roadmap: Changing from Webpack to Vite + +> **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 + +We are planning substantial changes to the way we build our Vue.js application. +The current Webpack build system has been in place for quite some time now, but like everything in tech, it becomes outdated sooner than later. Additionally to Webpack being slow and outdated, we identified a security risk for the future of our application. Many Webpack maintainers have moved on to other projects. Therefore, the Webpack project no longer receives significant updates. The same applies to the Webpack loaders we currently use. + +## Introducing Vite + +The Vue.js ecosystem has built its own bundler: Vite. Vite is fast, easier to configure and the new standard for Vue.js applications. That's why we decided to switch to Vite with Shopware 6.7. + +## Consequences for extensions + +For apps there are no consequences as your build process is already decoupled from Shopware. For plugins you only need to get active if you currently extend the webpack config by providing your own `webpack.config.js` file. + +## Implementation details + +In this section we'll document the implementation details of the new Vite setup. + +### Feature flag + +The system is already in place and can be tested by activating the feature flag: `ADMIN_VITE`. + +### Bundle information + +The information about all active bundles/plugins is written to `/var/plugins.json` by the `Shopware\Core\Framework\Plugin\Command\BundleDumpCommand`. This command can be triggered standalone by running `php bin/console bundle:dump`. It is also part of the composer commands `build:js:admin`, `build:js:storefront`, `watch:admin` and `watch:storefront`. This file is used to load all the Shopware Bundles and custom plugins. + +### Building the Shopware Administration + +The command responsible for building the Shopware Administration with all extensions remains `composer build:js:admin`. + +### Building the core + +The Vite config located under `/src/Administration/Resources/app/administration/vite.config.mts` is only responsible for the core without extensions. Currently there are a few file duplications because Vite requires different module loading order. You can recognize these files, they look like this: `*.vite.ts`. So for example the entry file `/src/Administration/Resources/app/administration/src/index.vite.ts`. + +### Building extensions + +The script responsible for building all extensions is located at `/src/Administration/Resources/app/administration/build/plugins.vite.ts`. This script uses the JS API of Vite to build all extensions. As mentioned above, it's still part of the `composer build:js:admin` command and needs no manual execution. + +The script will do the following: + +1. Get all bundles/plugins from the `/var/plugins.json` +2. Call `build` from Vite for each plugin +3. The `build` function of Vite will automatically load `vite.config` files from the path of the entry file. + +### Dev mode/HMR server + +The command responsible for serving the application in dev mode (HMR server) is still `composer watch:admin`. For the core it's just going to take the `vite.config.mts` again and this time the `plugins.vite.ts` script will call `createServer` for each plugin. + +### Loading Vite assets + +Once built the right assets need to be loaded somehow into the administration. For the core we use the `pentatrion_vite` Symfony bundle. Loading the correct file(s) based on the `entrypoints.json` file generated by its counterpart `vite-plugin-symfony`. For bundles and plugins the boot process inside the `application.ts` will load and inject the entry files based on the environment. + +Production build: + +- Information is taken from the `/api/_info/config` call + +Dev mode/HMR server: + +- Information is served by our own Vite plugin `shopware-vite-plugin-serve-multiple-static` in form of the `sw-plugin-dev.json` file requested by the `application.ts` + +## Vite plugins + +To accomplish all this, we created a few Vite plugins and in this section we'll take the time to explain what they do. All our Vite plugin names are prefixed with `shopware-vite-plugin-`. I'll leave this out of the headlines for better readability. + +### asset-path + +This plugin manipulates the chunk loading function of Vite, to prepend the `window.__sw__.assetPath` to the chunk path. This is needed for cluster setups, serving the assets from a S3 bucket. + +### static-assets + +Copies static admin assets from `static` to the output directory so they can get served. + +### serve-multiple-static + +Serves static assets in dev mode (HMR server). + +### vue-globals + +Replacing all Vue imports in bundles/plugins to destructure from `Shopware.Vue`. This solves the problem of having multiple Vue instances. It does this by creating a temporary file exporting the Shopware.Vue and adding an alias to point every Vue import to that temporary file. This way it will result in bundled code like this: + +From this: + +```vue +// From this + + +// To this + +``` + +### override-component + +Registering `*.override.vue` files automatically. It will search for all files matching the override pattern and automatically import them into the bundle/plugin entry file. Additionally, these imports will be registered as override components by calling `Shopware.Component.registerOverrideComponent`. This will make sure that all overrides are loaded at any time as soon as the bundle/plugin script is injected. To learn more about the new overrides take a look at the Vue native docs right next to this file. + +### twigjs + +Transforming all `*.html.twig` files in a way that they can be loaded by Vite. + +## HMR reloading + +A quick note on HMR (Hot Module Replacement). Vite is only capable of reloading `*.vue` files. This means that we can only leverage the HMR by the time we transitioned everything to SFC (Single File Components) but once we do the Vite setup will be able to distinguish between changes in a plugin or the core. + +## Performance + +Vite is able to build the core Administration in ~18s on my system. This is a saving of over 50% compared to Webpack. In dev mode it's similar but not directly comparable. The Vite dev server starts instantly and moves the loading time to the first request. Webpack on the other hand compiles a long time upfront until the server is ready. diff --git a/guides/plugins/plugins/administration/system-updates/vue-native.md b/guides/plugins/plugins/administration/system-updates/vue-native.md new file mode 100644 index 000000000..7f34d715a --- /dev/null +++ b/guides/plugins/plugins/administration/system-updates/vue-native.md @@ -0,0 +1,340 @@ +--- +nav: + title: Native Vue + position: 260 +--- + +# Future Development Roadmap: Moving Towards Vue Native + +> **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 + +We are planning a significant shift in our development approach, moving towards a more native Vue.js implementation. +This document outlines the reasons for this change and provides an overview of our upgrade path. + +## Current status + +To better understand the changes described in this article, let's recap the current status. +The Shopware 6 Administration is built around Vue.js with several custom systems on top to allow for extensions. + +### Custom component registration + +```javascript +Shopware.Component.register('sw-component', { + template, + + //... +}); +``` + +### Custom templates with Twig.Js + +```html +{% block sw-component %} + +{% endblock %} +``` + +## Why Go Native? + +Our transition to a more native Vue.js approach is driven by several key factors: + +1. **Improved Developer Experience** + - Devtool enhancements + - Easier maintenance + +2. **Future-Proofing** + - Aligning with Vue 3 and potential future versions + - Preparing for upcoming industry standards + +3. **Performance Optimization** + - Leveraging native Vue.js capabilities for better performance + +## Major Changes + +### 1. Moving from Options API to Composition API + +#### Why Make This Change? + +We aim to better align with Vue's ecosystem, to minimize the amount of specifications new Developers need to learn. +The Composition API has become the new standard for Vue's documentation and projects all over Github. +Renowned libraries like `vue-i18n` are dropping support of the Options API, as seen in their [migration guide](https://vue-i18n.intlify.dev/guide/migration/vue3#summary), and we expect similar transitions from other tools in the ecosystem. +This also aligns with Vue's best practices, as highlighted in the official [Composition API FAQ](https://vuejs.org/guide/extras/composition-api-faq.html#why-composition-api). + +#### What Will Change? + +We will gradually transform our components from Options API to Composition API. Together with native blocks, this builds the foundation to use Single File Components (SFC). +The transformation will be stretched over multiple major versions to offer enough time for all of us to adapt. Take a look at the estimated timeline below. + +#### Upgrade Path + +| Shopware Version | Options API | Composition API | +|:----------------:|---------------------------------|------------------------------| +| 6.7 | Standard | Experimental | +| 6.8 | Still supported for extensions* | Standard for Core components | +| 6.9 | Removed completely | Standard | + +*Extensions still can register components using the Options API; overwriting Core components needs the Composition API. + +### 2. TwigJS to Native Blocks + +#### Why Make This Change? + +Vue has no native support for blocks like in Twig.js. Vue has slots, but slots don't work like blocks. +Recently, we accomplished the unthinkable and found a way to implement blocks with native Vue components. +This will allow us to finally use SFC and keep the extendability of Twig.js. +Lowering the learning curve, as the Twig.js syntax is especially unfamiliar to Vue developers. +Standard tooling like VSCode, ESLint, and Prettier will work out of the box. + +#### What Will Change? + +We will gradually transform all component templates from external `*.html.twig` files with Twig.Js into `.vue` files using the native block implementation. + +#### Upgrade Path + +| Shopware Version | Twig.Js | Native blocks | +|:----------------:|---------------------------------|------------------------------| +| 6.7 | Standard | Experimental | +| 6.8 | Still supported for extensions* | Standard for Core components | +| 6.9 | Removed completely | Standard | + +*Extensions still can register components using Twig.Js templates; overwriting Core blocks needs the native block implementation. + +### 3. Vuex to Pinia + +#### Why Make This Change? + +Vuex has been the default State management for Vue 2. For Vue 3 Pinia took it's place. + +#### What Will Change? + +We will move all core Vuex states to Pinia stores. The public API will change from `Shopware.State` to `Shopware.Store`. + +#### Upgrade Path + +| Shopware Version | Vuex | Pinia | +|:----------------:|---------------------------------|------------------------------| +| 6.7 | Still supported for extensions* | Standard for Core components | +| 6.8 | Removed completely | Standard | + +*Extensions still can register Vuex states; Accessing core stores is done via Pinia + +## Example: Component Evolution + +Now let's take a look how core and extension components will evolve. + +### Shopware 6.7 + +First we start with the current status which is still compatible with Shopware 6.7. + +#### Core component + +In the core we register a component via `Shopware.Component.register`. + +```javascript +Shopware.Component.register('sw-text-field', { + template: ` + {% block sw-text-field %} + + {% endblock %} + `, + + data() { + return { + value: null, + } + }, + + methods: { + onChange() { + this.$emit('update:value', this.value); + } + }, +}); +``` + +#### Extension override + +The extension overrides the component via `Shopware.Component.override`. + +```javascript +Shopware.Component.override('sw-text-field', { + template: ` + {% block sw-text-field %} + {% parent %} + + {{ helpText }} + {% endblock %} + `, + + props: { + helpText: { + type: String, + required: false, + } + } +}) +``` + +#### Extension new component + +The extension add's an additional component via `Shopware.Component.register`. + +```javascript +Shopware.Component.register('your-crazy-ai-field', { + template: ` + {% block your-crazy-ai-field %} + {# ... #} + {% endblock %} + `, + + // Options API implementation +}) +``` + +### Shopware 6.8 + +With Shopware 6.8 the core uses single file components with the composition api. + +#### Core component + +The core component is added via a single file component `*.vue` file. + +```vue + + + +``` + +#### Extension override + +For overrides we created a new convention. They must match the `*.override.vue` pattern. +`*.override.vue` files will be loaded automatically in your main entry file. + +```vue + + + +``` + +#### Extension new component + +```javascript + +// For this you would also have the option to use a `*.vue` file but you don't have to +Shopware.Component.register('your-crazy-ai-field', { + template: ` + {% block your-crazy-ai-field %} + {# ... #} + {% endblock %} + `, + + // Options API implementation +}) +``` + +### Shopware 6.9 + +The only difference for 6.9 is that you can no longer register new components via `Shopware.Component.register`. + +## FAQ + +**Will existing extensions built with Options API continue to work in Shopware 6.8?** + +When you only use `Shopware.Component.register` yes. If you also use `Shopware.Component.extend/ override` you need to use the composition API extension approach for that. + +**How can I prepare my development team for the transition to Composition API?** + +I would recommend building a simple Vue application using the Composition API. You can do so by following [official guides](https://vuejs.org/guide/extras/composition-api-faq.html). + +**What advantages does the native block implementation offer over the current Twig.js system?** + +It works with native Vue.Js components, therefore is compatible with default tooling. + +**Can I mix Composition API and Options API components during the transition period?** + +Yes as long as you stick to the limitations from the upgrade paths. + +**How will the migration from Twig.js templates to .vue files affect my existing component overrides?** + +You need to migrate all your overrides with Shopware 6.8. + +**What tools or resources will be available to help migrate existing components?** + +We'll try to provide a code mod to transition your components into SFC. This will not work for all edge cases, so you need to manually check and transition them. + +**Will there be any performance impact during the transition period when both systems are supported?** + +During our tests we didn't experience any performance issues. + +**How does the new `Shopware.Component.createExtendableSetup` function work with TypeScript?** + +It has built in TypeScript support. + +**What happens to existing extensions using Twig.js templates after version 6.9?** + +They will stop working with Shopware version 6.9. + +**Can I start using the native blocks and Composition API in my extensions before version 6.8?** + +Yes! You can add new components using SFC and native blocks. But you can't extend core components using the old systems or vise versa. + +**Which extensions are affected by these changes?** + +- Apps aren't affected at all +- Plugins need to respect the discussed changes diff --git a/guides/plugins/plugins/administration/add-custom-styles.md b/guides/plugins/plugins/administration/templates-styling/add-custom-styles.md similarity index 100% rename from guides/plugins/plugins/administration/add-custom-styles.md rename to guides/plugins/plugins/administration/templates-styling/add-custom-styles.md diff --git a/guides/plugins/plugins/administration/adding-snippets.md b/guides/plugins/plugins/administration/templates-styling/adding-snippets.md similarity index 100% rename from guides/plugins/plugins/administration/adding-snippets.md rename to guides/plugins/plugins/administration/templates-styling/adding-snippets.md diff --git a/guides/plugins/plugins/administration/using-assets.md b/guides/plugins/plugins/administration/templates-styling/using-assets.md similarity index 100% rename from guides/plugins/plugins/administration/using-assets.md rename to guides/plugins/plugins/administration/templates-styling/using-assets.md diff --git a/guides/plugins/plugins/administration/writing-templates.md b/guides/plugins/plugins/administration/templates-styling/writing-templates.md similarity index 100% rename from guides/plugins/plugins/administration/writing-templates.md rename to guides/plugins/plugins/administration/templates-styling/writing-templates.md diff --git a/guides/plugins/plugins/administration/adding-responsive-behavior.md b/guides/plugins/plugins/administration/ui-ux/adding-responsive-behavior.md similarity index 100% rename from guides/plugins/plugins/administration/adding-responsive-behavior.md rename to guides/plugins/plugins/administration/ui-ux/adding-responsive-behavior.md