Agent Skills: 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 | Vite and Vue 3, Pinia, Meteor components, CMS and rule-condition extension points, notifications, dashboard, sourcemaps | | Storefront | ESI pagelets, route state, navigation, forms, snippets, accessibility, Twig, themes, cookies, feeds, images | | APIs and integrations | Store API and Admin API contracts, MCP, translations, media downloads, sessions, integration ACLs, OpenAPI | | Data and search | DAL contracts, criteria, indexing, product streams, Elasticsearch/OpenSearch, cache keys, SEO, entities | | Extensions and framework | Plugins, apps, custom fields, scheduled tasks, Symfony, Composer, exceptions, hooks, configuration | | Operations and infrastructure | Platform baseline, cache, queues, Redis, Varnish, filesystems, PaaS, JWT, Shopware Services, CLI setup | | Commerce and documents | 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.

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.

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.

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.

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.

High-use migration recipes

Create a minimal plugin

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:

bin/console dal:validate --tolerate-foreign-key=constraint_name

Opt into production sourcemaps

Set GENERATE_SOURCEMAPS=true together with NODE_ENV=production:

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:

bin/console messenger:consume webhook async low_priority

For rollback, stop webhook workers and run:

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:

storefront:
  router:
    allowed_routes: [swag.test.foo-bar]

Exclude heavy DAL fields

$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:

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:

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:

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 or Storefront before selecting an extension point.
• For routes, schemas, ACLs, webhooks, MCP, translations, or media transfer, read APIs and integrations.
• For DAL definitions, queries, indexing, product streams, search, and cache relevance, read Data and search.
• For plugin/app lifecycle, framework APIs, exceptions, constraints, custom fields, and scheduled handlers, read Extensions and framework.
• For workers, caching, filesystems, hosting, environment variables, Redis, Varnish, or service reconciliation, read Operations and infrastructure.
• For checkout, payments, customers, orders, rules, addresses, documents, or units, read Commerce and documents.