docs: explain plugin scaffolding and generator troubleshooting - #2473
Open
somethings (lasomethingsomething) wants to merge 23 commits into
Open
docs: explain plugin scaffolding and generator troubleshooting#2473somethings (lasomethingsomething) wants to merge 23 commits into
somethings (lasomethingsomething) wants to merge 23 commits into
Conversation
Developer Docs healthcheckStatus: Completed with |
Adds Storefront controller lifecycle guide explaining how controller class, route attributes, routing import, service registration, and cache connect. Warns about generated plugin base class name mismatches when plugin name does not follow UpperCamelCase, which can cause PluginBaseClassNotFoundException during installation even when plugin:refresh succeeds. Links lifecycle guides from index pages and remaining documentation. Aligns all lifecycle pages with repo formatting conventions (frontmatter blank lines, consistent command formatting, improved phrasing). Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Copilot started work on behalf of
somethings (lasomethingsomething)
August 21, 2026 16:31
View session
Co-authored-by: lasomethingsomething <2453640+lasomethingsomething@users.noreply.github.com>
somethings (lasomethingsomething)
marked this pull request as ready for review
August 24, 2026 14:18
Contributor
📢 Developer Announcement RecommendationRecommendation: ❌ No Announcement Recommended No developer announcement signals were detected.
|
Copilot started reviewing on behalf of
somethings (lasomethingsomething)
August 24, 2026 14:18
View session
somethings (lasomethingsomething)
requested review from
a team,
Anne (Ant1gua),
Micha Hobert (Isengo1989),
Malte Janz (MalteJanz),
Soner (shyim) and
Tomasz Turkowski (tturkowski)
and removed request for
a team
August 24, 2026 14:19
Contributor
There was a problem hiding this comment.
Pull request overview
This PR strengthens the Shopware plugin documentation by explaining how generator output typically represents coordinated framework wiring (registration, discovery, build/runtime), helping readers interpret scaffolded files as connected parts rather than isolated artifacts.
Changes:
- Adds short “generator output is a connected chain” explanations across Storefront JS, controllers, scheduled tasks, Store API routes, and Administration modules.
- Extends the “Creating Plugins” guide with troubleshooting context emphasizing wiring/discovery/build boundaries.
- Refines a few in-guide code comments to better align with the narrative (e.g., “Register your custom Storefront plugin”).
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| guides/plugins/plugins/storefront/javascript/add-custom-javascript.md | Adds generator-chain context for main.js/plugin class/selector and updates code comment wording. |
| guides/plugins/plugins/storefront/controllers/add-custom-controller.md | Adds info callouts explaining how controllers relate to service registration and route discovery. |
| guides/plugins/plugins/plugin-fundamentals/add-scheduled-task.md | Adds explanation of scheduled task vs handler roles and generator wiring implications. |
| guides/plugins/plugins/plugin-base-guide.md | Adds a generator-output framing paragraph to connect the base guide to focused feature guides. |
| guides/plugins/plugins/framework/store-api/add-store-api-route.md | Adds info callouts clarifying route/service/routes.php responsibilities and debugging interpretation. |
| guides/plugins/plugins/creating-plugins.md | Adds troubleshooting guidance about generated output and reinforces version/adaptation context. |
| guides/plugins/plugins/administration/module-component-management/add-custom-module.md | Adds info callouts explaining how module entrypoints, registration, snippets, and build relate. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
69
to
+71
| Shopware is automatically looking for a `main.js` file in a directory `<plugin root>/src/Resources/app/storefront/src`, which then will be loaded automatically. Consider this to be your main storefront JavaScript entrypoint. | ||
|
|
||
| The entry point, plugin class, and optional DOM selector form one runtime chain. A generator creates these pieces together: `main.js` imports and registers the class, the selector connects it to rendered markup when one is used, and the Storefront build produces the asset the browser loads. Keeping that relationship in mind makes generated output easier to adapt without treating each file as an independent feature. |
| This is done with a `routes.php` file at `<plugin root>/src/Resources/config/` location. | ||
| Take a look at the official [Symfony documentation](https://symfony.com/doc/current/routing.html) about routes and how they are registered. | ||
|
|
||
| The route import is the discovery half of the feature: it tells Shopware which controller files to inspect for route attributes. A controller can therefore exist and be a valid service while still not expose a URL until its route is imported. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds context explaining how Shopware plugin generators produce coordinated framework features, rather than isolated files.
New info is based on a hands-on walkthrough of current
bin/console plugin:createscaffolding and cross-checked against currentshopware/shopwarescaffolding generators and the proposedshopware-cli extension creategenerator epics: shopware/shopware-cli#1255, shopware/shopware-cli#1280.The goal is to bridge the gap between “the generator created these files” and “here’s how those pieces work together”, without adding another workflow or duplicating existing guides.