NEXT-37708 - Improve docs

shopware · Jan 7, 2025 · d35b304 · d35b304
1 parent 7444071
commit d35b304
Show file tree

Hide file tree

Showing 41 changed files with 470 additions and 3 deletions.
diff --git 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/...tion/add-rule-assignment-configuration.md → ...tion/add-rule-assignment-configuration.md b/...tion/add-rule-assignment-configuration.md → ...tion/add-rule-assignment-configuration.md
diff --git a/...s/plugins/administration/add-shortcuts.md → ...n/advanced-configuration/add-shortcuts.md b/...s/plugins/administration/add-shortcuts.md → ...n/advanced-configuration/add-shortcuts.md
diff --git a/...ugins/administration/extending-webpack.md → ...vanced-configuration/extending-webpack.md b/...ugins/administration/extending-webpack.md → ...vanced-configuration/extending-webpack.md
diff --git a/...y-blacklist-for-dynamic-product-groups.md → ...y-blacklist-for-dynamic-product-groups.md b/...y-blacklist-for-dynamic-product-groups.md → ...y-blacklist-for-dynamic-product-groups.md
diff --git a/.../plugins/administration/handling-media.md → ...ata-handling-processing/handling-media.md b/.../plugins/administration/handling-media.md → ...ata-handling-processing/handling-media.md
diff --git a/...gins/administration/search-custom-data.md → ...handling-processing/search-custom-data.md b/...gins/administration/search-custom-data.md → ...handling-processing/search-custom-data.md
diff --git a/...ins/administration/the-shopware-object.md → ...andling-processing/the-shopware-object.md b/...ins/administration/the-shopware-object.md → ...andling-processing/the-shopware-object.md
diff --git a/...ins/administration/using-custom-fields.md → ...andling-processing/using-custom-fields.md b/...ins/administration/using-custom-fields.md → ...andling-processing/using-custom-fields.md
diff --git a/...ins/administration/using-data-handling.md → ...andling-processing/using-data-handling.md b/...ins/administration/using-data-handling.md → ...andling-processing/using-data-handling.md
diff --git a/...stration/using-the-data-grid-component.md → ...ocessing/using-the-data-grid-component.md b/...stration/using-the-data-grid-component.md → ...ocessing/using-the-data-grid-component.md
diff --git a/...lugins/administration/using-vuex-state.md → ...a-handling-processing/using-vuex-state.md b/...lugins/administration/using-vuex-state.md → ...a-handling-processing/using-vuex-state.md
diff --git a/...gins/plugins/administration/add-mixins.md → ...istration/mixins-directives/add-mixins.md b/...gins/plugins/administration/add-mixins.md → ...istration/mixins-directives/add-mixins.md
diff --git a/...ugins/administration/adding-directives.md → ...on/mixins-directives/adding-directives.md b/...ugins/administration/adding-directives.md → ...on/mixins-directives/adding-directives.md
diff --git a/...ns/plugins/administration/using-mixins.md → ...tration/mixins-directives/using-mixins.md b/...ns/plugins/administration/using-mixins.md → ...tration/mixins-directives/using-mixins.md
diff --git a/...ns/administration/add-custom-component.md → ...ponent-management/add-custom-component.md b/...ns/administration/add-custom-component.md → ...ponent-management/add-custom-component.md
diff --git a/...lugins/administration/add-custom-field.md → ...-component-management/add-custom-field.md b/...lugins/administration/add-custom-field.md → ...-component-management/add-custom-field.md
diff --git a/...ugins/administration/add-custom-module.md → ...component-management/add-custom-module.md b/...ugins/administration/add-custom-module.md → ...component-management/add-custom-module.md
diff --git a/.../administration/customizing-components.md → ...nent-management/customizing-components.md b/.../administration/customizing-components.md → ...nent-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/...ins/administration/customizing-modules.md → ...mponent-management/customizing-modules.md b/...ins/administration/customizing-modules.md → ...mponent-management/customizing-modules.md
diff --git a/...s/administration/using-base-components.md → ...onent-management/using-base-components.md b/...s/administration/using-base-components.md → ...onent-management/using-base-components.md
diff --git a/...s/plugins/administration/add-acl-rules.md → ...rmissions-error-handling/add-acl-rules.md b/...s/plugins/administration/add-acl-rules.md → ...rmissions-error-handling/add-acl-rules.md
diff --git a/...gins/administration/add-error-handling.md → ...ions-error-handling/add-error-handling.md b/...gins/administration/add-error-handling.md → ...ions-error-handling/add-error-handling.md
diff --git a/...lugins/administration/add-custom-route.md → ...on/routing-navigation/add-custom-route.md b/...lugins/administration/add-custom-route.md → ...on/routing-navigation/add-custom-route.md
diff --git a/.../plugins/administration/add-menu-entry.md → ...tion/routing-navigation/add-menu-entry.md b/.../plugins/administration/add-menu-entry.md → ...tion/routing-navigation/add-menu-entry.md
diff --git a/...ins/plugins/administration/add-new-tab.md → ...tration/routing-navigation/add-new-tab.md b/...ins/plugins/administration/add-new-tab.md → ...tration/routing-navigation/add-new-tab.md
diff --git a/...ugins/administration/overriding-routes.md → ...n/routing-navigation/overriding-routes.md b/...ugins/administration/overriding-routes.md → ...n/routing-navigation/overriding-routes.md
diff --git a/...gins/administration/add-custom-service.md → .../services-utilities/add-custom-service.md b/...gins/administration/add-custom-service.md → .../services-utilities/add-custom-service.md
diff --git a/...gins/plugins/administration/add-filter.md → ...stration/services-utilities/add-filter.md b/...gins/plugins/administration/add-filter.md → ...stration/services-utilities/add-filter.md
diff --git a/...gins/administration/extending-services.md → .../services-utilities/extending-services.md b/...gins/administration/extending-services.md → .../services-utilities/extending-services.md
diff --git a/...gins/administration/injecting-services.md → .../services-utilities/injecting-services.md b/...gins/administration/injecting-services.md → .../services-utilities/injecting-services.md
diff --git a/...ns/administration/the-sanitizer-helper.md → ...ervices-utilities/the-sanitizer-helper.md b/...ns/administration/the-sanitizer-helper.md → ...ervices-utilities/the-sanitizer-helper.md
diff --git a/...ns/plugins/administration/using-filter.md → ...ration/services-utilities/using-filter.md b/...ns/plugins/administration/using-filter.md → ...ration/services-utilities/using-filter.md
diff --git a/...ins/plugins/administration/using-utils.md → ...tration/services-utilities/using-utils.md b/...ins/plugins/administration/using-utils.md → ...tration/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
@@ -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 `<shopwareRoot>/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 `<shopwareRoot>/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 `<shopwareRoot>/src/Administration/Resources/app/administration/src/index.vite.ts`.
+
+### Building extensions
+
+The script responsible for building all extensions is located at `<shopwareRoot>/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 `<shopwareRoot>/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
+<script setup>
+import { ref } from 'vue';
+</script>
+
+// To this
+<script setup>
+const { ref } = window['Shopware']['Vue'];
+</script>
+```
+
+### 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.