Update documentation with why frontend wiring is necessary

Author: GitHub Actions

assemblies/dynamic-plugins/assembly-front-end-plugin-wiring.adoc

@@ -6,6 +6,18 @@
 
 You can configure front-end plugins to customize icons, integrate components at mount points, and provide or replace utility APIs.
 
+// Frontend plugin wiring
+include::../modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc[leveloffset=+1]
+
+// Understand frontend wiring
+include::../modules/dynamic-plugins/con-understand-why-wiring-is-required-for-plugin-deployment.adoc[leveloffset=+2]
+
+// When you skip frontend wiring
+include::../modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc[leveloffset=+2]
+
+// When to perform frontend wiring
+include::../modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc[leveloffset=+2]
+
 // Extending the internal icon catalog
 include::../modules/dynamic-plugins/proc-extending-internal-icon-catalog.adoc[leveloffset=+1]
 

modules/dynamic-plugins/con-frontend-dynamic-plugin-wiring.adoc

@@ -0,0 +1,7 @@
+:_mod-docs-content-type: CONCEPT
+[id="con-frontend-dynamic-plugin-wiring_{context}"]
+= Frontend plugin wiring
+
+Frontend plugin wiring allows dynamically loaded frontend plugins to integrate their functionality, such as new pages, UI extensions, icons, and APIs, into {product}.
+
+Dynamic frontend plugins are loaded at runtime. Therefore, the core application must discover and connect the exported assets of the plugin to the appropriate locations and systems within the user interface.

modules/dynamic-plugins/con-identify-and-register-plugin-features-for-application-use.adoc

@@ -0,0 +1,90 @@
+:_mod-docs-content-type: CONCEPT
+[id="con-identify-and-register-plugin-features-for-application-use_{context}"]
+
+= Identify and register plugin features for application use
+
+Frontend wiring must be performed whenever a dynamic frontend plugin exports a feature that needs to be integrated into the main {product-custom-resource-type} application UI.
+
+Wiring is specifically required for, but not limited to, the following scenarios:
+
+[cols="1,1,2"]
+|===
+|Scenario|Wiring configuration|Description
+
+|Enabling new pages/Routes
+|`dynamicRoutes`
+|When adding a full new page and route to the application (for example, `/my-plugin`).
+
+|Extending existing pages/UI
+|`mountPoints`
+|When injecting custom widgets, cards, listeners, or providers into existing pages (for example, the Catalog entity page).
+
+|Customizing sidebar navigation
+|`dynamicRoutes.menuItem`, `menuItems`
+|When adding a new entry to the main sidebar or customizing its order/nesting.
+
+|Integrating custom APIs
+|`apiFactories`
+|When a plugin provides a custom utility API implementation or overrides an existing one.
+
+|Extending entity tabs
+|`entityTabs`
+|When adding a new tab to the Catalog entity view or customizing an existing one.
+
+|Binding routes
+|`routeBindings`
+|When linking a route in one plugin to an external route defined by another plugin.
+
+|Adding icons/Theming
+|`appIcons`, `themes`
+|When adding custom icons to the application catalog or defining a new {product-custom-resource-type} theme.
+
+|Scaffolder/TechDocs extensions
+|`scaffolderFieldExtensions`, `techdocsAddons`
+|When exposing custom field extensions for the Scaffolder or new Addons for TechDocs.
+
+|Translation resources
+|`translationResources`
+|When providing new translation files or overriding default translations of a plugin.
+|===
+
+.Example of Frontend wiring workflow
+
+The fundamental process for frontend wiring involves configuring the plugin exports in the `{my-app-config-file}` or a dedicated `dynamic-plugins-config.yaml` file.
+
+The dynamic plugin is built to expose components, routes, or APIs. A plugin component (`FooPluginPage`) is exported as an export from a module (for example, `PluginRoot`).
+
+The application administrator defines the wiring in the configuration file, using the plugin package name to register the exports. This step adds a new full page with a sidebar link.
+
+[source,yaml]
+.dynamic-plugins-config.yaml
+----
+# dynamic-plugins-config.yaml
+plugins:
+  - plugin: <plugin_path_or_url>
+    disabled: false
+    pluginConfig:
+      dynamicPlugins:
+        frontend:
+          my-plugin-package-name: # The plugin's unique package name
+            dynamicRoutes: # Wiring for a new page/route
+              - path: /my-new-page # The desired URL path
+                importName: FooPluginPage # The exported component name
+                menuItem: # Wiring for the sidebar entry
+                  icon: favorite # A registered icon name
+                  text: My Custom Page
+----
+
+The application follows these steps when it loads:
+
+. It parses the `dynamic-plugins-config.yaml`.
+. It uses the `<plugin_path_or_url>` to download the plugin bundle using the dynamic loading mechanism.
+. If the plugin exports the plugin object, the application adds this to the list of plugins provided to the Backstage `createApp` API, registering the plugin properly with the Backstage frontend application.
+. It uses the configuration block (`dynamicRoutes`, `menuItem`) to:
+* Add an entry to the internal router mapping `/my-new-page` to the `FooPluginPage` component.
+* Construct and render a new sidebar item labeled _My Custom Page_, pointing to the `/my-new-page` route.
+
+[NOTE]
+====
+If the configuration is missing, steps 1 and 2 might still happen, but the final wiring in step 3 is skipped, and you do not see any change.
+====

modules/dynamic-plugins/con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible.adoc

@@ -0,0 +1,13 @@
+:_mod-docs-content-type: CONCEPT
+[id="con-troubleshoot-why-a-dynamically-loaded-plugin-is-not-visible_{context}"]
+
+= Troubleshoot why a dynamically loaded plugin is not visible
+
+If you skip frontend wiring, the plugin is discovered but not loaded into the application frontend. As a result, the plugin features do not appear or function. This is expected because backend plugins are automatically discovered and loaded, but frontend plugins are only loaded based on the list defined in the `dynamicPlugins.frontend` configuration.
+
+You can expect the following behavior when you skip frontend wiring:
+
+Functionality is disabled:: The Backstage application does not know how to integrate the plugin exports.
+Invisible components:: New pages, sidebar links, or custom cards are not rendered.
+Unregistered APIs:: Custom utility APIs or API overrides provided by the plugin fail to register in the application API system, causing plugins or components to fail.
+Unused assets:: Icons, translations, and themes are not registered or made available for use.

modules/dynamic-plugins/con-understand-why-wiring-is-required-for-plugin-deployment.adoc

@@ -0,0 +1,16 @@
+:_mod-docs-content-type: CONCEPT
+[id="con-understand-why-wiring-is-required-for-plugin-deployment_{context}"]
+
+= Understand why wiring is required for plugin deployment
+
+Frontend wiring bridges the gap between the dynamically loaded plugin code and the structured components of the {product-short} application.
+
+Frontend components need instructions on where to be registered in the application UI. The application does not automatically know where the UI components of a plugin must appear.
+
+Wiring tells the application the following:
+
+* "Add new pages and routes to the main application." (using `dynamicRoutes`)
+* "Inject custom components into existing UI pages." (using `mountPoints`)
+* "Customize the application with new icons or themes." (using `appIcons`)
+
+Wiring configuration, typically located in `{my-app-config-file}` or `dynamic-plugins-config.yaml`, provides the application with the metadata (including the component names, paths, and integration points) needed to render and use the plugin features.