docs(administration): Vue single file component extension documentation by davidtraum · Pull Request #2503 · shopware/docs

David Traum (davidtraum) · 2026-09-08T08:12:19Z

Summary

This PR will cover the documentation for the new, yet still experimental vue single file components in the administration.

Related links

closes shopware/shopware#20191

shopware-dev-docs-connector · 2026-09-08T08:12:24Z

Developer Docs healthcheck

Status: Completed with failure.
Repository: shopware/docs
Commit: 0c9892c
Preview: No Vercel preview URL was found in the workflow logs.
Workflow run: #5533

Five chapters below the Single File Components chapter, plus a troubleshooting page. The reader starts with an empty directory and ends with a plugin that warns a merchant when a product's profit margin is too low, shown on the real product detail page. 1. Override first. Most extensions start by changing a page that already exists, so the tutorial does that in chapter 2 and only builds a component of its own in chapter 4. 2. Every code sample was built and run against an Administration from trunk with shopware/shopware#20006 and shopware/shopware#20008 applied, which is what lets a .vue override target a component that still ships a Twig template. The screenshots are that shop. 3. Chapter 1 sets the shop up with Shopware CLI and links the existing Docker and watcher guides rather than repeating them. 4. Troubleshooting is a page of its own, not a chapter, and holds only diagnostics: every build message, every console message, and the markup that fails silently. 5. Seven inline placeholders mark where a reference page belongs, each naming the issue that tracks it (#20192, #20196, #20198, #20199). The experimental warning lives in a shared snippet so every page carries it. Closes shopware/shopware#20194 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Each "What this replaces" tab now opens with the markup: the Twig template in the Twig column, the `<template>` block in the SFC column. Comparing the two starts with the thing that looks the same on both sides. Also drops the two file listings that pushed the SFC template down the page; the file names are the first line of each snippet. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Four sales channels left behind by acceptance-test runs sat in the sidebar of every screenshot. They are gone from the dev shop, and all six are retaken against the same states as before: plugin installed, block location, chapter 2 through chapter 5. The extensions listing is now filtered to the plugin by search rather than by hiding the other cards, so the checkpoint says to search for it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

The tutorial teaches these APIs in the order a reader needs them. This is the page to look one up on: filename rules, the two macros, the three override composables, and sw-block with sw-block-parent, each with its signature and the mode it is valid in. Replaces the four placeholders in the chapter that pointed at this page. Closes shopware/shopware#20196 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Splits the filename table into a base table and an override table. Four rows read as four options; two tables of two read as what it is, one naming scheme with two layouts each. Each composable example now opens with its import from shopware:composables, and the table of names you never write drops them, keeping only the macros, the two globally registered tags, and the Shopware object. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

The five chapters move into single-file-components/tutorial/ behind a hub page, so the chapter list reads as one unit next to the reference and troubleshooting pages rather than as seven siblings. The override composables are imported from shopware:composables/* wherever the tutorial uses them. Note for review: the portal's sidebar renders five levels (VPSidebarItem, `depth < 5`), and these chapters now sit one deeper, so they are reachable by link and search but do not appear in the sidebar until that cap is raised. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Brings in the nested tutorial from docs/admin-sfc-tutorial, and splits api-reference.md into a section: a hub carrying the filename rules and the cross-cutting tables, then one page each for swDefinePublic, swDefineOverride, useSwPreviousState, useSwProps, useSwContext, sw-block and sw-block-parent. Every composable page opens with its import from shopware:composables, and the tutorial's three reference links now point at the individual pages. Note for review: like the tutorial chapters, these pages sit one level deeper than the portal's sidebar renders (VPSidebarItem, `depth < 5`), so they are reachable by link and search but do not appear in the sidebar until that cap is raised. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…d block components Three sections, each with a hub that carries what its members share: 1. Macros - the shorthand-only rule, the once-at-top-level rule and the mandatory-even-when-empty rule live here instead of on both macro pages. 2. Composables - the naming rule for shopware:composables/*, the three override composables, and the composables the Administration already has. 3. Block components - the declare/contribute model, block naming and chains, with sw-block and sw-block-parent underneath. The composables page now lists the codebase composables an extension can use: seventeen that replace a mixin, named with the mixin each one stands in for, plus the four that carry Administration state. Left out are the ones that are Administration plumbing rather than extension API, such as the block registry behind sw-block. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

`useSwPreviousState()`, `useSwProps()` and `useSwContext()` are injected by the setup transform like the macros are, so an import line would be wrong to copy into a file. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

They are injected by the setup transform like the macros, so the reference now lists them beside `swDefinePublic` under "What you never import". The `shopware:composables/*` specifier stays where it belongs: on the composables the Administration publishes, such as `useNotification()` and `useListing()`. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

The composables the Administration ships are all experimental, so the reference no longer filters by the `@private` annotation and documents the whole set - signature, what it returns, and the mixin it replaces. They move off the index onto a page of their own, so the composables section stays a landing page for the three override composables. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…e off it The SFC migration codemod targets it on purpose: it keeps the `cms-element` mixin's behaviour, so a migrated component does not change behaviour in the same step it changes shape. Documenting it means a reader who finds it in their own file knows what it is, and the member-by-member mapping to `useCmsElement()` is the second step. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Every composable gets its own page under the Composables section, the way the three override composables already had one: signature with its import, what it is for, an example where one helps, and the mixin it replaces. The section index becomes the parent that lists them, grouped by area. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Closes the last open question the chapter left: what works today, what is still coming, and where to say something about it. The support tables are derived from the transform's macro registry and the mixin container, not written from memory, and the mixin table names every composable that is still to come. The chapter also sorts to the bottom of the Administration section, and the template mutation restriction is stated as permanent rather than temporary. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

One page for readers who want to know why the dialect exists and what it compiles to. Every generated sample is the output of the real transform run against the tutorial's own component, not written from memory. It covers the build pipeline, the base and override lowering, the block registry at runtime, and the Twig shims - including the one fact that explains most of the chapter's rules: an override's markup is a slot the base component calls, which is why its bindings arrive through a generated destructuring and why a write to them is rejected. The chapter entry point gains a teaser of the syntax and loses the sections the reference pages now cover. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Gerrit Weiermann (gweiermann) · 2026-09-17T09:57:17Z

Blocked by:

Hard blockers:

Soft blockers:

[Admin] Setup transform errors report the wrong source location, or none at all shopware#19561
[Admin] Vite watcher does not surface setup transform errors shopware#19562
Reject dynamic Shopware block override declarations shopware#17534
[Admin] Native setup components expose no state to the platform's own Options API consumers shopware#19571

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

- remove author metadata ("Verified against trunk", "Verified in source") from the tutorial - drop the eight composable pages that `shopware:composables` does not export (useBlockContext, useCmsElementDeprecated, useContext, useModuleIconColors, useSession, useSnackbar, useSystem, useTheme) and their wordlist entries - document defineExpose() as rejected in both modes; swDefinePublic() generates it - add the transform messages that were missing from the troubleshooting tables - keep the timeline on the roadmap only and link it from the index - point the devtools block inspector note at the open PR instead of the closed issue - fix the usePosition field argument description and the host-PHP reasoning - remove codemod references that presented it as available to plugin developers - revert the experimental route note from the stable add-custom-route guide - tighten reader-directing asides and repeated feedback calls to action Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

- chapter 1: create the shop with `project create … dev-trunk`, name the container tabs "Shopware CLI" and "Composer", turn the vue-tsc hint into an info box with the command - chapter 3: drop the visibility info block and the claim about `this` - chapter 4: teach the filename rule on its own, explain the scoped styles, list `shopware:composables` among the virtual modules - chapter 5: reframe the block-name promise without publishing, mark the swDefinePublic section as a reminder - reword the tutorial intro and chapter openers Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

- tutorial: explain the warnBelow prop, keep sw-block-parent in the chapter 3 example, scope the template-mutation warning, correct the tWithFallback, store and prop-override statements, give the snippet files and main.ts import that chapters 4 and 5 left implicit - troubleshooting: quote messages verbatim, fix the reserved-name and sw-block causes, add the missing wrong-mode, default-slot, override script and TemplateFactory messages - internals: only targeted Twig blocks are wrapped, add the named-slot limitation, an import is usually enough for a base component - api-reference: correct useNotification, useUserSettings, usePlaceholder, useSalutation, useListing, useVideoCover and the macro rules against trunk; drop the deprecated $tc Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…m it - the experimental notice and every pointer from the stable guides now name 6.7.16.0 instead of "trunk only, in no 6.7 release" - block names keep the backwards-compatibility promise; the sw-block system targeting them is what can still change without deprecation - the roadmap no longer promises the shims "across several majors" - drop the route aside from chapter 4, the tutorial never builds a module Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The transform now scopes every sw-block by its component, generates a defineExpose() footer for base components and a target-registration script for overrides. The listings are real transform output again, and the runtime section describes the component-scoped registry. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

- chapter 1 installs shopware/dev-tools and generates demo data, so the product pages the later chapters open have prices and purchase prices - chapter 2 states once that sw-block extends targets Twig blocks and sw-blocks alike; the shim caveat moves into an info box - the block-name compatibility promise lives in the block-components reference only Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

- chapter 3 computes isTooLow and message in their own section instead of deferring to the whole file - the shopware/shopware tooling note becomes an info box - reword the chapter 1 prerequisites and the demo data intro Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot

Copilot review overview

🟡 Changes recommended

The tutorial contains incorrect price calculations and contradictory API guidance, and it presents an unreleased version as currently available.

Review effort: Balanced
Findings: 3 · 4

Open (7)

Find product prices by the default currency ID · New
Select prices by the default currency ID · New
Declare Shopware core compatibility in the plugin manifest · New
Make the parent block requirement conditional · New
Align the documented locale parameter type with runtime behavior · New
Conditionally require sw-block-parent in extending blocks · New
Clarify when sw-block-parent is required · New

What changed in this PR

Adds comprehensive documentation for the experimental Administration Single File Component extension system, addressing shopware/shopware#20191.

Changes:

Adds a five-part tutorial, API reference, roadmap, troubleshooting, and internals documentation.
Cross-links existing Administration guides to the new SFC documentation.
Adds supporting terminology and experimental-version notices.

File	Description
`.wordlist.txt`	Adds SFC terminology
`snippets/guide/administration_sfc_experimental.md`	Adds shared experimental warning
`guides/upgrades-migrations/administration/vue-native.md`	Updates migration guidance
`guides/plugins/plugins/administration/index.md`	Links the SFC guide
`guides/plugins/plugins/administration/templates-styling/writing-templates.md`	Introduces native blocks
`guides/plugins/plugins/administration/templates-styling/adding-snippets.md`	Documents SFC translations
`guides/plugins/plugins/administration/module-component-management/customizing-components.md`	Links override tutorial
`guides/plugins/plugins/administration/module-component-management/add-custom-component.md`	Links component tutorial
`guides/plugins/plugins/administration/mixins-directives/using-mixins.md`	Introduces composable replacements
`guides/plugins/plugins/administration/single-file-components/index.md`	Adds SFC landing page
`guides/plugins/plugins/administration/single-file-components/roadmap.md`	Documents timeline and limitations
`guides/plugins/plugins/administration/single-file-components/troubleshooting.md`	Adds troubleshooting reference
`guides/plugins/plugins/administration/single-file-components/internals.md`	Explains build/runtime internals
`guides/plugins/plugins/administration/single-file-components/tutorial/index.md`	Adds tutorial overview
`guides/plugins/plugins/administration/single-file-components/tutorial/set-up-your-environment.md`	Creates development environment
`guides/plugins/plugins/administration/single-file-components/tutorial/your-first-override.md`	Demonstrates an override
`guides/plugins/plugins/administration/single-file-components/tutorial/read-the-base-component.md`	Reads and extends component state
`guides/plugins/plugins/administration/single-file-components/tutorial/build-your-own-component.md`	Builds a native component
`guides/plugins/plugins/administration/single-file-components/tutorial/make-it-extensible.md`	Adds extension points
`guides/plugins/plugins/administration/single-file-components/api-reference/index.md`	Adds API overview
`guides/plugins/plugins/administration/single-file-components/api-reference/macros/index.md`	Summarizes macros
`guides/plugins/plugins/administration/single-file-components/api-reference/macros/sw-define-public.md`	Documents public bindings
`guides/plugins/plugins/administration/single-file-components/api-reference/macros/sw-define-override.md`	Documents override bindings
`guides/plugins/plugins/administration/single-file-components/api-reference/block-components/index.md`	Summarizes block components
`guides/plugins/plugins/administration/single-file-components/api-reference/block-components/sw-block.md`	Documents extension blocks
`guides/plugins/plugins/administration/single-file-components/api-reference/block-components/sw-block-parent.md`	Documents parent rendering
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/index.md`	Indexes composables
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-cms-element.md`	Documents CMS element state
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-cms-state.md`	Documents CMS editor state
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-inline-snippet.md`	Documents inline snippets
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-listing.md`	Documents listing state
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-media-grid-listener.md`	Documents media selection
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-media-sidebar-modal.md`	Documents media modals
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-notification.md`	Documents notifications
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-notification-translation.md`	Documents notification translation
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-placeholder.md`	Documents translated placeholders
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-position.md`	Documents entity positioning
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-rule-between-operator.md`	Documents between conditions
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-rule-container.md`	Documents rule containers
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-salutation.md`	Documents salutation formatting
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-sw-context.md`	Documents override context
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-sw-previous-state.md`	Documents previous state
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-sw-props.md`	Documents override props
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-translate-with-fallback.md`	Documents translation fallback
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-user-settings.md`	Documents user settings
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-validation.md`	Documents validation
`guides/plugins/plugins/administration/single-file-components/api-reference/composables/use-video-cover.md`	Documents video covers

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

docs(administration): add entrypoint for sfc documentation

d3574e8

Gerrit Weiermann (gweiermann) and others added 24 commits September 10, 2026 17:56

docs: do not show imports for the override composables

5dac8de

`useSwPreviousState()`, `useSwProps()` and `useSwContext()` are injected by the setup transform like the macros are, so an import line would be wrong to copy into a file. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Merge the tutorial branch

c911de5

docs(administration): drop the Vue composables section from the index

9edefee

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs(administration): add timeline to index page

dbceeaf

docs(administration): improve index page

7136325

docs(administration): add link hint

4429c8a

docs(administration): fix markdown

b814ce8

Merge branch 'main' into docs/admin-vue-sfc-extensions

db28bf7

docs(administration): fix table alignment

e8591ae

docs(administration): fix table alignments

074b2db

Jannis Leifeld (jleifeld) mentioned this pull request Sep 16, 2026

Make it easier to discover "sw-block" names shopware/shopware#20499

Open

docs: add some improvements, cross references, etc.

258b08c

Gerrit Weiermann (gweiermann) assigned Jannis Leifeld (jleifeld) Sep 17, 2026

Gerrit Weiermann (gweiermann) assigned Gerrit Weiermann (gweiermann) and David Traum (davidtraum) Sep 17, 2026

David Traum (davidtraum) added 4 commits October 2, 2026 11:55

docs: add discussion link

500c707

docs: update composable imports

943a9d7

docs: update v-if usage on sw-block-extends

2319277

docs: fix code example

100cae5

This was referenced Oct 5, 2026

[Admin] Extensions can't use vue-router or vue-i18n in Composition API components shopware/shopware#21125

Open

fix(administration): discover new override files in the running dev server shopware/shopware#21239

Draft

Gerrit Weiermann (gweiermann) and others added 4 commits October 5, 2026 18:29

docs: explain cache clear for new admin snippets

9d42471

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs: use console commands for extension tooling

a821620

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs: update product menu path

624b5bf

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs: describe what actually changes at the chapter 4 checkpoint

a1897dd

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Gerrit Weiermann (gweiermann) mentioned this pull request Oct 6, 2026

feat(administration): expose useI18n, useRoute and useRouter via shopware:composables shopware/shopware#21246

Draft

4 of 5 tasks

Jannis Leifeld (jleifeld) and others added 9 commits October 6, 2026 09:38

docs: fix spellcheck in the composables reference

f133eea

docs: show the by-name registration before the route exception

2fab96c

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Gerrit Weiermann (gweiermann) approved these changes Oct 7, 2026

View reviewed changes

Gerrit Weiermann (gweiermann) marked this pull request as ready for review October 7, 2026 14:27

Merge branch 'main' into docs/admin-vue-sfc-extensions

c165480

Copilot AI balanced review requested due to automatic review settings October 7, 2026 14:28

Copilot started reviewing on behalf of David Traum (davidtraum) October 7, 2026 14:28 View session

Copilot AI reviewed Oct 7, 2026

View reviewed changes

docs: update faq for vue-native migration

0c9892c

Navigation Menu

Repository navigation

docs(administration): Vue single file component extension documentation - #2503

docs(administration): Vue single file component extension documentation#2503
David Traum (davidtraum) wants to merge 45 commits into
mainfrom
docs/admin-vue-sfc-extensions

David Traum (davidtraum) commented Sep 8, 2026

Uh oh!

shopware-dev-docs-connector Bot commented Sep 8, 2026 •

edited

Loading

Uh oh!

Gerrit Weiermann (gweiermann) commented Sep 17, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

David Traum (davidtraum) commented Sep 8, 2026

Summary

Related links

Uh oh!

shopware-dev-docs-connector Bot commented Sep 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Developer Docs healthcheck

Uh oh!

Gerrit Weiermann (gweiermann) commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Blocked by:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

shopware-dev-docs-connector Bot commented Sep 8, 2026 •

edited

Loading

Gerrit Weiermann (gweiermann) commented Sep 17, 2026 •

edited

Loading