From 7172297f823cfa74d04eaece5f6da9f65df31b1c Mon Sep 17 00:00:00 2001 From: LApple Date: Tue, 24 Feb 2026 09:31:18 +0100 Subject: [PATCH 01/43] adds upgrade guide and apidocs --- concepts/api/admin-api.md | 12 --- concepts/api/index.md | 14 ---- concepts/api/store-api.md | 35 -------- concepts/apis/index.md | 50 ++++++++++++ .../architecture/storefront-concept.md | 18 ++++- .../administration/index.md | 17 ++++ .../administration}/meteor-components.md | 0 .../administration}/pinia.md | 0 .../administration}/vite.md | 0 .../administration}/vue-migration-build.md | 0 .../administration}/vue-native.md | 0 .../administration/vue3.md | 2 +- .../extension-translation.md | 8 +- guides/upgrades-migrations/index.md | 80 +++++++++++++++++++ .../language-pack-migration.md | 24 ++---- guides/upgrades-migrations/upgrade-shopware | 70 ++++++++++++++++ .../upgrades/administration/index.md | 10 --- resources/references/upgrades/core/index.md | 10 --- .../upgrades/core/translation/index.md | 10 --- resources/references/upgrades/index.md | 11 --- 20 files changed, 244 insertions(+), 127 deletions(-) delete mode 100644 concepts/api/admin-api.md delete mode 100644 concepts/api/index.md delete mode 100644 concepts/api/store-api.md create mode 100644 concepts/apis/index.md create mode 100644 guides/upgrades-migrations/administration/index.md rename guides/{plugins/plugins/administration/system-updates => upgrades-migrations/administration}/meteor-components.md (100%) rename guides/{plugins/plugins/administration/system-updates => upgrades-migrations/administration}/pinia.md (100%) rename guides/{plugins/plugins/administration/system-updates => upgrades-migrations/administration}/vite.md (100%) rename guides/{plugins/plugins/administration/system-updates => upgrades-migrations/administration}/vue-migration-build.md (100%) rename guides/{plugins/plugins/administration/system-updates => upgrades-migrations/administration}/vue-native.md (100%) rename {resources/references/upgrades => guides/upgrades-migrations}/administration/vue3.md (99%) rename {resources/references/upgrades/core/translation => guides/upgrades-migrations}/extension-translation.md (94%) create mode 100644 guides/upgrades-migrations/index.md rename {resources/references/upgrades/core/translation => guides/upgrades-migrations}/language-pack-migration.md (67%) create mode 100644 guides/upgrades-migrations/upgrade-shopware delete mode 100644 resources/references/upgrades/administration/index.md delete mode 100644 resources/references/upgrades/core/index.md delete mode 100644 resources/references/upgrades/core/translation/index.md delete mode 100644 resources/references/upgrades/index.md diff --git a/concepts/api/admin-api.md b/concepts/api/admin-api.md deleted file mode 100644 index 6bb1cb3553..0000000000 --- a/concepts/api/admin-api.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -nav: - title: Admin API - position: 20 - ---- - -# Admin API - -The Admin API provides CRUD operations for every entity within Shopware and is used to build integrations with external systems. - -For more information, refer to the [Guides section](../../guides/integrations-api/index.md). diff --git a/concepts/api/index.md b/concepts/api/index.md deleted file mode 100644 index c963ca36aa..0000000000 --- a/concepts/api/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -nav: - title: API - position: 40 - ---- - -# API - -The Shopware API allows developers to interact with and integrate Shopware with other systems and applications. It provides a set of services that enable developers to perform various operations, such as managing products, customers, orders, and shopping carts.The API supports both read and write operations, allowing developers to retrieve information from Shopware and make modifications or additions to the e-commerce platform. By leveraging the Shopware API, developers can extend the functionality of Shopware, integrate it with external systems, and create seamless experiences for managing and operating online stores. - -Shopware supports two major functional APIs: the Store API and the Admin API. These APIs serve different purposes. The Store API is designed to interact with the front-end or storefront of a Shopware online store while the Admin API is intended for administrative operations related to managing the back-end of the Shopware platform. - -The API documentation provides details on the available endpoints, request/response formats, authentication mechanisms, and data structures. It supports different authentication methods, including token-based authentication and OAuth 2.0, to ensure secure communication between the API client and the Shopware platform. diff --git a/concepts/api/store-api.md b/concepts/api/store-api.md deleted file mode 100644 index 4fd48be32d..0000000000 --- a/concepts/api/store-api.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -nav: - title: Store API - position: 10 - ---- - -# Store API - -Every interaction between the store and a customer can be modeled using the Store API. It serves as a normalized layer or an interface to communicate between customer-facing applications and the Shopware Core. It can be used to build custom frontends like SPAs, native apps, or simple catalog apps. It doesn't matter what you want to build as long as you are able to consume a JSON API via HTTP. - -![Data and logic flow in Shopware 6 \(top to bottom and vice versa\)](../../assets/concepts-api-storeApiLogic.svg) - -Whenever additional logic is added to Shopware, the method of the corresponding service is exposed via a dedicated HTTP route. At the same time, it can be programmatically used to provide data to a controller or other services in the stack. This way, you can ensure that there is always common logic between the API and the Storefront and almost no redundancy. It also allows us to build core functionalities into our Storefront without compromising support for our API consumers. - -## Extensibility - -Using plugins, you can add custom routes to the Store API \(as well as any other routes\) and also register custom services. We don't force developers to provide API coverage for their functionalities. However, if you want to support headless applications, ensure that your plugin provides its functionalities through dedicated routes. - - - -## Store API and the traditional TWIG storefront - -When using the server-side rendered TWIG storefront, the Store API is not used. -Instead, the storefront uses custom [storefront controllers](../../guides/plugins/plugins/storefront/add-custom-controller.md) which internally use the Store API to fetch data. - -The storefront controllers are optimized for the usage in our TWIG storefront. And the biggest difference is the way that authentication and authorization are handled. -As the Store-API is a proper REST API, the main design is stateless, which means authentication info needs to be provided via the request headers in form of the `sw-context-token`. -The storefront relies on the session to store the authentication info, that way you do not have to handle the authentication manually with every request. - -## What next? - -* To start working with the Store API, check out our [Quick Start guide](https://shopware.stoplight.io/docs/store-api/38777d33d92dc-quick-start-guide) and explore all endpoints in our reference guide. - -* An interesting project based on the Store API is [Composable Frontends](../../../frontends/). diff --git a/concepts/apis/index.md b/concepts/apis/index.md new file mode 100644 index 0000000000..888c2358bf --- /dev/null +++ b/concepts/apis/index.md @@ -0,0 +1,50 @@ +--- +nav: + title: APIs + position: 40 + +--- + +# APIs + +Shopware exposes HTTP-based APIs that allow external systems and custom applications to interact with the platform. + +Two functional APIs are available, each representing a different integration surface: + +* **Store API**: customer-facing interactions +* **Admin API**: administrative and system-level operations + +Both APIs use HTTP, exchange structured JSON payloads, and require authenticated access. While they serve different purposes within the platform, they share some underlying design principles and structural patterns: + +- Search criteria abstraction for filtering, sorting, and pagination +- Structured JSON request/response bodies +- Versioned endpoints +- Header-based contextual behavior + +These patterns form the foundation of integration development. + +## Store API + +The Store API represents the customer-facing surface of Shopware. It is designed for storefront/frontend-related interactions such as product browsing, cart handling, checkout, and customer account management. It exposes only data that is relevant and safe for frontend use and supports both anonymous and authenticated customers. + +The Store API acts as a normalized interface layer between customer-facing applications and the Shopware Core. It enables headless frontends (such as SPAs or native apps) to consume Shopware functionality via JSON over HTTP. Core business logic is exposed through HTTP routes, ensuring that the Storefront and API consumers rely on the same underlying services. + +Authoritative endpoint documentation: + + + +* An interesting project based on the Store API is [Composable Frontends](../../../frontends/). + +## Admin API + +The Admin API represents the administrative and integration surface of Shopware. It enables structured access to core business entities such as products, orders, customers, media, and configurations. It is intended for backend integrations, automation, data synchronization, and system-to-system communication. + +These integrations typically involve structured data exchange, synchronization, imports, exports, and notifications. They prioritize consistency, error handling, validation, and transactional integrity. Performance is also important in terms of high data loads rather than fast response times. + +The Admin API provides CRUD operations for every entity within Shopware and is used to build integrations with external systems. + +Authoritative endpoint documentation: + + + +For details on endpoints, authentication methods (including token-based authentication and OAuth 2.0), schemas, and request formats, always refer to the Stoplight documentation. diff --git a/concepts/framework/architecture/storefront-concept.md b/concepts/framework/architecture/storefront-concept.md index 3e08bab3c6..5bd276b6ba 100644 --- a/concepts/framework/architecture/storefront-concept.md +++ b/concepts/framework/architecture/storefront-concept.md @@ -32,7 +32,23 @@ The main concerns that the Storefront component has are listed below. Furthermor Contrary to API calls that result in single resource data, a whole page in the Storefront displays multiple different data sets on a single page. Think of partials, which lead to a single page being displayed. Imagine a page that displays the order overview in the customer account environment. There are partials that are generic and will be displayed on almost every Page. These partials include - for example, Header and Footer information wrapped into a `GenericPage` as `Pagelets` \(`HeaderPagelet`, `FooterPagelet`\). This very generic Page will later be enriched with the specific information you want to display through a separate loader \(e.g. a list of orders\). -To achieve getting information from a specific resource, the Storefront's second concern is to map requests to the Core. Internally, the Storefront makes use of the [Store API](../../api/store-api) routes to enrich the Page with additional information, e.g., a list of orders, which is being fetched through the order route. Once all needed information is added to the Page, the corresponding page loader returns the Page to a Storefront controller. +To obtain information from a specific resource, the Storefront's second concern is to map requests to the Core. Internally, the Storefront makes use of the [Store API](https://shopware.stoplight.io/docs/store-api/38777d33d92dc-quick-start-guide) routes to enrich the Page with additional information, e.g., a list of orders, which is being fetched through the order route. + +![Data and logic flow in Shopware 6 \(top to bottom and vice versa\)](../../assets/concepts-api-storeApiLogic.svg) + +Once all needed information is added to the Page, the corresponding page loader returns the Page to a Storefront controller. + +### Store API and the traditional TWIG storefront + +In the traditional server-side rendered Twig storefront, the Store API is not called directly by the browser. Instead, custom storefront controllers internally use the Store API to fetch data from the Core. + +The Store API is stateless and expects authentication information via request headers (for example the `sw-context-token`). In contrast, the traditional storefront relies on session-based authentication, so authentication does not need to be handled manually on every request. + +### Store API and the traditional Twig storefront + +In the traditional server-side rendered Twig storefront, the Store API is not called directly by the browser. Instead, custom storefront controllers internally use the Store API to fetch data from the Core. + +The Store API is stateless and expects authentication information via request headers (for example the `sw-context-token`). In contrast, the traditional storefront relies on session-based authentication, so authentication does not need to be handled manually on every request. Contrary to the Core, which can almost completely omit templating in favor of JSON responses, the Storefront contains a rich set of Twig templates to display a fully functional shop. Another concern of the Storefront is to provide templating with Twig. The page object, which was enriched beforehand, will later be passed to a specific Twig page template throughout a controller. A more detailed look into an example can be found in [Composite data handling](storefront-concept#composite-data-handling). diff --git a/guides/upgrades-migrations/administration/index.md b/guides/upgrades-migrations/administration/index.md new file mode 100644 index 0000000000..4fb462c566 --- /dev/null +++ b/guides/upgrades-migrations/administration/index.md @@ -0,0 +1,17 @@ +--- +nav: + title: Administration + position: 10 + +--- + +# Administration + +These guides cover upcoming architectural changes and migration paths affecting Administration extensions. Use them to prepare plugins for major system transitions: + +* [Vue 3 migration](./vue3) +* [Meteor components](./meteor-components) +* [Pinia migration](./pinia) +* [Vite migration](./vite) +* [Vue migration build removal](./vue-migration-build) +* [Native Vue implementation](./vue-native) diff --git a/guides/plugins/plugins/administration/system-updates/meteor-components.md b/guides/upgrades-migrations/administration/meteor-components.md similarity index 100% rename from guides/plugins/plugins/administration/system-updates/meteor-components.md rename to guides/upgrades-migrations/administration/meteor-components.md diff --git a/guides/plugins/plugins/administration/system-updates/pinia.md b/guides/upgrades-migrations/administration/pinia.md similarity index 100% rename from guides/plugins/plugins/administration/system-updates/pinia.md rename to guides/upgrades-migrations/administration/pinia.md diff --git a/guides/plugins/plugins/administration/system-updates/vite.md b/guides/upgrades-migrations/administration/vite.md similarity index 100% rename from guides/plugins/plugins/administration/system-updates/vite.md rename to guides/upgrades-migrations/administration/vite.md diff --git a/guides/plugins/plugins/administration/system-updates/vue-migration-build.md b/guides/upgrades-migrations/administration/vue-migration-build.md similarity index 100% rename from guides/plugins/plugins/administration/system-updates/vue-migration-build.md rename to guides/upgrades-migrations/administration/vue-migration-build.md diff --git a/guides/plugins/plugins/administration/system-updates/vue-native.md b/guides/upgrades-migrations/administration/vue-native.md similarity index 100% rename from guides/plugins/plugins/administration/system-updates/vue-native.md rename to guides/upgrades-migrations/administration/vue-native.md diff --git a/resources/references/upgrades/administration/vue3.md b/guides/upgrades-migrations/administration/vue3.md similarity index 99% rename from resources/references/upgrades/administration/vue3.md rename to guides/upgrades-migrations/administration/vue3.md index 4fcb3c1dfb..8c3d8fa841 100644 --- a/resources/references/upgrades/administration/vue3.md +++ b/guides/upgrades-migrations/administration/vue3.md @@ -5,7 +5,7 @@ nav: --- -# Vue 3 upgrade +# Vue 3 Upgrade ## Introduction diff --git a/resources/references/upgrades/core/translation/extension-translation.md b/guides/upgrades-migrations/extension-translation.md similarity index 94% rename from resources/references/upgrades/core/translation/extension-translation.md rename to guides/upgrades-migrations/extension-translation.md index ff25abbddd..3c1cb1bf6d 100644 --- a/resources/references/upgrades/core/translation/extension-translation.md +++ b/guides/upgrades-migrations/extension-translation.md @@ -23,10 +23,10 @@ The snippet loading system now follows this resolution order: When a translation key is requested, Shopware will: -- First check the specific country variant (e.g., `es-AR`) -- If not found, check the base language (e.g., `es`) -- If not found, the legacy fallback will be checked (`en-GB`) -- Finally, fall back to `en` if still not found +* First check the specific country variant (e.g., `es-AR`) +* If not found, check the base language (e.g., `es`) +* If not found, the legacy fallback will be checked (`en-GB`) +* Finally, fall back to `en` if still not found **Result**: ~90% reduction in duplicate translations while maintaining full functionality. diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md new file mode 100644 index 0000000000..c227072cb4 --- /dev/null +++ b/guides/upgrades-migrations/index.md @@ -0,0 +1,80 @@ +--- +nav: + title: Upgrades and Migrations + position: 10 + +--- + +# Version Upgrades and Migrations + +This section covers version-based upgrades and required migration effort for Shopware core and extensions. When upgrading to a new minor or major Shopware version, review it to understand breaking changes, required adjustments, and compatibility requirements. + +## Scope of this section + +Upgrades typically fall into one of these categories: + +* **Core**: Framework-level changes, data abstraction layer (DAL) updates, APIs, feature removals, and backend behavior. +* **[Administration](administration/index.md)**: frontend framework upgrades, Vue upgrades, breaking changes. +* **Translations**: [Extension translation](extension-translation), [Language pack migration](./language-pack-migration). +* **Extensions**: Version compatibility and required refactorings. + +:::info +Administration upgrades (Vue, Pinia, Vite, Meteor) may require major plugin version bumps. +::: + +## Upgrade strategy for extension developers + +To reduce long-term upgrade cost: + +* Avoid internal APIs and undocumented features +* Avoid unstable Admin patterns (`this.$parent`, prop mutation, Vue internals) +* Keep dependencies aligned with Shopware core +* Maintain automated test coverage +* Keep database migrations idempotent +* Track deprecations continuously—do not batch them + +For general development best practices that reduce upgrade friction, see the [Development guide](../development/index.md). + +## Typical upgrade workflow + +When targeting a new Shopware version: + +1. Review [release notes](https://www.shopware.com/de/changelog/) and UPGRADE files +2. Check breaking changes per layer (Core / Admin / Translations) +3. Validate extension compatibility +4. Apply required migrations +5. Rebuild Admin/Storefront assets if needed +6. Test critical flows +7. Update extension versions if required + +## Extension responsibilities + +### Custom projects + +* Follow the ([Performing updates guide](../hosting/installation-updates/performing-updates.md)) to stage, test, and execute upgrades in order. +* Review changelogs/UPGRADE files per release. +* Script data migrations and cache warmups. +* Use feature toggles or maintenance mode to decouple risky changes from the deploy moment. + +### Custom plugins + +* Provide migration code for schema/config changes. +* Ship defaults that work on older core versions until you deliberately drop support. +* Test against the target Shopware version matrix before rollout; note breaking changes in the plugin README. + +### Store plugins + +* Align Store metadata (compatibility range, changelog) with the tested core versions; refuse installation on unsupported versions. +* Run Shopware Store validation on the new build before submission ([Store submission via CLI](../../products/cli/shopware-account-commands/releasing-extension-to-shopware-store.md)). +* Communicate BC breaks explicitly. +* Prefer additive changes and feature flags to keep existing shops stable. + +### Apps + +* Version manifests carefully. Broaden compatibility only after testing, and narrow it when deprecations apply. +* Keep webhook/action handlers tolerant to new fields and events. Avoid hard coupling to specific core patch behavior. +* Document required scopes/permissions per version and avoid removing scopes without a migration path. + +## Next steps + +For the operational update procedure, continue with [Update Shopware](update-shopware). diff --git a/resources/references/upgrades/core/translation/language-pack-migration.md b/guides/upgrades-migrations/language-pack-migration.md similarity index 67% rename from resources/references/upgrades/core/translation/language-pack-migration.md rename to guides/upgrades-migrations/language-pack-migration.md index bc4c3e92dc..6ebca5ca3d 100644 --- a/resources/references/upgrades/core/translation/language-pack-migration.md +++ b/guides/upgrades-migrations/language-pack-migration.md @@ -39,7 +39,7 @@ Starting with Shopware **6.7.3.0**, translations are managed directly in Shopwar - Nothing changes. - To install additional languages, use the CLI command: -```bash +```bash bin/console translation:install --locales ``` @@ -55,16 +55,10 @@ Example: `bin/console translation:install --locales it-IT,fr-FR` will install It 2. The command uses the **same source ([translate.shopware.com][shopware-translations])** as the [Language Pack plugin][language-pack-plugin] but is updated more frequently. So it's essentially identical – or even more up to date! -3. Make sure that all languages you need are **active** in the Administration: `Settings → Languages` -4. Create base snippet sets for used languages - - If you're on Shopware **6.7.7.0** or later, this is done automatically. - - If you're on Shopware **6.7.6.0** or earlier, for each language in use, create a base snippet, e.g. `BASE en-US` for English (US). -5. Change all sales channel domains to use the base snippet sets. - - If you're on Language Pack **5.37.1** or later, this is done automatically. - - If you're on Language Pack **5.37.0** or earlier, open each sales channel, scroll down to the domains and change the - snippet set from `LanguagePack` to `BASE`, e.g.: `LanguagePack en-US` to `BASE en-US`. -6. It is recommended to uninstall and remove the Language Pack plugin after `translation:install` succeeded for all locales. - Your **custom snippets** created in the snippet module remain intact since they are saved in the database. +3. You can safely uninstall and remove the Language Pack plugin. Your **custom snippets** created in the Snippet module + remain intact since they are saved in the database. +4. Make sure that all languages you need are **active** in the Administration: + `Settings → Languages` ## New installations @@ -76,14 +70,6 @@ Example: `bin/console translation:install --locales it-IT,fr-FR` will install It - Additional details about the new translation handling are available in the [integrated language handling][translation-system] guide. -## Common problems and troubleshooting - -### Can't remove Language Pack: a foreign key constraint fails (\`shopware\`.\`sales_channel_domain\`… - -Starting with **Shopware 6.7.7.0** and **Language Pack 5.37.1**, the migration process was improved. If you encounter this issue, -please update Shopware to >= 6.7.7.0, Language Pack to >= 5.37.1, remove the translation files created from running the -command and run the command again. Or follow the updated migration guide. - [translation-system]: ../../../../../concepts/translations/built-in-translation-system.md [language-pack-plugin]: https://store.shopware.com/en/swag338126230916f/shopware-language-pack.html [shopware-translations]: https://translate.shopware.com diff --git a/guides/upgrades-migrations/upgrade-shopware b/guides/upgrades-migrations/upgrade-shopware new file mode 100644 index 0000000000..4cfcc96d2d --- /dev/null +++ b/guides/upgrades-migrations/upgrade-shopware @@ -0,0 +1,70 @@ +--- +nav: + title: Update Shopware + position: 10 +--- + +# Update Shopware + +This guide explains how to update an existing Shopware installation using Composer. + +For maintaining custom plugins or apps, review the [Upgrades and Migrations](../upgrades-and-migrations/index.md) guide before performing updates. + +## Standard update process + +Shopware updates must be executed via Composer. + +### 1. Enable maintenance mode + +Prepare the system for update: + +```bash +bin/console system:update:prepare +``` + +This enables maintenance mode and prepares the update process. + +### 2. Update Composer dependencies + +Update all Composer packages without executing scripts: + +```bash +composer update --no-scripts +``` + +The `--no-scripts` flag instructs Composer to avoid running any scripts that may reference Shopware CLI commands. These commands will only work after updated recipes are installed. + +### 3. Update Symfony recipes (optional but recommended) + +To force-update all configuration files managed by Symfony Flex: + +```bash +composer recipes:update +``` + +Review changes carefully before committing them. + +### 4. Finalize the update + +Disable maintenance mode and complete the update: + +```bash +bin/console system:update:finish +``` + +## Operational best practices + +* Automate pre-upgrade checks (PHP/DB versions, extensions, disk space). +* Always test upgrades on staging with production-like data. +* Keep verified database backups and a recovery plan. +* Review changelogs and UPGRADE files before applying changes. +* Track deprecations early and use official tooling (Rector, Administration codemods referenced in [Performing updates](../hosting/installation-updates/performing-updates.md)) to reduce manual work. +* Avoid skipping major versions. +* Commit the `composer.lock` file. +* Run post-upgrade smoke tests. + +## After the update + +* Clear caches if necessary +* Rebuild Administration and Storefront assets if required +* Test critical business flows (checkout, login, API integrations) diff --git a/resources/references/upgrades/administration/index.md b/resources/references/upgrades/administration/index.md deleted file mode 100644 index ce7b1d6f0a..0000000000 --- a/resources/references/upgrades/administration/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -nav: - title: Administration - position: 10 - ---- - -# Administration - -This section contains all upgrade guides related to the Shopware Administration. diff --git a/resources/references/upgrades/core/index.md b/resources/references/upgrades/core/index.md deleted file mode 100644 index e5d404a66e..0000000000 --- a/resources/references/upgrades/core/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -nav: - title: Core - position: 20 - ---- - -# Core upgrade and migration guides - -This section contains all upgrade and migration guides related to the Shopware Core. diff --git a/resources/references/upgrades/core/translation/index.md b/resources/references/upgrades/core/translation/index.md deleted file mode 100644 index 98cfc5a4e8..0000000000 --- a/resources/references/upgrades/core/translation/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -nav: - title: Translation - position: 10 - ---- - -# Update And Migration Guides For Translations In The Shopware Core - -This section contains all upgrade and migration guides related to translations in the Shopware Core. diff --git a/resources/references/upgrades/index.md b/resources/references/upgrades/index.md deleted file mode 100644 index 023adeb784..0000000000 --- a/resources/references/upgrades/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -nav: - title: Upgrades and Migrations - position: 50 - ---- - -# Upgrades and Migrations - -Software projects typically undergo changes and upgrades, for Shopware this is not different. -This section provides you with comprehensive update guides for specific technical changes. From 84995c5689019486145994d6bb4cb03ed3ea4b68 Mon Sep 17 00:00:00 2001 From: somethings Date: Tue, 24 Feb 2026 09:38:46 +0100 Subject: [PATCH 02/43] Update index.md --- concepts/apis/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/concepts/apis/index.md b/concepts/apis/index.md index 888c2358bf..bf4e948a8f 100644 --- a/concepts/apis/index.md +++ b/concepts/apis/index.md @@ -16,10 +16,10 @@ Two functional APIs are available, each representing a different integration sur Both APIs use HTTP, exchange structured JSON payloads, and require authenticated access. While they serve different purposes within the platform, they share some underlying design principles and structural patterns: -- Search criteria abstraction for filtering, sorting, and pagination -- Structured JSON request/response bodies -- Versioned endpoints -- Header-based contextual behavior +* Search criteria abstraction for filtering, sorting, and pagination +* Structured JSON request/response bodies +* Versioned endpoints +* Header-based contextual behavior These patterns form the foundation of integration development. From 33d1d6038486d0e0e10a669808e7d29c3938867f Mon Sep 17 00:00:00 2001 From: somethings Date: Tue, 24 Feb 2026 09:42:18 +0100 Subject: [PATCH 03/43] Update index.md --- guides/upgrades-migrations/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md index c227072cb4..684b49181c 100644 --- a/guides/upgrades-migrations/index.md +++ b/guides/upgrades-migrations/index.md @@ -53,7 +53,7 @@ When targeting a new Shopware version: * Follow the ([Performing updates guide](../hosting/installation-updates/performing-updates.md)) to stage, test, and execute upgrades in order. * Review changelogs/UPGRADE files per release. -* Script data migrations and cache warmups. +* Script data migrations and cache warm-ups. * Use feature toggles or maintenance mode to decouple risky changes from the deploy moment. ### Custom plugins From 15d132b528fcfb5b55fd95a827a29ff11a5926c6 Mon Sep 17 00:00:00 2001 From: sushmangupta Date: Thu, 26 Feb 2026 10:56:04 +0100 Subject: [PATCH 04/43] Additional info --- concepts/framework/architecture/index.md | 104 +++++++++++++++++- .../{upgrade-shopware => upgrade-shopware.md} | 2 +- 2 files changed, 103 insertions(+), 3 deletions(-) rename guides/upgrades-migrations/{upgrade-shopware => upgrade-shopware.md} (95%) diff --git a/concepts/framework/architecture/index.md b/concepts/framework/architecture/index.md index 35e8b3701a..1eb48d92e2 100644 --- a/concepts/framework/architecture/index.md +++ b/concepts/framework/architecture/index.md @@ -5,6 +5,106 @@ nav: --- -# Architecture +# Shopware Architecture -On a high level, Shopware consists of multiple modules that separate the entire code base into logical units. Some modules are independent, and some depend on others. +Shopware follows a modular, API-first architecture built on top of Symfony and modern frontend technologies. The platform separates concerns into clearly defined layers, allowing storefront experiences, administrative tooling, and core business logic to evolve independently while sharing a common backend foundation. + +At a high level, the system consists of three primary domains: + +* **Core** — the backend foundation containing business logic, data abstraction, APIs, and extension mechanisms. +* **Storefront** — the customer-facing presentation layer responsible for rendering sales channels and interacting with the Store API. +* **Administration** — the management interface used by merchants and operators to configure, manage, and operate the platform. + +These domains are unified through a shared API layer and a consistent plugin system, enabling extensibility without tightly coupling features to presentation layers. + +## Architectural principles + +The Shopware architecture is guided by several core principles: + +* **API-first design** — all functionality is exposed via APIs, enabling headless and composable commerce scenarios. +* **Separation of concerns** — frontend experiences (storefront/admin) are decoupled from backend logic. +* **Extensibility** — plugins integrate through events, services, and extension points rather than modifying core code. +* **Asynchronous processing** — background tasks (indexing, messaging, integrations) are handled via message queues and workers. +* **Domain-driven structure** — business logic is organized around commerce domains rather than UI features. + +## Core components + +The architecture centers around the Shopware Core, which provides: + +* Data Abstraction Layer (DAL) for database interaction +* Business services and domain logic +* Sales Channel and Store APIs +* Plugin and event system +* Messaging and scheduled task infrastructure + +The Storefront and Administration layers consume these services rather than duplicating logic, ensuring consistency across channels. + +## Architectural overview + +High-level architectural overview of Shopware’s core system layers and supporting infrastructure. + +```mermaid +flowchart TB + %% Entry + U[User (Customer / Admin)] -->|HTTPS| RP[Reverse Proxy / Load Balancer] + + %% Application boundary + subgraph SW[Shopware 6 Application] + direction TB + + %% Top-level modules + subgraph CORE[Core] + direction TB + DAL[Data Abstraction Layer (DAL)] + BL[Business Logic / Services] + API[Sales Channel API + Store API] + PLUG[Plugin System + Events] + SCHED[Scheduled Tasks] + MESS[Symfony Messenger (Async)] + end + + subgraph ADMIN[Administration] + direction TB + ADMUI[Admin UI (Vue)] + ADMAPI[Admin API (ACL / AuthZ)] + BUILDADM[Build Tooling (npm/webpack)] + ADMUI --> ADMAPI + end + + subgraph STOREFRONT[Storefront] + direction TB + SFSSR[Storefront (Twig / Symfony Controllers)] + SFAPI[Store API / Sales Channel API Client] + BUILDSF[Build Tooling (npm/webpack)] + SFSSR --> SFAPI + end + + %% Internal interactions + ADMIN --> API + STOREFRONT --> API + API --> DAL + BL --> DAL + PLUG --> BL + SCHED --> MESS + BL --> MESS + end + + %% Infrastructure dependencies + DB[(MySQL / MariaDB)] <--> DAL + CACHE[(Redis: Cache / Sessions / Locks)] <--> SW + SEARCH[(Elasticsearch / OpenSearch)] <--> SW + FS[(Media Storage: Local FS / NFS / S3)] <--> SW + + %% Async processing + MQ[(Async Transport: Redis / RabbitMQ / DB)] <--> MESS + MESS --> W[Workers / Consumers] + W --> DB + W --> SEARCH + W --> FS + + %% External integrations + EXT[External Services\nPayment / Shipping / ERP / PIM / Tax / Email] <--> API + EXT <--> W + + RP --> SW +``` diff --git a/guides/upgrades-migrations/upgrade-shopware b/guides/upgrades-migrations/upgrade-shopware.md similarity index 95% rename from guides/upgrades-migrations/upgrade-shopware rename to guides/upgrades-migrations/upgrade-shopware.md index 4cfcc96d2d..2ef4eb0eef 100644 --- a/guides/upgrades-migrations/upgrade-shopware +++ b/guides/upgrades-migrations/upgrade-shopware.md @@ -8,7 +8,7 @@ nav: This guide explains how to update an existing Shopware installation using Composer. -For maintaining custom plugins or apps, review the [Upgrades and Migrations](../upgrades-and-migrations/index.md) guide before performing updates. +For maintaining custom plugins or apps, review the [Upgrades and Migrations](../upgrades-migrations/index.md) guide before performing updates. ## Standard update process From e1c97cb765be6db6875b77b994daca52218c169f Mon Sep 17 00:00:00 2001 From: somethings Date: Thu, 26 Feb 2026 11:17:22 +0100 Subject: [PATCH 05/43] Update concepts/apis/index.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- concepts/apis/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/concepts/apis/index.md b/concepts/apis/index.md index bf4e948a8f..4ca36dd5d6 100644 --- a/concepts/apis/index.md +++ b/concepts/apis/index.md @@ -29,11 +29,11 @@ The Store API represents the customer-facing surface of Shopware. It is designed The Store API acts as a normalized interface layer between customer-facing applications and the Shopware Core. It enables headless frontends (such as SPAs or native apps) to consume Shopware functionality via JSON over HTTP. Core business logic is exposed through HTTP routes, ensuring that the Storefront and API consumers rely on the same underlying services. -Authoritative endpoint documentation: - +For details on endpoints, authentication methods, schemas, and request formats, always refer to the Store API documentation. -* An interesting project based on the Store API is [Composable Frontends](../../../frontends/). +Shopware provides [Composable Frontends](https://frontends.shopware.com/) + as a headless frontend implementation based on the Store API. ## Admin API From 6d4eecab5eb0f48d9deeeb9a4b48ce77fd67aedc Mon Sep 17 00:00:00 2001 From: somethings Date: Thu, 26 Feb 2026 11:17:47 +0100 Subject: [PATCH 06/43] Update concepts/apis/index.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- concepts/apis/index.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/concepts/apis/index.md b/concepts/apis/index.md index 4ca36dd5d6..83fe5484bf 100644 --- a/concepts/apis/index.md +++ b/concepts/apis/index.md @@ -43,8 +43,6 @@ These integrations typically involve structured data exchange, synchronization, The Admin API provides CRUD operations for every entity within Shopware and is used to build integrations with external systems. -Authoritative endpoint documentation: +For details on endpoints, authentication methods, schemas, and request formats, always refer to the Admin API documentation. - -For details on endpoints, authentication methods (including token-based authentication and OAuth 2.0), schemas, and request formats, always refer to the Stoplight documentation. From c778b157a0694a76be468638a015fd6b31b3c919 Mon Sep 17 00:00:00 2001 From: somethings Date: Thu, 26 Feb 2026 11:18:59 +0100 Subject: [PATCH 07/43] Update storefront-concept.md --- concepts/framework/architecture/storefront-concept.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/concepts/framework/architecture/storefront-concept.md b/concepts/framework/architecture/storefront-concept.md index 5bd276b6ba..7bdad8705b 100644 --- a/concepts/framework/architecture/storefront-concept.md +++ b/concepts/framework/architecture/storefront-concept.md @@ -38,12 +38,6 @@ To obtain information from a specific resource, the Storefront's second concern Once all needed information is added to the Page, the corresponding page loader returns the Page to a Storefront controller. -### Store API and the traditional TWIG storefront - -In the traditional server-side rendered Twig storefront, the Store API is not called directly by the browser. Instead, custom storefront controllers internally use the Store API to fetch data from the Core. - -The Store API is stateless and expects authentication information via request headers (for example the `sw-context-token`). In contrast, the traditional storefront relies on session-based authentication, so authentication does not need to be handled manually on every request. - ### Store API and the traditional Twig storefront In the traditional server-side rendered Twig storefront, the Store API is not called directly by the browser. Instead, custom storefront controllers internally use the Store API to fetch data from the Core. From 48f3a0cdaabdef6444e9e26f3c94f30991754236 Mon Sep 17 00:00:00 2001 From: somethings Date: Thu, 26 Feb 2026 11:19:58 +0100 Subject: [PATCH 08/43] Apply suggestion from @sushmangupta Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/upgrades-migrations/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md index 684b49181c..840672c4e6 100644 --- a/guides/upgrades-migrations/index.md +++ b/guides/upgrades-migrations/index.md @@ -19,7 +19,7 @@ Upgrades typically fall into one of these categories: * **Extensions**: Version compatibility and required refactorings. :::info -Administration upgrades (Vue, Pinia, Vite, Meteor) may require major plugin version bumps. +Administration framework upgrades (Vue, Pinia, Vite, Meteor) may introduce breaking changes requiring major version updates for affected plugins. ::: ## Upgrade strategy for extension developers From e7d903bd758935694f8e43d03e0dd48c3ec140c9 Mon Sep 17 00:00:00 2001 From: somethings Date: Thu, 26 Feb 2026 11:21:10 +0100 Subject: [PATCH 09/43] Update index.md --- guides/upgrades-migrations/index.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md index 840672c4e6..0a8d728d7e 100644 --- a/guides/upgrades-migrations/index.md +++ b/guides/upgrades-migrations/index.md @@ -33,8 +33,6 @@ To reduce long-term upgrade cost: * Keep database migrations idempotent * Track deprecations continuously—do not batch them -For general development best practices that reduce upgrade friction, see the [Development guide](../development/index.md). - ## Typical upgrade workflow When targeting a new Shopware version: From 238874734388ac170533f47309492e7ff39438a9 Mon Sep 17 00:00:00 2001 From: somethings Date: Thu, 26 Feb 2026 11:24:23 +0100 Subject: [PATCH 10/43] Update index.md --- guides/upgrades-migrations/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md index 0a8d728d7e..11af8e35cb 100644 --- a/guides/upgrades-migrations/index.md +++ b/guides/upgrades-migrations/index.md @@ -50,7 +50,7 @@ When targeting a new Shopware version: ### Custom projects * Follow the ([Performing updates guide](../hosting/installation-updates/performing-updates.md)) to stage, test, and execute upgrades in order. -* Review changelogs/UPGRADE files per release. +* Review [changelogs](https://github.com/shopware/shopware/tree/trunk/changelog) and UPGRADE files ([example](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.7.md)) per release. * Script data migrations and cache warm-ups. * Use feature toggles or maintenance mode to decouple risky changes from the deploy moment. From 16456bf0a9d95ba070e0fdcabee3f32d48c60277 Mon Sep 17 00:00:00 2001 From: somethings Date: Thu, 26 Feb 2026 11:28:16 +0100 Subject: [PATCH 11/43] Update index.md --- guides/upgrades-migrations/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md index 11af8e35cb..207d19f875 100644 --- a/guides/upgrades-migrations/index.md +++ b/guides/upgrades-migrations/index.md @@ -75,4 +75,4 @@ When targeting a new Shopware version: ## Next steps -For the operational update procedure, continue with [Update Shopware](update-shopware). +For the operational update procedure, continue with [Update Shopware](./update-shopware). From dc8d761268cf7f65fda10a6c4ae81097d8be0aeb Mon Sep 17 00:00:00 2001 From: somethings Date: Thu, 26 Feb 2026 11:29:04 +0100 Subject: [PATCH 12/43] Update index.md --- guides/upgrades-migrations/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md index 207d19f875..a7383d80b0 100644 --- a/guides/upgrades-migrations/index.md +++ b/guides/upgrades-migrations/index.md @@ -75,4 +75,4 @@ When targeting a new Shopware version: ## Next steps -For the operational update procedure, continue with [Update Shopware](./update-shopware). +For the operational update procedure, continue with [Upgrade Shopware](./upgrade-shopware). From 312d6c50a0d5f4c1cace3dfe4449661770199136 Mon Sep 17 00:00:00 2001 From: somethings Date: Thu, 26 Feb 2026 11:35:51 +0100 Subject: [PATCH 13/43] Update index.md --- guides/upgrades-migrations/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md index a7383d80b0..de333370cf 100644 --- a/guides/upgrades-migrations/index.md +++ b/guides/upgrades-migrations/index.md @@ -75,4 +75,4 @@ When targeting a new Shopware version: ## Next steps -For the operational update procedure, continue with [Upgrade Shopware](./upgrade-shopware). +For the operational update procedure, continue with [Upgrade Shopware](./upgrade-shopware.md). From 8f8b1cc97b02e479e774e12057001c482742c1c2 Mon Sep 17 00:00:00 2001 From: somethings Date: Thu, 26 Feb 2026 11:40:53 +0100 Subject: [PATCH 14/43] Update upgrade-shopware.md --- guides/upgrades-migrations/upgrade-shopware.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/upgrades-migrations/upgrade-shopware.md b/guides/upgrades-migrations/upgrade-shopware.md index 2ef4eb0eef..9b23923b70 100644 --- a/guides/upgrades-migrations/upgrade-shopware.md +++ b/guides/upgrades-migrations/upgrade-shopware.md @@ -1,10 +1,10 @@ --- nav: - title: Update Shopware + title: Upgrade Shopware position: 10 --- -# Update Shopware +# Upgrade Shopware This guide explains how to update an existing Shopware installation using Composer. From 4ecb86be5d7c52c0c544c56004486e7d385b1550 Mon Sep 17 00:00:00 2001 From: sushmangupta Date: Thu, 26 Feb 2026 12:10:32 +0100 Subject: [PATCH 15/43] Fix link --- concepts/framework/architecture/storefront-concept.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/concepts/framework/architecture/storefront-concept.md b/concepts/framework/architecture/storefront-concept.md index 7bdad8705b..fd03761ffa 100644 --- a/concepts/framework/architecture/storefront-concept.md +++ b/concepts/framework/architecture/storefront-concept.md @@ -34,7 +34,7 @@ Contrary to API calls that result in single resource data, a whole page in the S To obtain information from a specific resource, the Storefront's second concern is to map requests to the Core. Internally, the Storefront makes use of the [Store API](https://shopware.stoplight.io/docs/store-api/38777d33d92dc-quick-start-guide) routes to enrich the Page with additional information, e.g., a list of orders, which is being fetched through the order route. -![Data and logic flow in Shopware 6 \(top to bottom and vice versa\)](../../assets/concepts-api-storeApiLogic.svg) +![Data and logic flow in Shopware 6 \(top to bottom and vice versa\)](../../../assets/concepts-api-storeApiLogic.svg) Once all needed information is added to the Page, the corresponding page loader returns the Page to a Storefront controller. From 97c7e5e9d71015f3d6b431924e490c9b1e2dba83 Mon Sep 17 00:00:00 2001 From: sushmangupta Date: Thu, 26 Feb 2026 14:31:27 +0100 Subject: [PATCH 16/43] Language tool issue fix --- concepts/framework/architecture/index.md | 10 +++++----- guides/upgrades-migrations/index.md | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/concepts/framework/architecture/index.md b/concepts/framework/architecture/index.md index 1eb48d92e2..9683202559 100644 --- a/concepts/framework/architecture/index.md +++ b/concepts/framework/architecture/index.md @@ -60,7 +60,7 @@ flowchart TB API[Sales Channel API + Store API] PLUG[Plugin System + Events] SCHED[Scheduled Tasks] - MESS[Symfony Messenger (Async)] + MESSAGE[Symfony Messenger (Async)] end subgraph ADMIN[Administration] @@ -85,8 +85,8 @@ flowchart TB API --> DAL BL --> DAL PLUG --> BL - SCHED --> MESS - BL --> MESS + SCHED --> MESSAGE + BL --> MESSAGE end %% Infrastructure dependencies @@ -96,8 +96,8 @@ flowchart TB FS[(Media Storage: Local FS / NFS / S3)] <--> SW %% Async processing - MQ[(Async Transport: Redis / RabbitMQ / DB)] <--> MESS - MESS --> W[Workers / Consumers] + MQ[(Async Transport: Redis / RabbitMQ / DB)] <--> MESSAGE + MESSAGE --> W[Workers / Consumers] W --> DB W --> SEARCH W --> FS diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md index de333370cf..bf9a255e7b 100644 --- a/guides/upgrades-migrations/index.md +++ b/guides/upgrades-migrations/index.md @@ -52,7 +52,7 @@ When targeting a new Shopware version: * Follow the ([Performing updates guide](../hosting/installation-updates/performing-updates.md)) to stage, test, and execute upgrades in order. * Review [changelogs](https://github.com/shopware/shopware/tree/trunk/changelog) and UPGRADE files ([example](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.7.md)) per release. * Script data migrations and cache warm-ups. -* Use feature toggles or maintenance mode to decouple risky changes from the deploy moment. +* Use feature toggles or maintenance mode to decouple risky changes from the deployment. ### Custom plugins From 69d084962afbfa9474dd54d1c906507f927e0c31 Mon Sep 17 00:00:00 2001 From: sushmangupta Date: Thu, 26 Feb 2026 15:04:01 +0100 Subject: [PATCH 17/43] Fix api directory content --- concepts/api/admin-api.md | 18 +++++++++++++++ concepts/api/index.md | 24 ++++++++++++++++++++ concepts/api/store-api.md | 17 ++++++++++++++ concepts/apis/index.md | 48 --------------------------------------- 4 files changed, 59 insertions(+), 48 deletions(-) create mode 100644 concepts/api/admin-api.md create mode 100644 concepts/api/index.md create mode 100644 concepts/api/store-api.md delete mode 100644 concepts/apis/index.md diff --git a/concepts/api/admin-api.md b/concepts/api/admin-api.md new file mode 100644 index 0000000000..13657c23eb --- /dev/null +++ b/concepts/api/admin-api.md @@ -0,0 +1,18 @@ +--- +nav: + title: Admin API + position: 42 + +--- + +# Admin API + +The Admin API represents the administrative and integration surface of Shopware. It enables structured access to core business entities such as products, orders, customers, media, and configurations. It is intended for backend integrations, automation, data synchronization, and system-to-system communication. + +These integrations typically involve structured data exchange, synchronization, imports, exports, and notifications. They prioritize consistency, error handling, validation, and transactional integrity. Performance is also important in terms of high data loads rather than fast response times. + +The Admin API provides CRUD operations for every entity within Shopware and is used to build integrations with external systems. + +For details on endpoints, authentication methods, schemas, and request formats, always refer to the Admin API documentation. + + diff --git a/concepts/api/index.md b/concepts/api/index.md new file mode 100644 index 0000000000..ae453c8d8a --- /dev/null +++ b/concepts/api/index.md @@ -0,0 +1,24 @@ +--- +nav: + title: API + position: 40 + +--- + +# APIs + +Shopware exposes HTTP-based APIs that allow external systems and custom applications to interact with the platform. + +Two functional APIs are available, each representing a different integration surface: + +* **Store API**: customer-facing interactions +* **Admin API**: administrative and system-level operations + +Both APIs use HTTP, exchange structured JSON payloads, and require authenticated access. While they serve different purposes within the platform, they share some underlying design principles and structural patterns: + +* Search criteria abstraction for filtering, sorting, and pagination +* Structured JSON request/response bodies +* Versioned endpoints +* Header-based contextual behavior + +These patterns form the foundation of integration development. diff --git a/concepts/api/store-api.md b/concepts/api/store-api.md new file mode 100644 index 0000000000..2f4aa11317 --- /dev/null +++ b/concepts/api/store-api.md @@ -0,0 +1,17 @@ +--- +nav: + title: Store API + position: 41 + +--- + +# Store API + +The Store API represents the customer-facing surface of Shopware. It is designed for storefront/frontend-related interactions such as product browsing, cart handling, checkout, and customer account management. It exposes only data that is relevant and safe for frontend use and supports both anonymous and authenticated customers. + +The Store API acts as a normalized interface layer between customer-facing applications and the Shopware Core. It enables headless frontends (such as SPAs or native apps) to consume Shopware functionality via JSON over HTTP. Core business logic is exposed through HTTP routes, ensuring that the Storefront and API consumers rely on the same underlying services. + +For details on endpoints, authentication methods, schemas, and request formats, always refer to the Store API documentation. + + +Shopware provides [Composable Frontends](https://frontends.shopware.com/) as a headless frontend implementation based on the Store API. diff --git a/concepts/apis/index.md b/concepts/apis/index.md deleted file mode 100644 index 83fe5484bf..0000000000 --- a/concepts/apis/index.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -nav: - title: APIs - position: 40 - ---- - -# APIs - -Shopware exposes HTTP-based APIs that allow external systems and custom applications to interact with the platform. - -Two functional APIs are available, each representing a different integration surface: - -* **Store API**: customer-facing interactions -* **Admin API**: administrative and system-level operations - -Both APIs use HTTP, exchange structured JSON payloads, and require authenticated access. While they serve different purposes within the platform, they share some underlying design principles and structural patterns: - -* Search criteria abstraction for filtering, sorting, and pagination -* Structured JSON request/response bodies -* Versioned endpoints -* Header-based contextual behavior - -These patterns form the foundation of integration development. - -## Store API - -The Store API represents the customer-facing surface of Shopware. It is designed for storefront/frontend-related interactions such as product browsing, cart handling, checkout, and customer account management. It exposes only data that is relevant and safe for frontend use and supports both anonymous and authenticated customers. - -The Store API acts as a normalized interface layer between customer-facing applications and the Shopware Core. It enables headless frontends (such as SPAs or native apps) to consume Shopware functionality via JSON over HTTP. Core business logic is exposed through HTTP routes, ensuring that the Storefront and API consumers rely on the same underlying services. - -For details on endpoints, authentication methods, schemas, and request formats, always refer to the Store API documentation. - - -Shopware provides [Composable Frontends](https://frontends.shopware.com/) - as a headless frontend implementation based on the Store API. - -## Admin API - -The Admin API represents the administrative and integration surface of Shopware. It enables structured access to core business entities such as products, orders, customers, media, and configurations. It is intended for backend integrations, automation, data synchronization, and system-to-system communication. - -These integrations typically involve structured data exchange, synchronization, imports, exports, and notifications. They prioritize consistency, error handling, validation, and transactional integrity. Performance is also important in terms of high data loads rather than fast response times. - -The Admin API provides CRUD operations for every entity within Shopware and is used to build integrations with external systems. - -For details on endpoints, authentication methods, schemas, and request formats, always refer to the Admin API documentation. - - From 2bef0437e2328fd0fe9285f7aaa2c8875edc2bfd Mon Sep 17 00:00:00 2001 From: sushmangupta Date: Thu, 26 Feb 2026 15:44:41 +0100 Subject: [PATCH 18/43] Addition of Core Concept --- .../framework/architecture/core-concept.md | 92 +++++++++++++++++++ .../architecture/storefront-concept.md | 2 +- 2 files changed, 93 insertions(+), 1 deletion(-) create mode 100644 concepts/framework/architecture/core-concept.md diff --git a/concepts/framework/architecture/core-concept.md b/concepts/framework/architecture/core-concept.md new file mode 100644 index 0000000000..abbc91fa01 --- /dev/null +++ b/concepts/framework/architecture/core-concept.md @@ -0,0 +1,92 @@ +--- +nav: + title: Core + position: 25 +--- + +# Core + +The Core component represents the central backend foundation of Shopware. It provides the domain logic, data handling, APIs, and extensibility mechanisms that power both the Storefront and Administration components. + +Conceptually, the Core sits at the center of the platform architecture. While the Storefront and Administration provide user interfaces, the Core exposes functionality through structured APIs and services. All business logic, domain modeling, and system integrations are implemented within the Core to ensure consistency across different presentation layers. + +The Core is built on Symfony and follows modern backend design principles such as dependency injection, domain-driven organization, and event-based extensibility. + +## Main concerns + +The Core component is responsible for: + +* Managing business logic and domain services +* Providing API interfaces (Store API and Admin API) +* Handling data persistence and abstraction +* Managing plugins and extensions +* Supporting asynchronous processing +* Providing integration points for external systems + +## Domain-driven architecture + +Shopware organizes the Core around commerce-related domains rather than technical layers. Examples include: + +* Products +* Orders +* Customers +* Checkout +* Pricing +* Inventory + +Each domain encapsulates its own services, entities, and business rules. This structure helps maintain clear boundaries and improves extensibility. + +## Data abstraction layer (DAL) + +The Data Abstraction Layer (DAL) provides a consistent way to access and manipulate database entities. Instead of working directly with database queries, developers interact with repositories and entity definitions. + +Key responsibilities of the DAL include: + +* Entity definitions and associations +* Validation and schema abstraction +* Versioning and inheritance handling +* Context-aware data access +* Event dispatching during entity lifecycle changes + +The DAL ensures that all components access data consistently and enables powerful extension capabilities. + +## APIs and communication + +The Core exposes functionality through two primary APIs: + +* **Store API** — Public-facing API used by storefront applications and headless frontends. It supports anonymous access and customer-authenticated requests depending on the endpoint. +* **Administration API** — OAuth 2.0 secured API used by the Administration SPA and external management integrations. + +Both APIs communicate over HTTP and exchange structured JSON payloads, allowing decoupled frontend implementations. + +## Plugin and extension system + +Extensibility is a fundamental design principle of Shopware. The Core provides multiple extension mechanisms: + +* Symfony event system +* Service decoration +* Entity extensions +* Custom API routes +* Dependency injection configuration + +Plugins integrate into the system without modifying core code, enabling safe upgrades and customization. + +## Messaging and asynchronous processing + +Certain operations are executed asynchronously to improve performance and scalability. The Core uses Symfony Messenger for background processing tasks such as: + +* Indexing and search updates +* Scheduled tasks +* Email sending +* Integration workflows + +Message queues allow heavy operations to run outside the request lifecycle. + +## Interaction with other components + +The Core serves as the foundation for: + +* **Storefront** — Uses the Store API and domain services to render customer-facing pages. +* **Administration** — Communicates via the Admin API to manage entities and configurations. + +By centralizing logic in the Core, Shopware ensures consistent behavior regardless of how functionality is accessed. diff --git a/concepts/framework/architecture/storefront-concept.md b/concepts/framework/architecture/storefront-concept.md index fd03761ffa..d7a4b39787 100644 --- a/concepts/framework/architecture/storefront-concept.md +++ b/concepts/framework/architecture/storefront-concept.md @@ -1,7 +1,7 @@ --- nav: title: Storefront - position: 10 + position: 15 --- From 24f4d31367e145d3b72832593341819215c40035 Mon Sep 17 00:00:00 2001 From: somethings Date: Thu, 26 Feb 2026 16:04:54 +0100 Subject: [PATCH 19/43] Update index.md --- concepts/api/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/concepts/api/index.md b/concepts/api/index.md index ae453c8d8a..5c6c66c37f 100644 --- a/concepts/api/index.md +++ b/concepts/api/index.md @@ -14,7 +14,7 @@ Two functional APIs are available, each representing a different integration sur * **Store API**: customer-facing interactions * **Admin API**: administrative and system-level operations -Both APIs use HTTP, exchange structured JSON payloads, and require authenticated access. While they serve different purposes within the platform, they share some underlying design principles and structural patterns: +Both APIs use HTTP and exchange JSON payloads. The Administration API requires OAuth 2.0 authentication, whereas the Store API is publicly accessible and only requires contextual headers, with authentication needed for customer-specific endpoints. While they serve different purposes within the platform, they share some underlying design principles and structural patterns: * Search criteria abstraction for filtering, sorting, and pagination * Structured JSON request/response bodies From e47d06edc2fce6addada1164ea160573a7d5a6bf Mon Sep 17 00:00:00 2001 From: sushmangupta Date: Thu, 26 Feb 2026 17:23:22 +0100 Subject: [PATCH 20/43] remove content from architecture --- .../framework/architecture/core-concept.md | 92 ------------------- concepts/framework/architecture/index.md | 70 -------------- 2 files changed, 162 deletions(-) delete mode 100644 concepts/framework/architecture/core-concept.md diff --git a/concepts/framework/architecture/core-concept.md b/concepts/framework/architecture/core-concept.md deleted file mode 100644 index abbc91fa01..0000000000 --- a/concepts/framework/architecture/core-concept.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -nav: - title: Core - position: 25 ---- - -# Core - -The Core component represents the central backend foundation of Shopware. It provides the domain logic, data handling, APIs, and extensibility mechanisms that power both the Storefront and Administration components. - -Conceptually, the Core sits at the center of the platform architecture. While the Storefront and Administration provide user interfaces, the Core exposes functionality through structured APIs and services. All business logic, domain modeling, and system integrations are implemented within the Core to ensure consistency across different presentation layers. - -The Core is built on Symfony and follows modern backend design principles such as dependency injection, domain-driven organization, and event-based extensibility. - -## Main concerns - -The Core component is responsible for: - -* Managing business logic and domain services -* Providing API interfaces (Store API and Admin API) -* Handling data persistence and abstraction -* Managing plugins and extensions -* Supporting asynchronous processing -* Providing integration points for external systems - -## Domain-driven architecture - -Shopware organizes the Core around commerce-related domains rather than technical layers. Examples include: - -* Products -* Orders -* Customers -* Checkout -* Pricing -* Inventory - -Each domain encapsulates its own services, entities, and business rules. This structure helps maintain clear boundaries and improves extensibility. - -## Data abstraction layer (DAL) - -The Data Abstraction Layer (DAL) provides a consistent way to access and manipulate database entities. Instead of working directly with database queries, developers interact with repositories and entity definitions. - -Key responsibilities of the DAL include: - -* Entity definitions and associations -* Validation and schema abstraction -* Versioning and inheritance handling -* Context-aware data access -* Event dispatching during entity lifecycle changes - -The DAL ensures that all components access data consistently and enables powerful extension capabilities. - -## APIs and communication - -The Core exposes functionality through two primary APIs: - -* **Store API** — Public-facing API used by storefront applications and headless frontends. It supports anonymous access and customer-authenticated requests depending on the endpoint. -* **Administration API** — OAuth 2.0 secured API used by the Administration SPA and external management integrations. - -Both APIs communicate over HTTP and exchange structured JSON payloads, allowing decoupled frontend implementations. - -## Plugin and extension system - -Extensibility is a fundamental design principle of Shopware. The Core provides multiple extension mechanisms: - -* Symfony event system -* Service decoration -* Entity extensions -* Custom API routes -* Dependency injection configuration - -Plugins integrate into the system without modifying core code, enabling safe upgrades and customization. - -## Messaging and asynchronous processing - -Certain operations are executed asynchronously to improve performance and scalability. The Core uses Symfony Messenger for background processing tasks such as: - -* Indexing and search updates -* Scheduled tasks -* Email sending -* Integration workflows - -Message queues allow heavy operations to run outside the request lifecycle. - -## Interaction with other components - -The Core serves as the foundation for: - -* **Storefront** — Uses the Store API and domain services to render customer-facing pages. -* **Administration** — Communicates via the Admin API to manage entities and configurations. - -By centralizing logic in the Core, Shopware ensures consistent behavior regardless of how functionality is accessed. diff --git a/concepts/framework/architecture/index.md b/concepts/framework/architecture/index.md index 9683202559..de4d2b0b24 100644 --- a/concepts/framework/architecture/index.md +++ b/concepts/framework/architecture/index.md @@ -38,73 +38,3 @@ The architecture centers around the Shopware Core, which provides: * Messaging and scheduled task infrastructure The Storefront and Administration layers consume these services rather than duplicating logic, ensuring consistency across channels. - -## Architectural overview - -High-level architectural overview of Shopware’s core system layers and supporting infrastructure. - -```mermaid -flowchart TB - %% Entry - U[User (Customer / Admin)] -->|HTTPS| RP[Reverse Proxy / Load Balancer] - - %% Application boundary - subgraph SW[Shopware 6 Application] - direction TB - - %% Top-level modules - subgraph CORE[Core] - direction TB - DAL[Data Abstraction Layer (DAL)] - BL[Business Logic / Services] - API[Sales Channel API + Store API] - PLUG[Plugin System + Events] - SCHED[Scheduled Tasks] - MESSAGE[Symfony Messenger (Async)] - end - - subgraph ADMIN[Administration] - direction TB - ADMUI[Admin UI (Vue)] - ADMAPI[Admin API (ACL / AuthZ)] - BUILDADM[Build Tooling (npm/webpack)] - ADMUI --> ADMAPI - end - - subgraph STOREFRONT[Storefront] - direction TB - SFSSR[Storefront (Twig / Symfony Controllers)] - SFAPI[Store API / Sales Channel API Client] - BUILDSF[Build Tooling (npm/webpack)] - SFSSR --> SFAPI - end - - %% Internal interactions - ADMIN --> API - STOREFRONT --> API - API --> DAL - BL --> DAL - PLUG --> BL - SCHED --> MESSAGE - BL --> MESSAGE - end - - %% Infrastructure dependencies - DB[(MySQL / MariaDB)] <--> DAL - CACHE[(Redis: Cache / Sessions / Locks)] <--> SW - SEARCH[(Elasticsearch / OpenSearch)] <--> SW - FS[(Media Storage: Local FS / NFS / S3)] <--> SW - - %% Async processing - MQ[(Async Transport: Redis / RabbitMQ / DB)] <--> MESSAGE - MESSAGE --> W[Workers / Consumers] - W --> DB - W --> SEARCH - W --> FS - - %% External integrations - EXT[External Services\nPayment / Shipping / ERP / PIM / Tax / Email] <--> API - EXT <--> W - - RP --> SW -``` From d3cbf85466e32838a00d40bdc3fc71b4d22c587c Mon Sep 17 00:00:00 2001 From: sushmangupta Date: Thu, 26 Feb 2026 18:08:45 +0100 Subject: [PATCH 21/43] Add redirects --- .gitbook.yaml | 10 +++++++++- concepts/api/index.md | 2 +- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/.gitbook.yaml b/.gitbook.yaml index d8f790ed17..a96ac2fb50 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -98,4 +98,12 @@ redirects: guides/installation/setups/devenv.html: guides/installation/legacy-setups/devenv-setup.html guides/installation/setups/symfony-cli.html: guides/installation/legacy-setups/symfony-cli-setup.html guides/installation/setups/devenv-options.html: guides/installation/legacy-setups/devenv-options.html - guides/installation/setups/: guides/installation/ \ No newline at end of file + guides/installation/setups/: guides/installation/ + guides/plugins/plugins/administration/system-updates/meteor-components.html: guides/upgrades-migrations/administration/meteor-components.html + guides/plugins/plugins/administration/system-updates/pinia.html: guides/upgrades-migrations/administration/pinia.html + guides/plugins/plugins/administration/system-updates/vue3.html: guides/upgrades-migrations/administration/vue3.html + guides/plugins/plugins/administration/system-updates/vite.html: guides/upgrades-migrations/administration/vite.html + guides/plugins/plugins/administration/system-updates/vue-migration-build.html: guides/upgrades-migrations/administration/vue-migration-build.html + guides/plugins/plugins/administration/system-updates/vue-native.html: guides/upgrades-migrations/administration/vue-native.html + guides/plugins/plugins/administration/system-updates/extension-translation.html: guides/upgrades-migrations/extension-translation.html + guides/plugins/plugins/administration/system-updates/language-pack-migration.html: guides/upgrades-migrations/language-pack-migration.html \ No newline at end of file diff --git a/concepts/api/index.md b/concepts/api/index.md index 5c6c66c37f..09439ec994 100644 --- a/concepts/api/index.md +++ b/concepts/api/index.md @@ -5,7 +5,7 @@ nav: --- -# APIs +# API Shopware exposes HTTP-based APIs that allow external systems and custom applications to interact with the platform. From c7024b3fadf9170e2bdd5b5df7a75e9f0bbe8d1b Mon Sep 17 00:00:00 2001 From: sushmangupta Date: Fri, 27 Feb 2026 09:35:14 +0100 Subject: [PATCH 22/43] Update gitbook, add info box, fix link --- .gitbook.yaml | 6 ++++-- concepts/framework/architecture/storefront-concept.md | 2 +- .../administration/meteor-components.md | 10 +++++----- guides/upgrades-migrations/administration/pinia.md | 4 +--- guides/upgrades-migrations/administration/vite.md | 10 +++++----- .../administration/vue-migration-build.md | 10 +++++----- .../upgrades-migrations/administration/vue-native.md | 8 +++++--- guides/upgrades-migrations/administration/vue3.md | 2 -- 8 files changed, 26 insertions(+), 26 deletions(-) diff --git a/.gitbook.yaml b/.gitbook.yaml index a96ac2fb50..56d73003cc 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -105,5 +105,7 @@ redirects: guides/plugins/plugins/administration/system-updates/vite.html: guides/upgrades-migrations/administration/vite.html guides/plugins/plugins/administration/system-updates/vue-migration-build.html: guides/upgrades-migrations/administration/vue-migration-build.html guides/plugins/plugins/administration/system-updates/vue-native.html: guides/upgrades-migrations/administration/vue-native.html - guides/plugins/plugins/administration/system-updates/extension-translation.html: guides/upgrades-migrations/extension-translation.html - guides/plugins/plugins/administration/system-updates/language-pack-migration.html: guides/upgrades-migrations/language-pack-migration.html \ No newline at end of file + resources/references/upgrades/core/translation/extension-translation.html: guides/upgrades-migrations/extension-translation.html + resources/references/upgrades/core/translation/language-pack-migration.html: guides/upgrades-migrations/language-pack-migration.html + resources/references/upgrades/administration/: guides/upgrades-migrations/administration/ + resources/references/upgrades/: guides/upgrades-migrations/ \ No newline at end of file diff --git a/concepts/framework/architecture/storefront-concept.md b/concepts/framework/architecture/storefront-concept.md index d7a4b39787..9fc91a3446 100644 --- a/concepts/framework/architecture/storefront-concept.md +++ b/concepts/framework/architecture/storefront-concept.md @@ -46,7 +46,7 @@ The Store API is stateless and expects authentication information via request he Contrary to the Core, which can almost completely omit templating in favor of JSON responses, the Storefront contains a rich set of Twig templates to display a fully functional shop. Another concern of the Storefront is to provide templating with Twig. The page object, which was enriched beforehand, will later be passed to a specific Twig page template throughout a controller. A more detailed look into an example can be found in [Composite data handling](storefront-concept#composite-data-handling). -Last but not least, the Storefront not only contains static templates but also includes a theming engine to modify the rendered templates or change the default layout programmatically with your own [Themes](../../../guides/plugins/themes/) or [Plugins](storefront-concept). +Last but not least, the Storefront not only contains static templates but also includes a theming engine to modify the rendered templates or change the default layout programmatically with your own [Themes](../../../guides/plugins/themes/) or [Plugins](../../../guides/plugins/plugins/). ## Structure diff --git a/guides/upgrades-migrations/administration/meteor-components.md b/guides/upgrades-migrations/administration/meteor-components.md index d93dab20af..8c03c01858 100644 --- a/guides/upgrades-migrations/administration/meteor-components.md +++ b/guides/upgrades-migrations/administration/meteor-components.md @@ -1,15 +1,15 @@ --- nav: title: Upgrading to Meteor Components - position: 260 + position: 11 --- # Future Development Roadmap: Upgrading to Meteor Components -> **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 +:::info +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. +::: With the release of Shopware 6.7, we will replace several current administration components with components from the [Meteor Component Library](https://meteor-component-library.vercel.app/). diff --git a/guides/upgrades-migrations/administration/pinia.md b/guides/upgrades-migrations/administration/pinia.md index 9e45a5d6a5..9ccd31dc47 100644 --- a/guides/upgrades-migrations/administration/pinia.md +++ b/guides/upgrades-migrations/administration/pinia.md @@ -1,13 +1,11 @@ --- nav: title: Upgrading to Pinia - position: 261 + position: 12 --- # Migration from Vuex in Shopware to Pinia -## Introduction - With the release of Shopware 6.7, we will replace Vuex with [Pinia](https://pinia.vuejs.org/) as the state management library for the administration. ## Why Pinia? diff --git a/guides/upgrades-migrations/administration/vite.md b/guides/upgrades-migrations/administration/vite.md index ae20f20183..ec8ff9a799 100644 --- a/guides/upgrades-migrations/administration/vite.md +++ b/guides/upgrades-migrations/administration/vite.md @@ -1,15 +1,15 @@ --- nav: title: Changing from Webpack to Vite - position: 260 + position: 13 --- # 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 +:::info +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. +::: 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. diff --git a/guides/upgrades-migrations/administration/vue-migration-build.md b/guides/upgrades-migrations/administration/vue-migration-build.md index ecdbbe522d..be16d7579c 100644 --- a/guides/upgrades-migrations/administration/vue-migration-build.md +++ b/guides/upgrades-migrations/administration/vue-migration-build.md @@ -1,15 +1,15 @@ --- nav: title: Removing Vue Migration Build - position: 260 + position: 14 --- # 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 +:::info +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. +::: 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. diff --git a/guides/upgrades-migrations/administration/vue-native.md b/guides/upgrades-migrations/administration/vue-native.md index 99f2594b45..42ec3be1ab 100644 --- a/guides/upgrades-migrations/administration/vue-native.md +++ b/guides/upgrades-migrations/administration/vue-native.md @@ -1,13 +1,15 @@ --- nav: title: Native Vue - position: 260 + position: 15 --- # 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. +:::info +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 diff --git a/guides/upgrades-migrations/administration/vue3.md b/guides/upgrades-migrations/administration/vue3.md index 8c3d8fa841..e387597226 100644 --- a/guides/upgrades-migrations/administration/vue3.md +++ b/guides/upgrades-migrations/administration/vue3.md @@ -7,8 +7,6 @@ nav: # Vue 3 Upgrade -## 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 From 7afcb0b41817258f02a86861966d8bd8319f9aa0 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 27 Feb 2026 11:40:45 +0100 Subject: [PATCH 23/43] Update index.md --- concepts/api/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/concepts/api/index.md b/concepts/api/index.md index 09439ec994..3ba222ae63 100644 --- a/concepts/api/index.md +++ b/concepts/api/index.md @@ -18,7 +18,6 @@ Both APIs use HTTP and exchange JSON payloads. The Administration API requires O * Search criteria abstraction for filtering, sorting, and pagination * Structured JSON request/response bodies -* Versioned endpoints * Header-based contextual behavior These patterns form the foundation of integration development. From 4c7e3bab88be2fcf0af4185bb0d6a75a3b858618 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 27 Feb 2026 11:50:27 +0100 Subject: [PATCH 24/43] Update index.md --- guides/upgrades-migrations/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md index bf9a255e7b..9beb77688a 100644 --- a/guides/upgrades-migrations/index.md +++ b/guides/upgrades-migrations/index.md @@ -38,7 +38,7 @@ To reduce long-term upgrade cost: When targeting a new Shopware version: 1. Review [release notes](https://www.shopware.com/de/changelog/) and UPGRADE files -2. Check breaking changes per layer (Core / Admin / Translations) +2. Check breaking changes per layer (Core / Admin / Storefront / API) 3. Validate extension compatibility 4. Apply required migrations 5. Rebuild Admin/Storefront assets if needed From c58d2475f3b4a612f88584ed62fda9d77ad36ef1 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 27 Feb 2026 11:52:43 +0100 Subject: [PATCH 25/43] Update index.md --- guides/upgrades-migrations/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md index 9beb77688a..a633a2de46 100644 --- a/guides/upgrades-migrations/index.md +++ b/guides/upgrades-migrations/index.md @@ -50,7 +50,7 @@ When targeting a new Shopware version: ### Custom projects * Follow the ([Performing updates guide](../hosting/installation-updates/performing-updates.md)) to stage, test, and execute upgrades in order. -* Review [changelogs](https://github.com/shopware/shopware/tree/trunk/changelog) and UPGRADE files ([example](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.7.md)) per release. +* Review [RELEASE_INFO](https://github.com/shopware/shopware/blob/trunk/RELEASE_INFO-6.7.md) and UPGRADE files ([example](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.7.md)) per release. * Script data migrations and cache warm-ups. * Use feature toggles or maintenance mode to decouple risky changes from the deployment. From 4c613cc2da9b2b2ae394c94441dd8d8976448759 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 27 Feb 2026 12:36:43 +0100 Subject: [PATCH 26/43] Update upgrade-shopware.md --- guides/upgrades-migrations/upgrade-shopware.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/upgrades-migrations/upgrade-shopware.md b/guides/upgrades-migrations/upgrade-shopware.md index 9b23923b70..02b7699176 100644 --- a/guides/upgrades-migrations/upgrade-shopware.md +++ b/guides/upgrades-migrations/upgrade-shopware.md @@ -12,7 +12,7 @@ For maintaining custom plugins or apps, review the [Upgrades and Migrations](../ ## Standard update process -Shopware updates must be executed via Composer. +Shopware updates can be executed via Composer or with the web-based updater in the Administration panel. ### 1. Enable maintenance mode From 1539467206ed100c19579baa20cbbeb327e31102 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 27 Feb 2026 13:22:22 +0100 Subject: [PATCH 27/43] Update language-pack-migration.md --- .../language-pack-migration.md | 28 ++++++++++++++----- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/guides/upgrades-migrations/language-pack-migration.md b/guides/upgrades-migrations/language-pack-migration.md index 6ebca5ca3d..2dbc9779d1 100644 --- a/guides/upgrades-migrations/language-pack-migration.md +++ b/guides/upgrades-migrations/language-pack-migration.md @@ -13,7 +13,7 @@ Starting with Shopware **6.7.3.0**, translations are managed directly in Shopwar - **From Shopware 6.7.3.0 onward** - - Translations can be installed via Shopware itself, the [Language Pack plugin][language-pack-plugin] is not required to fetch the + - Translations can be installed via Shopware itself. The [Language Pack plugin][language-pack-plugin] is not required to fetch the newest [Shopware translations][shopware-translations]. - A new CLI command is available: @@ -22,7 +22,7 @@ Starting with Shopware **6.7.3.0**, translations are managed directly in Shopwar ``` - The [Language Pack plugin][language-pack-plugin] still works but is not recommended. -- Languages now have an active flag which can be toggled in the Administration under `Settings → Languages` +- Languages now have an active flag which can be toggled in the Administration under `Settings → Languages`. - Languages installed/managed from other sources do not need to register their locales in the admin anymore. - **Other translation plugins or snippets in themes are not affected and can still be used alongside the integrated handling.** @@ -47,7 +47,7 @@ Example: `bin/console translation:install --locales it-IT,fr-FR` will install It ### 2. You are **currently using the Language Pack plugin** -1. Run the translation command and install every language you are using in your shop +1. Run the translation command and install every language you are using in your shop: ```bash bin/console translation:install --locales , @@ -55,10 +55,16 @@ Example: `bin/console translation:install --locales it-IT,fr-FR` will install It 2. The command uses the **same source ([translate.shopware.com][shopware-translations])** as the [Language Pack plugin][language-pack-plugin] but is updated more frequently. So it's essentially identical – or even more up to date! -3. You can safely uninstall and remove the Language Pack plugin. Your **custom snippets** created in the Snippet module - remain intact since they are saved in the database. -4. Make sure that all languages you need are **active** in the Administration: - `Settings → Languages` +3. Make sure that all languages you need are **active** in the Administration: `Settings → Languages` +4. Create base snippet sets for used languages + - If you're on Shopware **6.7.7.0** or later, this is done automatically. + - If you're on Shopware **6.7.6.0** or earlier, for each language in use, create a base snippet, e.g. `BASE en-US` for English (US). +5. Change all sales channel domains to use the base snippet sets. + - If you're on Language Pack **5.37.1** or later, this is done automatically. + - If you're on Language Pack **5.37.0** or earlier, open each sales channel, scroll down to the domains and change the + snippet set from `LanguagePack` to `BASE`, e.g.: `LanguagePack en-US` to `BASE en-US`. +6. It is recommended to uninstall and remove the Language Pack plugin after `translation:install` succeeded for all locales. + Your **custom snippets** created in the snippet module remain intact since they are saved in the database. ## New installations @@ -70,6 +76,14 @@ Example: `bin/console translation:install --locales it-IT,fr-FR` will install It - Additional details about the new translation handling are available in the [integrated language handling][translation-system] guide. +## Common problems and troubleshooting + +### Can't remove Language Pack: a foreign key constraint fails (\`shopware\`.\`sales_channel_domain\`… + +Starting with **Shopware 6.7.7.0** and **Language Pack 5.37.1**, the migration process was improved. If you encounter this issue, +please update Shopware to >= 6.7.7.0, Language Pack to >= 5.37.1, remove the translation files created from running the +command and run the command again. Or follow the updated migration guide. + [translation-system]: ../../../../../concepts/translations/built-in-translation-system.md [language-pack-plugin]: https://store.shopware.com/en/swag338126230916f/shopware-language-pack.html [shopware-translations]: https://translate.shopware.com From 5dba68fc03960b921977fcb6f5fcb5a9259cee03 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 27 Feb 2026 14:40:36 +0100 Subject: [PATCH 28/43] Update upgrade-shopware.md --- .../upgrades-migrations/upgrade-shopware.md | 22 +++++++++++++------ 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/guides/upgrades-migrations/upgrade-shopware.md b/guides/upgrades-migrations/upgrade-shopware.md index 02b7699176..2ac9778005 100644 --- a/guides/upgrades-migrations/upgrade-shopware.md +++ b/guides/upgrades-migrations/upgrade-shopware.md @@ -16,17 +16,17 @@ Shopware updates can be executed via Composer or with the web-based updater in t ### 1. Enable maintenance mode -Prepare the system for update: - ```bash -bin/console system:update:prepare +bin/console sales-channel:maintenance:enable --all ``` -This enables maintenance mode and prepares the update process. - ### 2. Update Composer dependencies -Update all Composer packages without executing scripts: +Before running the update, adjust the required Shopware version in `composer.json` to the version to be installed. When using the Commercial plugin, update the `shopware/commercial` requirement to a compatible version as well. + +Failure to change these version constraints means that running the update command will resolve to the currently installed Shopware version and no actual upgrade will happen. + +After adjusting the version constraints, update all Composer packages without executing scripts: ```bash composer update --no-scripts @@ -46,12 +46,20 @@ Review changes carefully before committing them. ### 4. Finalize the update -Disable maintenance mode and complete the update: +Complete the update by running: ```bash bin/console system:update:finish ``` +This command applies all required update routines for the newly installed Shopware version, including running database migrations, and recompiling themes with the latest code. + +After the update process has finished successfully, disable maintenance mode separately: + +```bash +bin/console sales-channel:maintenance:disable --all +``` + ## Operational best practices * Automate pre-upgrade checks (PHP/DB versions, extensions, disk space). From 7636babae8130b8c75b84348a4b511c5f9dd386f Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 27 Feb 2026 17:30:10 +0100 Subject: [PATCH 29/43] Update store-api.md --- concepts/api/store-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/concepts/api/store-api.md b/concepts/api/store-api.md index 2f4aa11317..f15e5ad168 100644 --- a/concepts/api/store-api.md +++ b/concepts/api/store-api.md @@ -1,7 +1,7 @@ --- nav: title: Store API - position: 41 + position: 50 --- From 29d2f466aaa39a92b1b1c8b9039c423be193f5a4 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 27 Feb 2026 17:30:31 +0100 Subject: [PATCH 30/43] Update admin-api.md --- concepts/api/admin-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/concepts/api/admin-api.md b/concepts/api/admin-api.md index 13657c23eb..133aecf370 100644 --- a/concepts/api/admin-api.md +++ b/concepts/api/admin-api.md @@ -1,7 +1,7 @@ --- nav: title: Admin API - position: 42 + position: 60 --- From 20fb1a063aeaf227eaf66c457c6d0e346647e20f Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 2 Mar 2026 09:09:37 +0100 Subject: [PATCH 31/43] Update index.md --- guides/upgrades-migrations/administration/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/upgrades-migrations/administration/index.md b/guides/upgrades-migrations/administration/index.md index 4fb462c566..8e5c34f289 100644 --- a/guides/upgrades-migrations/administration/index.md +++ b/guides/upgrades-migrations/administration/index.md @@ -7,7 +7,7 @@ nav: # Administration -These guides cover upcoming architectural changes and migration paths affecting Administration extensions. Use them to prepare plugins for major system transitions: +These guides cover architectural changes and migration paths affecting Administration extensions, helping you prepare plugins for major system transitions. Depending on the version, some changes—for example, Vue 3, Pinia, and Vite—may have already been completed: * [Vue 3 migration](./vue3) * [Meteor components](./meteor-components) From 01a574b6700f53c0c94ddc4722490b6f279ed163 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 2 Mar 2026 09:17:28 +0100 Subject: [PATCH 32/43] Update index.md --- guides/upgrades-migrations/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md index a633a2de46..15b84e5d35 100644 --- a/guides/upgrades-migrations/index.md +++ b/guides/upgrades-migrations/index.md @@ -27,7 +27,6 @@ Administration framework upgrades (Vue, Pinia, Vite, Meteor) may introduce break To reduce long-term upgrade cost: * Avoid internal APIs and undocumented features -* Avoid unstable Admin patterns (`this.$parent`, prop mutation, Vue internals) * Keep dependencies aligned with Shopware core * Maintain automated test coverage * Keep database migrations idempotent From 392e34b260bb103601a13be973cb1aa418135b08 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 2 Mar 2026 09:20:36 +0100 Subject: [PATCH 33/43] Update index.md --- guides/upgrades-migrations/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md index 15b84e5d35..b1a783bff1 100644 --- a/guides/upgrades-migrations/index.md +++ b/guides/upgrades-migrations/index.md @@ -50,7 +50,6 @@ When targeting a new Shopware version: * Follow the ([Performing updates guide](../hosting/installation-updates/performing-updates.md)) to stage, test, and execute upgrades in order. * Review [RELEASE_INFO](https://github.com/shopware/shopware/blob/trunk/RELEASE_INFO-6.7.md) and UPGRADE files ([example](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.7.md)) per release. -* Script data migrations and cache warm-ups. * Use feature toggles or maintenance mode to decouple risky changes from the deployment. ### Custom plugins From a29a1e52dc4316ea01f67c8fb93d65fb69953175 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 2 Mar 2026 09:25:30 +0100 Subject: [PATCH 34/43] Update index.md --- guides/upgrades-migrations/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md index b1a783bff1..54c721f2cf 100644 --- a/guides/upgrades-migrations/index.md +++ b/guides/upgrades-migrations/index.md @@ -50,7 +50,7 @@ When targeting a new Shopware version: * Follow the ([Performing updates guide](../hosting/installation-updates/performing-updates.md)) to stage, test, and execute upgrades in order. * Review [RELEASE_INFO](https://github.com/shopware/shopware/blob/trunk/RELEASE_INFO-6.7.md) and UPGRADE files ([example](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.7.md)) per release. -* Use feature toggles or maintenance mode to decouple risky changes from the deployment. +* Use feature toggles to decouple risky changes from the deployment. ### Custom plugins From 24c32c1b668cd7c35689af444765e76060abc475 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 2 Mar 2026 09:27:18 +0100 Subject: [PATCH 35/43] Update index.md --- guides/upgrades-migrations/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md index 54c721f2cf..ae1a3f33f5 100644 --- a/guides/upgrades-migrations/index.md +++ b/guides/upgrades-migrations/index.md @@ -69,7 +69,6 @@ When targeting a new Shopware version: * Version manifests carefully. Broaden compatibility only after testing, and narrow it when deprecations apply. * Keep webhook/action handlers tolerant to new fields and events. Avoid hard coupling to specific core patch behavior. -* Document required scopes/permissions per version and avoid removing scopes without a migration path. ## Next steps From d1ccc19fca477d474aaa5806b985fb958c28b672 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 2 Mar 2026 09:39:13 +0100 Subject: [PATCH 36/43] Update index.md --- guides/upgrades-migrations/index.md | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md index ae1a3f33f5..e06502fb42 100644 --- a/guides/upgrades-migrations/index.md +++ b/guides/upgrades-migrations/index.md @@ -22,17 +22,7 @@ Upgrades typically fall into one of these categories: Administration framework upgrades (Vue, Pinia, Vite, Meteor) may introduce breaking changes requiring major version updates for affected plugins. ::: -## Upgrade strategy for extension developers - -To reduce long-term upgrade cost: - -* Avoid internal APIs and undocumented features -* Keep dependencies aligned with Shopware core -* Maintain automated test coverage -* Keep database migrations idempotent -* Track deprecations continuously—do not batch them - -## Typical upgrade workflow +## Typical Shopware upgrade workflow When targeting a new Shopware version: @@ -44,14 +34,22 @@ When targeting a new Shopware version: 6. Test critical flows 7. Update extension versions if required -## Extension responsibilities - ### Custom projects * Follow the ([Performing updates guide](../hosting/installation-updates/performing-updates.md)) to stage, test, and execute upgrades in order. * Review [RELEASE_INFO](https://github.com/shopware/shopware/blob/trunk/RELEASE_INFO-6.7.md) and UPGRADE files ([example](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.7.md)) per release. * Use feature toggles to decouple risky changes from the deployment. +## Upgrade strategy for extension developers + +To reduce long-term upgrade cost: + +* Avoid internal APIs and undocumented features +* Keep dependencies aligned with Shopware core +* Maintain automated test coverage +* Keep database migrations idempotent +* Track deprecations continuously—do not batch them + ### Custom plugins * Provide migration code for schema/config changes. From d6fff94ab5a3982ed9b59017fd1da52088dcc9c7 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 2 Mar 2026 10:36:49 +0100 Subject: [PATCH 37/43] Update index.md --- guides/upgrades-migrations/index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md index e06502fb42..eb74309de7 100644 --- a/guides/upgrades-migrations/index.md +++ b/guides/upgrades-migrations/index.md @@ -13,10 +13,12 @@ This section covers version-based upgrades and required migration effort for Sho Upgrades typically fall into one of these categories: +* **APIs**: HTTP/API contract changes. * **Core**: Framework-level changes, data abstraction layer (DAL) updates, APIs, feature removals, and backend behavior. * **[Administration](administration/index.md)**: frontend framework upgrades, Vue upgrades, breaking changes. -* **Translations**: [Extension translation](extension-translation), [Language pack migration](./language-pack-migration). -* **Extensions**: Version compatibility and required refactorings. +* **Storefront**: breaking changes related to Twig templates and JavaScript plugins. +* **App System**: changes that affect the app framework (e.g. manifest, webhooks, etc.). +* **Hosting & Configuration**: for infrastructure-related changes. :::info Administration framework upgrades (Vue, Pinia, Vite, Meteor) may introduce breaking changes requiring major version updates for affected plugins. From 77255965d08e52b094448162c0d55aaf4291298a Mon Sep 17 00:00:00 2001 From: sushmangupta Date: Mon, 2 Mar 2026 13:59:52 +0100 Subject: [PATCH 38/43] grammar fixes --- .../architecture/storefront-concept.md | 42 ++--- .../administration/meteor-components.md | 6 +- .../administration/pinia.md | 72 ++++---- .../administration/vite.md | 50 +++--- .../administration/vue-migration-build.md | 14 +- .../administration/vue-native.md | 158 +++++++++--------- .../administration/vue3.md | 26 +-- .../extension-translation.md | 6 +- guides/upgrades-migrations/index.md | 2 +- .../language-pack-migration.md | 10 +- 10 files changed, 194 insertions(+), 192 deletions(-) diff --git a/concepts/framework/architecture/storefront-concept.md b/concepts/framework/architecture/storefront-concept.md index 9fc91a3446..b2ebf7af69 100644 --- a/concepts/framework/architecture/storefront-concept.md +++ b/concepts/framework/architecture/storefront-concept.md @@ -7,19 +7,19 @@ nav: # Storefront -In this article, you will get to know the Storefront component and learn a lot of its main concepts. Along the way, you will find answers to the following questions: +In this article, you will learn about the Storefront component and its main concepts. Along the way, you will find answers to the following questions: -* What is the Storefront component & what is its main purpose? +* What is the Storefront component & what is its primary purpose? * What technologies are being used? * How is the Storefront structured? * Which parts of other Platform components are being used? * How does the composite data handling work? -* What is the definition and main purpose of Pages, Pagelets, Controllers, and their corresponding Templates? +* What is the definition and primary purpose of Pages, Pagelets, Controllers, and their corresponding Templates? * How is the Storefront handling translations? ## Introduction -The Storefront component is a frontend written in PHP. It conceptually sits on top of the Core, similar to the [Administration](administration-concept) component. As the Storefront can be seen as a classical PHP application, it makes use of HTML rendering, JavaScript, and a CSS preprocessor. The Storefront component uses Twig as the templating engine and SASS for styling purposes. The foundation of the Storefront template is based on the Bootstrap framework and, therefore, fully customizable. +The Storefront component is a frontend written in PHP. It conceptually sits on top of the Core, similar to the [Administration](administration-concept) component. As the Storefront can be seen as a classical PHP application, it uses HTML rendering, JavaScript, and a CSS preprocessor. The Storefront component uses Twig as the templating engine and SASS for styling purposes. The Storefront template is built on the Bootstrap framework and is therefore fully customizable. ## Main concerns @@ -30,21 +30,21 @@ The main concerns that the Storefront component has are listed below. Furthermor * Rendering templates * Provide theming -Contrary to API calls that result in single resource data, a whole page in the Storefront displays multiple different data sets on a single page. Think of partials, which lead to a single page being displayed. Imagine a page that displays the order overview in the customer account environment. There are partials that are generic and will be displayed on almost every Page. These partials include - for example, Header and Footer information wrapped into a `GenericPage` as `Pagelets` \(`HeaderPagelet`, `FooterPagelet`\). This very generic Page will later be enriched with the specific information you want to display through a separate loader \(e.g. a list of orders\). +Contrary to API calls that result in single resource data, a whole page in the Storefront displays multiple different data sets on a single page. Think of partials, which lead to a single page being displayed. Imagine a page that displays the order overview in the customer account environment. There are partials that are generic and will be displayed on almost every Page. These partials include - for example, Header and Footer information wrapped into a `GenericPage` as `Pagelets` \(`HeaderPagelet`, `FooterPagelet`\). This very generic Page will later be enriched with the specific information you want to display through a separate loader \(e.g., a list of orders\). -To obtain information from a specific resource, the Storefront's second concern is to map requests to the Core. Internally, the Storefront makes use of the [Store API](https://shopware.stoplight.io/docs/store-api/38777d33d92dc-quick-start-guide) routes to enrich the Page with additional information, e.g., a list of orders, which is being fetched through the order route. +To obtain information from a specific resource, the Storefront's second concern is to map requests to the Core. Internally, the Storefront uses the [Store API](https://shopware.stoplight.io/docs/store-api/38777d33d92dc-quick-start-guide) routes to enrich the Page with additional information, e.g., a list of orders, which is fetched via the order route. ![Data and logic flow in Shopware 6 \(top to bottom and vice versa\)](../../../assets/concepts-api-storeApiLogic.svg) -Once all needed information is added to the Page, the corresponding page loader returns the Page to a Storefront controller. +Once all required information is added to the Page, the corresponding page loader returns the Page to the Storefront controller. ### Store API and the traditional Twig storefront In the traditional server-side rendered Twig storefront, the Store API is not called directly by the browser. Instead, custom storefront controllers internally use the Store API to fetch data from the Core. -The Store API is stateless and expects authentication information via request headers (for example the `sw-context-token`). In contrast, the traditional storefront relies on session-based authentication, so authentication does not need to be handled manually on every request. +The Store API is stateless and expects authentication information via request headers (for example, the `sw-context-token`). In contrast, the traditional storefront relies on session-based authentication, so authentication does not need to be handled manually on every request. -Contrary to the Core, which can almost completely omit templating in favor of JSON responses, the Storefront contains a rich set of Twig templates to display a fully functional shop. Another concern of the Storefront is to provide templating with Twig. The page object, which was enriched beforehand, will later be passed to a specific Twig page template throughout a controller. A more detailed look into an example can be found in [Composite data handling](storefront-concept#composite-data-handling). +Unlike the Core, which can almost completely omit templating in favor of JSON responses, the Storefront includes a rich set of Twig templates to display a fully functional shop. Another concern for the Storefront is providing templating with Twig. The page object, which was enriched beforehand, will later be passed to a specific Twig page template through a controller. A more detailed look into an example can be found in [Composite data handling](storefront-concept#composite-data-handling). Last but not least, the Storefront not only contains static templates but also includes a theming engine to modify the rendered templates or change the default layout programmatically with your own [Themes](../../../guides/plugins/themes/) or [Plugins](../../../guides/plugins/plugins/). @@ -71,19 +71,19 @@ Let's have a look at the Storefront's general component structure. When opening |- Storefront.php ``` -Starting at the top of this list, you will find all Storefront controllers inside the `Controller` directory. As said beforehand, a page is being built inside that controller with the help of the corresponding page loaders, Pages, Pagelets, and events, which you will find in the directories: `Pages`, `Pagelets`, and their sub-directories. Each controller method will also give detailed information about its routing with the help of attributes. The directory `DependencyInjection` includes all dependencies which are used in the specific controllers, whereas the `Event` directory includes route request events, and the `Framework` directory, amongst other things, also includes the Routing, Caching, and furthermore. `Migration` and `Test` obviously include migrations and tests for the Storefront component \(e.g., tests for each Storefront controller\). +Starting at the top of this list, you will find all Storefront controllers inside the `Controller` directory. As mentioned earlier, a page is being built within that controller using the corresponding page loaders, Pages, Pagelets, and events, which you will find in the directories `Pages`, `Pagelets`, and their sub-directories. Each controller method will also provide detailed information about its routing using attributes. The directory `DependencyInjection` includes all dependencies which are used in the specific controllers, whereas the `Event` directory includes route request events, and the `Framework` directory, amongst other things, also includes the Routing, Caching, and furthermore. `Migration` and `Test` obviously include migrations and tests for the Storefront component \(e.g., tests for each Storefront controller\). -As the Storefront theme uses Bootstrap, the template structure inside `./Resources` is a derivative of the Bootstrap starter template. Besides using Twig as the templating engine and SASS as the CSS preprocessor, we are also using Webpack for bundling and transpiling purposes. This templating directory structure is considered the best practice. If you are interested in developing your own themes or plugins, this section will give more information. +As the Storefront theme uses Bootstrap, the template structure in `./Resources` is derived from the Bootstrap starter template. Besides using Twig as the templating engine and SASS as the CSS preprocessor, we are also using Webpack for bundling and transpiling purposes. This templating directory structure is considered the best practice. If you are interested in developing your own themes or plugins, this section will give more information. ## Composite data handling -Composite data loading describes the process of preparing and fetching data for a whole template page worth of content. As a web application, the page rendering process is a central concern of the Storefront. Contrary to solutions through `postDispatch`-Handling or `lazy loading` from templates, the controller actions of the Storefront do a full lookup and handle data loading transparently and fully. The Storefront provides a general solution for this problem - the Page System. +Composite data loading describes the process of preparing and fetching data for a whole template page worth of content. In a web application, page rendering is a central concern for the Storefront. Contrary to solutions through `postDispatch`-Handling or `lazy loading` from templates, the controller actions of the Storefront do a full lookup and handle data loading transparently and fully. The Storefront provides a general solution for this problem - the Page System. ### Pages and Pagelets -The pages in the Storefront component can roughly be categorized into Pages and Pagelets. Although functionally identical, they represent different usages of Page's data. A Page is generally rendered into a full template, whereas a Pagelet is either a part of a Page or accessible through an XHR route, sometimes even both. +The pages in the Storefront component can roughly be categorized into Pages and Pagelets. Although functionally identical, they represent different usages of Page's data. A Page is generally rendered as a complete template, whereas a Pagelet is either part of a Page or accessible via an XHR route, sometimes both. -A single Page is always a three class namespace: +A single Page is always a three-class namespace: * The Page-Struct \(`GenericPage`\) - represents the data * The PageLoader \(`PageLoaderInterface`\) - handles the creation of page structs @@ -91,7 +91,7 @@ A single Page is always a three class namespace: ### Example: Composition of the account order page -Referring to the example described in the [main concerns chapter](storefront-concept#main-concerns), have a detailed look at the composition of the Storefronts `AccountOrderPage` with Header and Footer information. The composition is handled through the page loaders themselves by triggering the loading of associated data internally. The following example will also be used for any other Page being displayed on the Storefront. +Referring to the example described in the [main concerns chapter](storefront-concept#main-concerns), have a detailed look at the composition of the Storefronts `AccountOrderPage` with Header and Footer information. The composition is handled by the page loaders themselves, which trigger the loading of associated data internally. The following example will also be used for any other Page being displayed on the Storefront. To describe how the composition of the Page works, first get to know what the result of the composition should be. @@ -99,11 +99,11 @@ To describe how the composition of the Page works, first get to know what the re * This page consists of generic information \(e.g. Header, Footer\) and detailed information \(e.g. a list of orders\). * Detailed information should be fetched throughout the Core component to make use of the [Store API routes](../../api/store-api). -The best entry point to give you a good understanding of how the composition works is the corresponding controller. In our case, it is the `AccountOrderController`. The main and only task of the controller is to assign a page struct to a variable, which will later be passed to a Twig template. The Page is received by the specific `AccountOrderPageLoader`. Additionally, the method attributes of the controller also set routing information like path, name, options, and methods. +The best entry point for a good understanding of how the composition works is the corresponding controller. In our case, it is the `AccountOrderController`. The controller's only task is to assign a page struct to a variable, which will later be passed to a Twig template. The Page is received by the specific `AccountOrderPageLoader`. Additionally, the controller's method attributes set routing information such as path, name, options, and methods. -Speaking of the page loader \(`AccountOrderPageLoader`\), which returns the page \(`AccountOrderPage`\), you will see that we are doing the composition here. At first, a generic page is created by using the `GenericPageLoader`. As described above, this generic Page includes information, which is generic like Header, Footer, and Meta information. This information is wrapped inside our `Pagelets` and displays a specific part of the Page. +Speaking of the page loader \(`AccountOrderPageLoader`\), which returns the page \(`AccountOrderPage`\), you will see that we are doing the composition here. At first, a generic page is created by using the `GenericPageLoader`. As described above, this generic Page includes generic content, such as Header, Footer, and Meta information. This information is wrapped inside our `Pagelets` and displays a specific part of the Page. -Later, the `AccountOrderPage` is created from the generic Page because we also would like to add more information to this Page. Per definition, the `AccountOrderPage` can set and get a list of orders we can receive by calling a Store API route through the `OrderRoute` of our Core component. That said, we make sure that our Storefront uses the same data as we would use by calling the API directly, which is a big advantage. +Later, the `AccountOrderPage` is created from the generic Page because we also want to add more information to it. By definition, the `AccountOrderPage` can set and get a list of orders we can receive by calling a Store API route through the `OrderRoute` of our Core component. That said, we make sure that our Storefront uses the same data as we would use by calling the API directly, which is a big advantage. Once we have set all the necessary information to our page \(`AccountOrderPage`\) in our page loader \(`AccountOrderPageLoader`\), we are making usage of our event dispatcher to throw a `PageLoadedEvent`. For each Page, there should be a specific event, which will be thrown to ensure extensibility throughout plugins \(`AccountOrderPageLoadedEvent`\). @@ -113,10 +113,10 @@ To summarize the composition of a page, have a look at this diagram: ## Translations -Extending or adjusting a **translation** in Shopware 6 can be done by adding your own snippets inside a plugin. Besides that, there is also a set of translations inside our default Storefront component. We have decided to save snippets as JSON files, so it is easy to structure and find snippets you want to change. However, when using pluralization and/or variables, you can expect slight differences between snippets in the Administration and the Storefront. In theory, you can place your snippets anywhere as long as you load your JSON files correctly. However, we recommend that you mirror the core structure of Shopware. +Extending or adjusting a **translation** in Shopware 6 can be done by adding your own snippets inside a plugin. Besides that, there is also a set of translations inside our default Storefront component. We have decided to save snippets as JSON files, making it easy to structure and find the ones you want to change. However, when using pluralization and/or variables, you can expect slight differences between snippets in the Administration and the Storefront. In theory, you can place your snippets anywhere as long as you load your JSON files correctly. However, we recommend that you mirror the core structure of Shopware. ::: info -Storefront snippets can be found in `platform/src/Storefront/Resources/snippet`. +Storefront snippets are located in `platform/src/Storefront/Resources/snippet`. ::: -Inside that directory, you will find a specific sub-directory for each language, e.g., `de_DE` following the ISO standard. The localization is done via the exact ISO. In addition to the language, the country of destination is also supplied. By default, two Storefront translations are provided: `de_DE` and `en_GB`. There are, of course, language plugins for other locales available. Inside these JSON files, you will find a simple translation and the possibility to work with variables and pluralization, which are wrapped with the `%` character. The reference of a translated value is used inside our Twig templates by calling the Twig function `trans` and working with interpolations \( e.g. `{{ "general.homeLink"|trans }}`\). +Inside that directory, you will find a specific subdirectory for each language, e.g., `de_DE` following the ISO standard. Localization is done using the exact ISO. In addition to the language, the country of destination is also supplied. By default, two Storefront translations are provided: `de_DE` and `en_GB`. There are, of course, language plugins for other locales available. Inside these JSON files, you will find a simple translation and the possibility to work with variables and pluralization, which are wrapped with the `%` character. The reference of a translated value is used inside our Twig templates by calling the Twig function `trans` and working with interpolations \( e.g. `{{ "general.homeLink"|trans }}`\). diff --git a/guides/upgrades-migrations/administration/meteor-components.md b/guides/upgrades-migrations/administration/meteor-components.md index 8c03c01858..58d46b9b6c 100644 --- a/guides/upgrades-migrations/administration/meteor-components.md +++ b/guides/upgrades-migrations/administration/meteor-components.md @@ -63,7 +63,7 @@ To support extension developers and ensure compatibility between Shopware 6.6 an - **Default Value**: `false` (uses the new Meteor Components by default) - **Purpose**: - When `deprecated` is set to `true`, the component will render the old (deprecated) version instead of the new Meteor Component. - - This allows extension developers to maintain a single codebase compatible with both Shopware 6.6 and 6.7 without being forced to immediately migrate to Meteor Components. + - This allows extension developers to maintain a single codebase compatible with both Shopware 6.6 and 6.7 without being forced to migrate to Meteor Components immediately. Example: @@ -80,4 +80,6 @@ Example: ``` -> **Important:** Although the old components can still be used with the `deprecated` prop, we highly recommend migrating to Meteor Components whenever possible to align with future Shopware development. +:::warning +Although the old components can still be used with the `deprecated` prop, we highly recommend migrating to Meteor Components whenever possible to align with future Shopware development. +::: diff --git a/guides/upgrades-migrations/administration/pinia.md b/guides/upgrades-migrations/administration/pinia.md index 9ccd31dc47..474c186a18 100644 --- a/guides/upgrades-migrations/administration/pinia.md +++ b/guides/upgrades-migrations/administration/pinia.md @@ -10,11 +10,11 @@ With the release of Shopware 6.7, we will replace Vuex with [Pinia](https://pini ## Why Pinia? -Migrating to Pinia simplifies state management with an intuitive API, no need for mutations, better TypeScript support, and seamless integration with Vue 3 Composition API. It’s lightweight, modular, and offers modern features like devtools support, making it a more efficient alternative to Vuex. +Migrating to Pinia simplifies state management with an intuitive API, eliminates the need for mutations, provides better TypeScript support, and enables seamless integration with Vue 3 Composition API. It’s lightweight, modular, and offers modern features like devtools support, making it a more efficient alternative to Vuex. ## Migration Guide -To migrate a Vuex store to Pinia, you need to make some changes to the store definition and how you access it in components. +To migrate a Vuex store to Pinia, you need to update the store definition and how you access it in components. - First, register it with `Shopware.Store.register` and define the store with `state`, `getters`, and `actions` properties: @@ -26,17 +26,17 @@ export default { state: { // Initial state - ... - }, + ... + }, mutations: { - ... - }, + ... + }, getters: { - ... - }, + ... + }, actions: { - ... - }, + ... + }, } ``` @@ -46,14 +46,14 @@ export default { const store = Shopware.Store.register('', { state: () => ({ // Initial state - ... - }), + ... + }), getters: { - ... - }, + ... + }, actions: { - ... - }, + ... + }, }); export default store; ``` @@ -65,13 +65,13 @@ const store = Shopware.Store.register({ id: '', state: () => ({ // Initial state - }), + }), getters: { // ... - }, + }, actions: { // ... - }, + }, }); ``` @@ -101,7 +101,7 @@ import './state/products.state'; #### State -In Pinia, `state` must be a function returning the initial state instead of a static object. +In Pinia, `state` must be a function that returns the initial state rather than a static object. ```javascript state: () => ({ @@ -111,13 +111,13 @@ In Pinia, `state` must be a function returning the initial state instead of a st #### Mutations -Vuex `mutations` are no longer needed in Pinia, since you can modify state directly in actions or compute it dynamically. +Vuex `mutations` are no longer needed in Pinia, since you can modify the state directly in actions or compute it dynamically. ```javascript actions: { updateProductName(newName) { this.productName = newName; // Directly update state - }, + }, }, ``` @@ -133,7 +133,7 @@ We recommend migrating JavaScript stores to TypeScript for stricter typing, bett ```typescript const store = Shopware.Store.register({ id: 'myStore', - ... + ... }); export type StoreType = ReturnType; @@ -147,13 +147,13 @@ import type { StoreType } from './store/myStore'; declare global { interface PiniaRootState { myStore: StoreType; - } + } } ``` ### Composables as a Store -With Pinia, you can use reactive properties inside a store and define it like a composable. Keep in mind that only variables and functions returned from the store will be tracked by Pinia in devtools. +With Pinia, you can use reactive properties in a store and define them as composable. Keep in mind that Pinia will track only variables and functions returned from the store in devtools. ```typescript const store = Shopware.Store.register('', function() { @@ -163,11 +163,11 @@ const store = Shopware.Store.register('', function() { function increment() { count.value++; - } + } function decrement() { count.value--; - } + } return { count, doubled, increment, decrement }; }); @@ -184,11 +184,11 @@ export function useMyComposable() { function increment() { count.value++; - } + } function decrement() { count.value--; - } + } return { count, doubled, increment, decrement }; } @@ -227,11 +227,11 @@ describe('my store', () => { beforeEach(() => { store.$reset(); - }); + }); it('has initial state', () => { expect(store.count).toBe(0); - }); + }); }); ``` @@ -245,7 +245,7 @@ const pinia = createPinia(); describe('my component', () => { beforeEach(() => { setActivePinia(pinia); - }); + }); it('is a component', async () => { const wrapper = mount(await wrapTestComponent('myComponent', { sync: true }), { @@ -253,11 +253,11 @@ describe('my component', () => { plugins: [pinia], stubs: { // ... - }, - }, - }); + }, + }, + }); expect(wrapper.exists()).toBe(true); - }); + }); }); ``` diff --git a/guides/upgrades-migrations/administration/vite.md b/guides/upgrades-migrations/administration/vite.md index ec8ff9a799..61df8be77e 100644 --- a/guides/upgrades-migrations/administration/vite.md +++ b/guides/upgrades-migrations/administration/vite.md @@ -12,23 +12,23 @@ This document serves as a general guideline for our development direction. ::: 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. +The current Webpack build system has been in place for quite some time, but, like everything in tech, it becomes outdated sooner or later. In addition to Webpack being slow and outdated, we identified a security risk for our application's future. 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. +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. +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. ### Migrate the custom webpack config to Vite If you have a custom webpack config, you need to migrate it to Vite. You need to do the following steps: - 1. Create a new config file `vite.config.mts` to your plugin in the `YourApp/src/Resources/app/administration/src` directory. Previously you had a `webpack.config.js` in the following directory: `YourApp/src/Resources/app/administration/build/` + 1. Create a new config file `vite.config.mts` in your plugin in the `YourApp/src/Resources/app/administration/src` directory. Previously, you had a `webpack.config.js` in the following directory: `YourApp/src/Resources/app/administration/build/` 2. Remove the old `webpack.config.js` file - 3. Make sure to remove all webpack related dependencies from your `package.json` file + 3. Make sure to remove all webpack-related dependencies from your `package.json` file 4. Make sure to add the Vite dependencies to your `package.json` file A basic config migration could look like this: @@ -40,9 +40,9 @@ module.exports = () => { resolve: { alias: { '@example': 'src/example', - } - } - }; + } + } + }; }; ``` @@ -54,16 +54,16 @@ export default defineConfig({ resolve: { alias: { '@example': 'src/example', - }, - }, + }, + }, }); ``` -Of course, this is a very basic example. The Vite config can be much more complex and powerful. You can find more information about the Vite config in the [Vite documentation](https://vite.dev/config/). Depending on your webpack config, the migration can be very individual. +This is a very basic example. The Vite config can be much more complex and powerful. You can find more information about the Vite config in the [Vite documentation](https://vite.dev/config/). Depending on your webpack config, the migration can vary greatly. ## Implementation details -In this section we'll document the implementation details of the new Vite setup. +In this section, we'll document the implementation details of the new Vite setup. ### Feature flag @@ -71,7 +71,7 @@ The system is already in place and can be tested by activating the feature flag: ### 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. +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 loads all Shopware Bundles and custom plugins. ### Building the Shopware Administration @@ -79,11 +79,11 @@ The command responsible for building the Shopware Administration with all extens ### 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`. +The Vite config located at `/src/Administration/Resources/app/administration/vite.config.mts` is only responsible for the core, not extensions. Currently, there are a few file duplications because Vite requires a 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 responsible for building all extensions is located at `/src/Administration/Resources/app/administration/build/plugins.vite.ts`. This script uses Vite's JS API 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: @@ -93,11 +93,11 @@ The script will do the following: ### 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. +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. +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 in `application.ts` loads and injects the entry files based on the environment. Production build: @@ -105,15 +105,15 @@ Production build: 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` +- Information is served by our own Vite plugin `shopware-vite-plugin-serve-multiple-static` in the 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. +To accomplish all this, we created a few Vite plugins, and in this section, we'll 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. +This plugin manipulates Vite's chunk-loading function to prepend `window.__sw__.assetPath` to the chunk path. This is needed for cluster setups that serve assets from an S3 bucket. ### static-assets @@ -125,7 +125,7 @@ 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: +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 and 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: @@ -143,16 +143,16 @@ const { ref } = window['Shopware']['Vue']; ### 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. +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 ensures that all overrides are loaded immediately when 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. +Transforming all `*.html.twig` files in a way that Vite can load them. ## 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. +A quick note on HMR (Hot Module Replacement). Vite is only capable of reloading `*.vue` files. This means we can only leverage HMR until we transition 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. +Vite can 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, moving the loading time to the first request. Webpack, on the other hand, compiles ahead of time until the server is ready. diff --git a/guides/upgrades-migrations/administration/vue-migration-build.md b/guides/upgrades-migrations/administration/vue-migration-build.md index be16d7579c..18de35fa7f 100644 --- a/guides/upgrades-migrations/administration/vue-migration-build.md +++ b/guides/upgrades-migrations/administration/vue-migration-build.md @@ -35,7 +35,7 @@ Before (Vue 2): ```vue ``` @@ -43,7 +43,7 @@ After (Vue 3): ```vue ``` @@ -69,7 +69,7 @@ More detailed guide about [`$slots` unification breaking changes](https://v3-mig #### `$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; use template refs instead. Before (Vue 2): @@ -89,11 +89,11 @@ More detailed guide about [`$children` breaking changes](https://v3-migration.vu #### 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. +The methods `$on`, `$off`, and `$once` are removed in Vue 3, with no 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. +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: +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 of how you could adjust your code: Before (Vue 2): @@ -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. +In Shopware 6.7, the Vue migration build will be removed entirely. 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. diff --git a/guides/upgrades-migrations/administration/vue-native.md b/guides/upgrades-migrations/administration/vue-native.md index 42ec3be1ab..f0fde8e419 100644 --- a/guides/upgrades-migrations/administration/vue-native.md +++ b/guides/upgrades-migrations/administration/vue-native.md @@ -19,7 +19,7 @@ This document outlines the reasons for this change and provides an overview of o ## 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. +The Shopware 6 Administration is built on Vue.js, with several custom systems on top to enable extensions. ### Custom component registration @@ -31,7 +31,7 @@ Shopware.Component.register('sw-component', { }); ``` -### Custom templates with Twig.Js +### Custom templates with Twig.js ```html {% block sw-component %} @@ -61,14 +61,14 @@ Our transition to a more native Vue.js approach is driven by several key factors #### 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. +The Composition API has become the new standard for Vue documentation and projects across 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. +We will gradually transform our components from Options API to Composition API. Together with native blocks, this lays the foundation for using Single File Components (SFCs). +The transformation will be spread across multiple major versions to give all of us enough time to adapt. Take a look at the estimated timeline below. #### Upgrade Path @@ -92,7 +92,7 @@ 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. +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 @@ -102,13 +102,13 @@ We will gradually transform all component templates from external `*.html.twig` | 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. +*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. +Vuex has been the default State management for Vue 2. For Vue 3, Pinia took its place. #### What Will Change? @@ -125,35 +125,35 @@ We will move all core Vuex states to Pinia stores. The public API will change fr ## Example: Component Evolution -Now let's take a look how core and extension components will evolve. +Now let's take a look at 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. +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`. +In the core, we register a component via `Shopware.Component.register`. ```javascript Shopware.Component.register('sw-text-field', { template: ` - {% block sw-text-field %} - - {% endblock %} - `, + {% block sw-text-field %} + + {% endblock %} + `, data() { return { value: null, - } - }, + } + }, methods: { onChange() { this.$emit('update:value', this.value); - } - }, + } + }, }); ``` @@ -164,33 +164,33 @@ The extension overrides the component via `Shopware.Component.override`. ```javascript Shopware.Component.override('sw-text-field', { template: ` - {% block sw-text-field %} - {% parent %} + {% block sw-text-field %} + {% parent %} - {{ helpText }} - {% endblock %} - `, + {{ helpText }} + {% endblock %} + `, props: { helpText: { type: String, required: false, - } - } + } + } }) ``` #### Extension new component -The extension adds additional component via `Shopware.Component.register`. +The extension adds an additional component via `Shopware.Component.register`. ```javascript Shopware.Component.register('your-crazy-ai-field', { template: ` - {% block your-crazy-ai-field %} - {# ... #} - {% endblock %} - `, + {% block your-crazy-ai-field %} + {# ... #} + {% endblock %} + `, // Options API implementation }) @@ -198,64 +198,64 @@ Shopware.Component.register('your-crazy-ai-field', { ### Shopware 6.8 -With Shopware 6.8 the core uses single file components with the composition API. +In 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. +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. +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 @@ -266,10 +266,10 @@ import { defineProps } from 'vue'; // This file would also use Shopware.Component.overrideComponentSetup // if it would change the existing public API const props = defineProps({ - helpText: { - type: String, - required: false, - }, + helpText: { + type: String, + required: false, + }, }); ``` @@ -278,13 +278,13 @@ const props = defineProps({ ```javascript -// For this you would also have the option to use a `*.vue` file but you don't have to +// 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 %} - `, + {% block your-crazy-ai-field %} + {# ... #} + {% endblock %} + `, // Options API implementation }) @@ -296,9 +296,9 @@ The only difference for 6.9 is that you can no longer register new components vi ## FAQ -**Will existing extensions built with Options API continue to work in Shopware 6.8?** +**Will existing extensions built with the 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. +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?** @@ -306,11 +306,11 @@ I would recommend building a simple Vue application using the Composition API. Y **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. +It works with native Vue.js components; therefore, it 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. +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?** @@ -318,15 +318,15 @@ 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. +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 check and transition them manually. **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. +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. +It has built-in TypeScript support. **What happens to existing extensions using Twig.js templates after version 6.9?** @@ -334,7 +334,7 @@ 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. +Yes! You can add new components using SFC and native blocks. But you can't extend core components using the old systems or vice versa. **Which extensions are affected by these changes?** diff --git a/guides/upgrades-migrations/administration/vue3.md b/guides/upgrades-migrations/administration/vue3.md index e387597226..e175e54146 100644 --- a/guides/upgrades-migrations/administration/vue3.md +++ b/guides/upgrades-migrations/administration/vue3.md @@ -7,19 +7,19 @@ nav: # Vue 3 Upgrade -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/). +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 upgrade affects you. +Let's start with some frequently asked questions. These will also help you determine whether this upgrade affects you. ### Which extensions are affected by the Vue 3 upgrade? -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. +App-based extensions aren't affected by these changes. However, if your extension is plugin-based and includes custom administration code, you likely need to refactor. ### 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. +Yes, Vue 3 introduced breaking changes. It's crucial to review the Vue.js migration guide and this document for detailed information. ### What steps should I follow to upgrade my Shopware plugin to Vue 3? @@ -35,13 +35,13 @@ You can verify compatibility by reviewing the extension's functionality and upda ### Do I need to rewrite my extension to upgrade 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. +While some changes are required, a complete rewrite is not necessary. The effort required is determined 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 upgrade 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? +### Where can I find support and community discussions about updating the Shopware plugin to Vue 3? You can participate in discussions and seek help on the Shopware community Discord. There is a dedicated channel for this topic called `#shopware-development`. @@ -83,13 +83,13 @@ For your templates to work correctly, perform the following in no specific order Most of your code should be unaffected by the upgrade. You can start by searching for `this.$`. The usage of `this.$` is an indicator of Vue's internal API. These calls are very likely to break except for `this.$tc`. 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. +The best way to find errors is to test your application thoroughly, either manually or automatically. ## 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. You can only use those hooks if your code allows to be executed multiple times. +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. You can only use those hooks if your code allows it to be executed multiple times. ### Using slots programmatically @@ -97,12 +97,12 @@ It is no longer sufficient to check if `this.$slots` has a property with the slo ### 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. -Try to avoid `this.$parent` communication wherever possible as this is an anti pattern. Use services or event communication instead. +`this.$parent` is prone to errors because Vue 3 wraps asynchronous components in an `AsyncWrapperComponent`. This leads to the virtual DOM tree differing between Vue 2 and Vue 3. Where in Vue 2, a `this.$parent` call was successful, in Vue 3, a `this.$parent.$parent` may be necessary. +Try to avoid `this.$parent` communication whenever possible, as this is an anti-pattern. Use services or event communication instead. ### Vue dev tools performance -Vue dev tools causes massive performance issues with huge Vue 3 applications. +Vue DevTools causes massive performance issues in large Vue 3 applications. There is an open [issue on Github](https://github.com/vuejs/devtools-v6/issues/1875) with next to no activity from the maintainers. ### v-model changes @@ -115,7 +115,7 @@ Vuex stores lose reactivity if one or more getters alter state data. For more co ### 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. +Fields in the administration no longer use the previous ID, which was almost exclusively used in tests. To fix any failing test, add the `name` attribute to your field with a unique identifier. ### Prop default @@ -127,7 +127,7 @@ This is an antipattern also for Vue 2. In Vue 2, however, those mutations were n ## Conclusion -This document emphasizes the crucial need to upgrade your Shopware extensions to Vue.js 3 as Vue.js 2 reaches its end of life on December 31st 2023. Here's a concise recap of the key points: +This document emphasizes the crucial need to upgrade your Shopware extensions to Vue.js 3 as Vue.js 2 reaches its end of life on December 31st, 2023. Here's a concise recap of the key points: - **Transition to Vue 3**: Shopware will adopt Vue.js 3 from version 6.6 onwards. - **FAQ**: Addressing frequently asked questions: diff --git a/guides/upgrades-migrations/extension-translation.md b/guides/upgrades-migrations/extension-translation.md index 3c1cb1bf6d..da543719f1 100644 --- a/guides/upgrades-migrations/extension-translation.md +++ b/guides/upgrades-migrations/extension-translation.md @@ -41,7 +41,7 @@ check the translation files, or use the `--fix` parameter to even automate the m #### Step 1: Rename your existing files -Rename your existing files from country-specific naming to the language base layer naming. +Rename your existing files from country-specific naming to language-based layer naming. ```Generic ├── messages.en-GB.base.json ⇒ messages.en.base.json @@ -65,7 +65,7 @@ Re-create empty files with the former names of the country-specific naming. Check for duplicate translations across country-specific files and remove them from the country-specific layer. -Here are some example locales that are a dialect to the generic base layer. +Here are some example locales that are dialects of the generic base layer. ```Generic ├── messages.en-US.base.json (dialect of en-GB with the en base layer) @@ -88,7 +88,7 @@ country-specific terms being replaced. ### 1. Maintain Backward Compatibility -Keep existing country-specific files during transition to ensure compatibility with older Shopware versions that don't +Keep existing country-specific files during the transition to ensure compatibility with older Shopware versions that don't support the base layer. ## Troubleshooting diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md index eb74309de7..6b6075fb5a 100644 --- a/guides/upgrades-migrations/index.md +++ b/guides/upgrades-migrations/index.md @@ -7,7 +7,7 @@ nav: # Version Upgrades and Migrations -This section covers version-based upgrades and required migration effort for Shopware core and extensions. When upgrading to a new minor or major Shopware version, review it to understand breaking changes, required adjustments, and compatibility requirements. +This section covers version-based upgrades and the required migration effort for Shopware core and extensions. When upgrading to a new minor or major Shopware version, review it to understand breaking changes, required adjustments, and compatibility requirements. ## Scope of this section diff --git a/guides/upgrades-migrations/language-pack-migration.md b/guides/upgrades-migrations/language-pack-migration.md index 2dbc9779d1..9eb0759776 100644 --- a/guides/upgrades-migrations/language-pack-migration.md +++ b/guides/upgrades-migrations/language-pack-migration.md @@ -49,9 +49,9 @@ Example: `bin/console translation:install --locales it-IT,fr-FR` will install It 1. Run the translation command and install every language you are using in your shop: - ```bash - bin/console translation:install --locales , - ``` + ```bash + bin/console translation:install --locales , + ``` 2. The command uses the **same source ([translate.shopware.com][shopware-translations])** as the [Language Pack plugin][language-pack-plugin] but is updated more frequently. So it's essentially identical – or even more up to date! @@ -68,8 +68,8 @@ Example: `bin/console translation:install --locales it-IT,fr-FR` will install It ## New installations -- During a fresh Shopware installation, you can select desired languages directly in the installer. They will be - downloaded and installed automatically. +- During a fresh Shopware installation, you can select the desired languages directly in the installer. They will be + downloaded and installed automatically. - No additional language plugin is required. ## More information From bebb057d05d61b47f99749d2eb36613e6c4bc631 Mon Sep 17 00:00:00 2001 From: sushmangupta Date: Mon, 2 Mar 2026 14:04:21 +0100 Subject: [PATCH 39/43] markdown fixes --- .../upgrades-migrations/language-pack-migration.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/guides/upgrades-migrations/language-pack-migration.md b/guides/upgrades-migrations/language-pack-migration.md index 9eb0759776..4ef6cbb729 100644 --- a/guides/upgrades-migrations/language-pack-migration.md +++ b/guides/upgrades-migrations/language-pack-migration.md @@ -47,23 +47,23 @@ Example: `bin/console translation:install --locales it-IT,fr-FR` will install It ### 2. You are **currently using the Language Pack plugin** -1. Run the translation command and install every language you are using in your shop: +* Run the translation command and install every language you are using in your shop: ```bash bin/console translation:install --locales , ``` -2. The command uses the **same source ([translate.shopware.com][shopware-translations])** as the [Language Pack plugin][language-pack-plugin] but is +* The command uses the **same source ([translate.shopware.com][shopware-translations])** as the [Language Pack plugin][language-pack-plugin] but is updated more frequently. So it's essentially identical – or even more up to date! -3. Make sure that all languages you need are **active** in the Administration: `Settings → Languages` -4. Create base snippet sets for used languages +* Make sure that all languages you need are **active** in the Administration: `Settings → Languages` +* Create base snippet sets for used languages - If you're on Shopware **6.7.7.0** or later, this is done automatically. - If you're on Shopware **6.7.6.0** or earlier, for each language in use, create a base snippet, e.g. `BASE en-US` for English (US). -5. Change all sales channel domains to use the base snippet sets. +* Change all sales channel domains to use the base snippet sets. - If you're on Language Pack **5.37.1** or later, this is done automatically. - If you're on Language Pack **5.37.0** or earlier, open each sales channel, scroll down to the domains and change the snippet set from `LanguagePack` to `BASE`, e.g.: `LanguagePack en-US` to `BASE en-US`. -6. It is recommended to uninstall and remove the Language Pack plugin after `translation:install` succeeded for all locales. +*x It is recommended to uninstall and remove the Language Pack plugin after `translation:install` succeeded for all locales. Your **custom snippets** created in the snippet module remain intact since they are saved in the database. ## New installations From 975c2dc06a4855a31b36722b4fbcd0b6b9926948 Mon Sep 17 00:00:00 2001 From: sushmangupta Date: Mon, 2 Mar 2026 14:07:45 +0100 Subject: [PATCH 40/43] Markdown fix2 --- guides/upgrades-migrations/language-pack-migration.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/guides/upgrades-migrations/language-pack-migration.md b/guides/upgrades-migrations/language-pack-migration.md index 4ef6cbb729..0d0f4727ea 100644 --- a/guides/upgrades-migrations/language-pack-migration.md +++ b/guides/upgrades-migrations/language-pack-migration.md @@ -49,12 +49,12 @@ Example: `bin/console translation:install --locales it-IT,fr-FR` will install It * Run the translation command and install every language you are using in your shop: - ```bash - bin/console translation:install --locales , - ``` + ```bash + bin/console translation:install --locales , + ``` * The command uses the **same source ([translate.shopware.com][shopware-translations])** as the [Language Pack plugin][language-pack-plugin] but is - updated more frequently. So it's essentially identical – or even more up to date! +updated more frequently. So it's essentially identical – or even more up to date! * Make sure that all languages you need are **active** in the Administration: `Settings → Languages` * Create base snippet sets for used languages - If you're on Shopware **6.7.7.0** or later, this is done automatically. @@ -63,7 +63,7 @@ Example: `bin/console translation:install --locales it-IT,fr-FR` will install It - If you're on Language Pack **5.37.1** or later, this is done automatically. - If you're on Language Pack **5.37.0** or earlier, open each sales channel, scroll down to the domains and change the snippet set from `LanguagePack` to `BASE`, e.g.: `LanguagePack en-US` to `BASE en-US`. -*x It is recommended to uninstall and remove the Language Pack plugin after `translation:install` succeeded for all locales. +* It is recommended to uninstall and remove the Language Pack plugin after `translation:install` succeeded for all locales. Your **custom snippets** created in the snippet module remain intact since they are saved in the database. ## New installations From 4fdee7e1a16f1bdf1f13aa16641b5665247ab551 Mon Sep 17 00:00:00 2001 From: sushmangupta Date: Mon, 2 Mar 2026 14:09:51 +0100 Subject: [PATCH 41/43] Markdown fix3 --- .../language-pack-migration.md | 22 +++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/guides/upgrades-migrations/language-pack-migration.md b/guides/upgrades-migrations/language-pack-migration.md index 0d0f4727ea..b9a06d262c 100644 --- a/guides/upgrades-migrations/language-pack-migration.md +++ b/guides/upgrades-migrations/language-pack-migration.md @@ -47,23 +47,27 @@ Example: `bin/console translation:install --locales it-IT,fr-FR` will install It ### 2. You are **currently using the Language Pack plugin** -* Run the translation command and install every language you are using in your shop: +- Run the translation command and install every language you are using in your shop: - ```bash - bin/console translation:install --locales , - ``` + ```bash + bin/console translation:install --locales , + ``` -* The command uses the **same source ([translate.shopware.com][shopware-translations])** as the [Language Pack plugin][language-pack-plugin] but is +- The command uses the **same source ([translate.shopware.com][shopware-translations])** as the [Language Pack plugin][language-pack-plugin] but is updated more frequently. So it's essentially identical – or even more up to date! -* Make sure that all languages you need are **active** in the Administration: `Settings → Languages` -* Create base snippet sets for used languages + +- Make sure that all languages you need are **active** in the Administration: `Settings → Languages` + +- Create base snippet sets for used languages - If you're on Shopware **6.7.7.0** or later, this is done automatically. - If you're on Shopware **6.7.6.0** or earlier, for each language in use, create a base snippet, e.g. `BASE en-US` for English (US). -* Change all sales channel domains to use the base snippet sets. + +- Change all sales channel domains to use the base snippet sets. - If you're on Language Pack **5.37.1** or later, this is done automatically. - If you're on Language Pack **5.37.0** or earlier, open each sales channel, scroll down to the domains and change the snippet set from `LanguagePack` to `BASE`, e.g.: `LanguagePack en-US` to `BASE en-US`. -* It is recommended to uninstall and remove the Language Pack plugin after `translation:install` succeeded for all locales. + +- It is recommended to uninstall and remove the Language Pack plugin after `translation:install` succeeded for all locales. Your **custom snippets** created in the snippet module remain intact since they are saved in the database. ## New installations From 519aacb794176ba18ff0ab5c960d10f5bb99b07f Mon Sep 17 00:00:00 2001 From: sushmangupta Date: Mon, 2 Mar 2026 14:13:33 +0100 Subject: [PATCH 42/43] Spell check fix --- .wordlist.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index 4e8592f80d..50c476ba5c 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1812,6 +1812,7 @@ setProductFixtureVisibility setSalesChannelDomain setToInitialState settingsItem +SFCs sha shakable shallowMount @@ -1970,6 +1971,7 @@ viewport viewportHeight viewports vimeo +Vite's vscode vue vuex From 64762699e675e23146667a3769484892fa9051cd Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 2 Mar 2026 13:13:52 +0000 Subject: [PATCH 43/43] chore: sort .wordlist.txt --- .wordlist.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index 50c476ba5c..e749a03121 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -834,6 +834,7 @@ SDKs SEO SEOs SFC +SFCs SFTP SHA SKEs @@ -1041,6 +1042,7 @@ VersionDataPayloadField VersionField VirtualHosts Vite +Vite's VitePress Vitepress Vitest @@ -1812,7 +1814,6 @@ setProductFixtureVisibility setSalesChannelDomain setToInitialState settingsItem -SFCs sha shakable shallowMount @@ -1971,7 +1972,6 @@ viewport viewportHeight viewports vimeo -Vite's vscode vue vuex