# Shopware Knowledge Patch > Shopware - Skill: `nevaberry/shopware-knowledge-patch` (Agent Skill, multi-file: 9 files) - Install (CLI): `npx skillmds@latest add nevaberry/shopware-knowledge-patch` - Raw SKILL.md: https://api.skillmd.com/api/skills/nevaberry/shopware-knowledge-patch/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: nevaberry (https://skillmd.com/u/nevaberry) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nevaberry/shopware-knowledge-patch --- # Shopware Knowledge Patch Use this skill for Shopware development, upgrades, extension compatibility, Store API or Admin API integration, Storefront customization, Administration customization, and deployment configuration. Start with the quick checks below, then open the task-specific reference before changing code or configuration. ## Reference index | Reference | Topics | | --- | --- | | [Administration](references/administration.md) | Vite and Vue 3, Pinia, Meteor components, CMS and rule-condition extension points, notifications, dashboard, sourcemaps | | [Storefront](references/storefront.md) | ESI pagelets, route state, navigation, forms, snippets, accessibility, Twig, themes, cookies, feeds, images | | [APIs and integrations](references/apis-and-integrations.md) | Store API and Admin API contracts, MCP, translations, media downloads, sessions, integration ACLs, OpenAPI | | [Data and search](references/data-and-search.md) | DAL contracts, criteria, indexing, product streams, Elasticsearch/OpenSearch, cache keys, SEO, entities | | [Extensions and framework](references/extensions-and-framework.md) | Plugins, apps, custom fields, scheduled tasks, Symfony, Composer, exceptions, hooks, configuration | | [Operations and infrastructure](references/operations-and-infrastructure.md) | Platform baseline, cache, queues, Redis, Varnish, filesystems, PaaS, JWT, Shopware Services, CLI setup | | [Commerce and documents](references/commerce-and-documents.md) | Payments, orders, customers, rules, addresses, tax providers, documents, ZUGFeRD, measurements | ## Breaking-change triage ### Administration build and state - Migrate custom Administration builds from `webpack.config.js` to `vite.config.js` and distribute a 6.7-specific build. - Native Vue 3 is in use and components are async by default. Guard template refs or use `@vue:mounted`. - Core state uses `Shopware.Store`; register Pinia stores with `Shopware.Store.register()` and mutate state in actions. - Replace migrated `sw-*` basic components with their `mt-*` equivalents and account for their changed value, event, and prop contracts. See [Administration](references/administration.md). ### Storefront chrome and extension points - Store API `Cached*Route` decorators are removed. - Header and footer now render through `/header` and `/footer` ESI requests, with new layout entry points and `base_esi_header` / `base_esi_footer`. - Header/footer data belongs in their pagelet loaders and loaded events, not `GenericPageLoader`, `Page`, or `ErrorTemplateStruct`. - Use `activeRoute`, `window.activeRoute`, and `.is-active-route-*` instead of the former controller/action state. See [Storefront](references/storefront.md). ### Payment and customer contracts - Extend `AbstractPaymentHandler`; the former sync, async, prepared, refund, and recurring handler interfaces are deprecated. - App manifests use `manifest-3.0.xsd` and `pay-url` rather than `capture-url`. - Payment and shipping API writes and plugin installers must supply a stable `technicalName`. - Customer default-payment behavior is removed in favor of the last-used or current method. See [Commerce and documents](references/commerce-and-documents.md). ### DAL and extension definitions - Plugin `Resources/config/entities.xml` custom entities are unsupported; use an `EntityDefinition` or attribute entities. - Many-to-many mapping definitions must declare foreign-key fields, and `EntityExtension::getEntityName()` is mandatory. - Search-result wrappers are separating from collections. Call collection methods on `$result->getEntities()` and iterate `searchResult.entities`. - `Criteria::excludeFields()` can omit storage columns without returning partial entities, but cannot be combined with `addFields()`. See [Data and search](references/data-and-search.md). ### Cache, queues, and infrastructure - Cache invalidation is delayed through the `shopware.invalidate_cache` scheduled task; the prior delay switch is removed. - Under `WEBHOOKS_REWORK`, explicitly consume the `webhook` transport or deliveries accumulate. - Varnish requires XKeys; cache tags can no longer be stored in Redis. - Redis DSNs now belong to named connections, and dependent configuration uses `connection` keys rather than `dsn` or `url`. - JWTs use only `APP_SECRET`, which must contain at least 32 characters. See [Operations and infrastructure](references/operations-and-infrastructure.md). ## High-use migration recipes ### Create a minimal plugin ```bash bin/console plugin:create MyPlugin MyNamespace --no-scaffold ``` `--no-scaffold` creates only the required plugin skeleton. ### Validate foreign keys for MySQL 8.4 `dal:validate` rejects a foreign key that does not reference a complete primary or unique key. Versioned entities commonly need the missing `version_id`. Temporarily tolerate a constraint during migration with: ```bash bin/console dal:validate --tolerate-foreign-key=constraint_name ``` ### Opt into production sourcemaps Set `GENERATE_SOURCEMAPS=true` together with `NODE_ENV=production`: ```bash GENERATE_SOURCEMAPS=true NODE_ENV=production composer build:js:admin GENERATE_SOURCEMAPS=true NODE_ENV=production composer build:js:storefront ``` Other production values keep sourcemaps disabled; non-production builds always generate them. ### Consume and roll back webhook transport With `WEBHOOKS_REWORK` enabled, consume `webhook` explicitly, preferably before the other transports: ```bash bin/console messenger:consume webhook async low_priority ``` For rollback, stop webhook workers and run: ```bash bin/console webhook:drain-to-async ``` Draining can redeliver messages, so receivers must deduplicate using `X-Shopware-Event-Id` or body `eventId`. Recover crashed rows left as `running` before draining. ### Flush delayed cache invalidations - Use `sw-force-cache-invalidate: 1` for a critical Admin API write. - Run `cache:clear:delayed` or call `DELETE /api/_action/cache-delayed` to flush queued tags. - Run `cache:watch:delayed` to inspect queued tags. ### Configure a custom Storefront route name Allowlist route names that do not use the `frontend`, `widgets`, or `payment` prefixes: ```yaml storefront: router: allowed_routes: [swag.test.foo-bar] ``` ### Exclude heavy DAL fields ```php $criteria->excludeFields(['description', 'keywords']); ``` Excluded properties keep their typed entity defaults. Unknown, required, or write-protected top-level fields cannot be excluded. ### Configure read-only deployments Set a non-empty value to bypass web-installer and `install.lock` checks and avoid writes to the project root and public `.htaccess`: ```bash SHOPWARE_SKIP_WEBINSTALLER=1 ``` ### Update installed translations The daily `translation.update` task performs the same refresh as `translation:update` and `POST /api/_action/translation/update`. Disable it with: ```bash bin/console scheduled-task:deactivate translation.update ``` When no translations are installed, the task makes no remote request. ### Start a local Shopware CLI project With Docker and Shopware CLI installed: ```bash shopware-cli project create mystore cd mystore make up make setup ``` The generated default serves the Storefront at `http://127.0.0.1:8000`, the Administration at `http://127.0.0.1:8000/admin`, and uses `admin` / `shopware`. ## Task routing - For a template, component, or Administration override, read [Administration](references/administration.md) or [Storefront](references/storefront.md) before selecting an extension point. - For routes, schemas, ACLs, webhooks, MCP, translations, or media transfer, read [APIs and integrations](references/apis-and-integrations.md). - For DAL definitions, queries, indexing, product streams, search, and cache relevance, read [Data and search](references/data-and-search.md). - For plugin/app lifecycle, framework APIs, exceptions, constraints, custom fields, and scheduled handlers, read [Extensions and framework](references/extensions-and-framework.md). - For workers, caching, filesystems, hosting, environment variables, Redis, Varnish, or service reconciliation, read [Operations and infrastructure](references/operations-and-infrastructure.md). - For checkout, payments, customers, orders, rules, addresses, documents, or units, read [Commerce and documents](references/commerce-and-documents.md).