feat(app): dynamic Techdocs addons

.rhdh/docker/Dockerfile

@@ -85,6 +85,7 @@ COPY $EXTERNAL_SOURCE_NESTED/dynamic-plugins/wrappers/pagerduty-backstage-plugin
 COPY $EXTERNAL_SOURCE_NESTED/dynamic-plugins/wrappers/immobiliarelabs-backstage-plugin-gitlab/package.json ./dynamic-plugins/wrappers/immobiliarelabs-backstage-plugin-gitlab/package.json
 COPY $EXTERNAL_SOURCE_NESTED/dynamic-plugins/wrappers/immobiliarelabs-backstage-plugin-gitlab-backend-dynamic/package.json ./dynamic-plugins/wrappers/immobiliarelabs-backstage-plugin-gitlab-backend-dynamic/package.json
 COPY $EXTERNAL_SOURCE_NESTED/dynamic-plugins/wrappers/backstage-plugin-techdocs/package.json ./dynamic-plugins/wrappers/backstage-plugin-techdocs/package.json
+COPY $EXTERNAL_SOURCE_NESTED/dynamic-plugins/wrappers/backstage-plugin-techdocs-module-addons-contrib/package.json ./dynamic-plugins/wrappers/backstage-plugin-techdocs-module-addons-contrib/package.json
 COPY $EXTERNAL_SOURCE_NESTED/dynamic-plugins/wrappers/backstage-plugin-techdocs-backend-dynamic/package.json ./dynamic-plugins/wrappers/backstage-plugin-techdocs-backend-dynamic/package.json
 COPY $EXTERNAL_SOURCE_NESTED/dynamic-plugins/wrappers/backstage-plugin-signals/package.json ./dynamic-plugins/wrappers/backstage-plugin-signals/package.json
 COPY $EXTERNAL_SOURCE_NESTED/dynamic-plugins/wrappers/backstage-plugin-signals-backend-dynamic/package.json ./dynamic-plugins/wrappers/backstage-plugin-signals-backend-dynamic/package.json

app-config.dynamic-plugins.yaml

@@ -471,6 +471,9 @@ dynamicPlugins:
             props:
               name: Documentation
               icon: docs
+    backstage.plugin-techdocs-module-addons-contrib:
+      techdocsAddons:
+        - importName: ReportIssue
     backstage-community.plugin-tech-radar:
       apiFactories:
         - importName: TechRadarApi

docker/Dockerfile

@@ -86,6 +86,7 @@
 COPY $EXTERNAL_SOURCE_NESTED/dynamic-plugins/wrappers/immobiliarelabs-backstage-plugin-gitlab/package.json ./dynamic-plugins/wrappers/immobiliarelabs-backstage-plugin-gitlab/package.json
 COPY $EXTERNAL_SOURCE_NESTED/dynamic-plugins/wrappers/immobiliarelabs-backstage-plugin-gitlab-backend-dynamic/package.json ./dynamic-plugins/wrappers/immobiliarelabs-backstage-plugin-gitlab-backend-dynamic/package.json
 COPY $EXTERNAL_SOURCE_NESTED/dynamic-plugins/wrappers/backstage-plugin-techdocs/package.json ./dynamic-plugins/wrappers/backstage-plugin-techdocs/package.json
+COPY $EXTERNAL_SOURCE_NESTED/dynamic-plugins/wrappers/backstage-plugin-techdocs-module-addons-contrib/package.json ./dynamic-plugins/wrappers/backstage-plugin-techdocs-module-addons-contrib/package.json
 COPY $EXTERNAL_SOURCE_NESTED/dynamic-plugins/wrappers/backstage-plugin-techdocs-backend-dynamic/package.json ./dynamic-plugins/wrappers/backstage-plugin-techdocs-backend-dynamic/package.json
 COPY $EXTERNAL_SOURCE_NESTED/dynamic-plugins/wrappers/backstage-plugin-signals/package.json ./dynamic-plugins/wrappers/backstage-plugin-signals/package.json
 COPY $EXTERNAL_SOURCE_NESTED/dynamic-plugins/wrappers/backstage-plugin-signals-backend-dynamic/package.json ./dynamic-plugins/wrappers/backstage-plugin-signals-backend-dynamic/package.json
@@ -229,7 +230,7 @@
 COPY --from=build $CONTAINER_SOURCE/dynamic-plugins/dist/ ./dynamic-plugins/dist/
 
 # RHIDP-4220 - make Konflux preflight and EC checks happy - [check-container] Create a directory named /licenses and include all relevant licensing
 COPY $EXTERNAL_SOURCE/LICENSE /licenses/
 
 # Copy script to gather dynamic plugins; copy embedded dynamic plugins to root folder; fix permissions
 COPY docker/install-dynamic-plugins.py docker/install-dynamic-plugins.sh ./
@@ -257,7 +258,7 @@
 
 # gGVM6sYRK0D0ndVX22BOtS7NRcxPej8t is key for dev environment
 # Upstream only - Use dev key in all branches
 ENV SEGMENT_WRITE_KEY=gGVM6sYRK0D0ndVX22BOtS7NRcxPej8t
 ENV SEGMENT_TEST_MODE=false
 
 # RHIDP-2217: corporate proxy support (configured using 'global-agent' for 'node-fetch' calls and 'undici' for 'fetch' calls)

docs/dynamic-plugins/export-derived-package.md

@@ -43,7 +43,7 @@ If you are developing your own plugin that is going to be used as a dynamic plug
 To be compatible with the showcase dynamic plugin support, and used as dynamic plugins, existing plugins must be based on, or compatible with, the new backend system, as well as rebuilt with a dedicated CLI command.
 
 The new backend system standard entry point (created using `createBackendPlugin()` or `createBackendModule()`) should be exported as the default export of either the main package or of an `alpha` package (if the new backend support is still provided as `alpha` APIs). This doesn't add any additional requirement on top of the standard plugin development guidelines of the new backend system.
-For a practical example of a dynamic plugin entry point built upon the new backend system, please refer to the [Janus plugins repository](https://github.com/backstage/community-plugins/blob/main/workspaces/3scale/plugins/3scale-backend/src/module.ts).
+For a practical example of a dynamic plugin entry point built upon the new backend system, please refer to the [Backstage community plugins repository](https://github.com/backstage/community-plugins/blob/main/workspaces/3scale/plugins/3scale-backend/src/module.ts).
 
 The dynamic export mechanism identifies private, non-backstage dependencies, and sets the `bundleDependencies` field in the `package.json` file for them, so that the dynamic plugin package can be published as a self-contained package, along with its private dependencies bundled in a private `node_modules` folder.
 
@@ -130,4 +130,30 @@ export const DynamicEntityTechdocsContent = {
 };
 ```
 
+To include components provided by other dynamic plugins inside static JSX as element children with your dynamically imported component, you can extract them from [dynamicConfig](https://github.com/redhat-developer/rhdh/blob/main/packages/app/src/components/DynamicRoot/DynamicRootContext.tsx#L115) that is passed to the `staticJSXContent`:
+
+```tsx
+// Used by a static plugin
+export const EntityTechdocsContent = () => {...}
+
+// Custom function that extracts addon components from dynamic config
+function getTechdocsAddonComponents(dynamicConfig: DynamicConfig) {
+  const techdocsAddonsData = dynamicConfig?.techdocsAddons ?? [];
+  return techdocsAddonsData.map(
+    ({ scope, module, importName, Component, config }) => (
+      <Component key={`${scope}-${module}-${importName}`} {...config.props} />
+    ),
+  );
+}
+
+// Used by a dynamic plugin
+export const DynamicEntityTechdocsContent = {
+  element: EntityTechdocsContent,
+  staticJSXContent: (dynamicConfig: DynamicConfig) => {
+    const children = getTechdocsAddonComponents(dynamicConfig);
+    return <TechDocsAddons>{children}</TechDocsAddons>;
+  },
+};
+```
+
 Important part of the frontend dynamic plugins is its layout configuration (bindings and routes). For more information on how to configure bindings and routes, see [Frontend Plugin Wiring](frontend-plugin-wiring.md).

docs/dynamic-plugins/frontend-plugin-wiring.md

@@ -581,6 +581,39 @@ A plugin can specify multiple field extensions, in which case each field extensi
 - `importName` is an optional import name that should reference the value returned the scaffolder field extension API
 - `module` is an optional argument which allows you to specify which set of assets you want to access within the plugin. If not provided, the default module named `PluginRoot` is used. This is the same as the key in `scalprum.exposedModules` key in plugin's `package.json`.
 
+## Provide custom TechDocs addons
+
+The Backstage TechDocs component supports specifying [custom addons](https://backstage.io/docs/features/techdocs/addons/) to extend TechDocs functionality, like rendering a component or accessing and manipulating TechDocs's DOM.
+
+Here is an example of creating an addon:
+
+```typescript
+export const ExampleAddon = techdocsPlugin.provide(
+  createTechDocsAddonExtension({
+    name: "ExampleAddon",
+    location: TechDocsAddonLocations.Content,
+    component: ExampleTestAddon,
+  }),
+);
+```
+
+These components can be contributed by plugins by exposing the TechDocs addon component via the `techdocsAddons` configuration:
+
+```yaml
+dynamicPlugins:
+  frontend:
+    <package_name>: # same as `scalprum.name` key in plugin's `package.json`
+      techdocsAddons:
+        - importName: ExampleAddon
+          config:
+            props: ... # optional, React props to pass to the addon
+```
+
+A plugin can specify multiple addons, in which case each techdocsAddon will need to supply an `importName` for each addon.
+
+- `importName` name of an exported `Addon` component
+- `module` is an optional argument which allows you to specify which set of assets you want to access within the plugin. If not provided, the default module named `PluginRoot` is used. This is the same as the key in `scalprum.exposedModules` key in plugin's `package.json`.
+
 ## Add a custom Backstage theme or replace the provided theme
 
 The look and feel of a Backstage application is handled by Backstage theming. Out of the box Developer Hub provides a theme with a number of [configuration overrides](../customization.md) that allow for user customization. It's also possible to provide additional Backstage themes as well as replace the out of box Developer Hub themes from a dynamic plugin.

dynamic-plugins.default.yaml

@@ -653,6 +653,14 @@ plugins:
                   props:
                     name: Documentation
                     icon: docs
+  - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
+    disabled: false
+    pluginConfig:
+      dynamicPlugins:
+        frontend:
+          backstage.plugin-techdocs-module-addons-contrib:
+            techdocsAddons:
+              - importName: ReportIssue
 
   # PagerDuty
   - package: ./dynamic-plugins/dist/pagerduty-backstage-plugin

dynamic-plugins/wrappers/backstage-plugin-techdocs-module-addons-contrib/.eslintignore

@@ -0,0 +1,2 @@
+dist-dynamic
+dist-scalprum

dynamic-plugins/wrappers/backstage-plugin-techdocs-module-addons-contrib/.eslintrc.js

@@ -0,0 +1,12 @@
+const backstageConfig = require('@backstage/cli/config/eslint-factory')(
+  __dirname,
+);
+
+module.exports = {
+  ...backstageConfig,
+  rules: {
+    ...backstageConfig.rules,
+    'react/react-in-jsx-scope': 'off',
+    'react/jsx-uses-react': 'off',
+  },
+};

dynamic-plugins/wrappers/backstage-plugin-techdocs-module-addons-contrib/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "backstage-plugin-techdocs-module-addons-contrib",
+  "version": "1.1.20",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "frontend-plugin-module",
+    "supported-versions": "1.35.1",
+    "pluginId": "techdocs",
+    "pluginPackage": "backstage-plugin-techdocs"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "tsc": "tsc",
+    "build": "backstage-cli package build",
+    "lint:check": "backstage-cli package lint",
+    "test": "backstage-cli package test --passWithNoTests --coverage",
+    "clean": "backstage-cli package clean",
+    "export-dynamic": "janus-cli package export-dynamic-plugin --in-place",
+    "export-dynamic:clean": "run export-dynamic --clean"
+  },
+  "dependencies": {
+    "@backstage/plugin-techdocs-module-addons-contrib": "1.1.20",
+    "@backstage/plugin-techdocs-react": "1.2.13",
+    "@material-ui/core": "4.12.4",
+    "jss": "10.10.0"
+  },
+  "peerDependencies": {
+    "react": "16.13.1 || ^17.0.0 || ^18.0.0"
+  },
+  "devDependencies": {
+    "@backstage/cli": "0.29.6",
+    "@janus-idp/cli": "3.2.0",
+    "react": "18.3.1",
+    "typescript": "5.7.3"
+  },
+  "files": [
+    "dist",
+    "dist-scalprum"
+  ],
+  "scalprum": {
+    "name": "backstage.plugin-techdocs-module-addons-contrib",
+    "exposedModules": {
+      "PluginRoot": "./src/index.ts"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/redhat-developer/rhdh",
+    "directory": "dynamic-plugins/wrappers/backstage-plugin-techdocs-module-addons-contrib"
+  },
+  "maintainers": [
+    "@janus-idp/maintainers-showcase"
+  ],
+  "author": "Red Hat",
+  "homepage": "https://red.ht/rhdh",
+  "bugs": "https://issues.redhat.com/browse/RHIDP",
+  "keywords": [
+    "support:production",
+    "lifecycle:active"
+  ]
+}

dynamic-plugins/wrappers/backstage-plugin-techdocs/src/addons.tsx → dynamic-plugins/wrappers/backstage-plugin-techdocs-module-addons-contrib/src/addons.tsx

@@ -1,10 +1,16 @@
-import React from 'react';
+import {
+  ReportIssue as ReportIssueBase,
+  techdocsModuleAddonsContribPlugin,
+} from "@backstage/plugin-techdocs-module-addons-contrib";
 
-import { techdocsPlugin } from '@backstage/plugin-techdocs';
-import { createTechDocsAddonExtension, TechDocsAddonLocations } from '@backstage/plugin-techdocs-react';
+import React from "react";
 
-import { ReportIssue as ReportIssueBase } from "@backstage/plugin-techdocs-module-addons-contrib";
-import { ShadowRootStylesProvider } from './ShadowRootStylesProvider';
+import {
+  createTechDocsAddonExtension,
+  TechDocsAddonLocations,
+} from "@backstage/plugin-techdocs-react";
+
+import { ShadowRootStylesProvider } from "./ShadowRootStylesProvider";
 
 /**
  * Automatically wrap the backstage ReportIssue component with a (JSS)
@@ -44,9 +50,9 @@ const ReportIssueWrapper = () => {
   );
 };
 
-export const ReportIssue = techdocsPlugin.provide(
+export const ReportIssue = techdocsModuleAddonsContribPlugin.provide(
   createTechDocsAddonExtension<{}>({
-    name: 'ReportIssue',
+    name: "ReportIssue",
     location: TechDocsAddonLocations.Content,
     component: ReportIssueWrapper,
   }),

dynamic-plugins/wrappers/backstage-plugin-techdocs-module-addons-contrib/src/index.ts

@@ -0,0 +1,2 @@
+export * from "@backstage/plugin-techdocs-module-addons-contrib";
+export { ReportIssue } from "./addons";

dynamic-plugins/wrappers/backstage-plugin-techdocs-module-addons-contrib/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "@backstage/cli/config/tsconfig.json",
+  "include": ["src", "dev", "migrations"],
+  "exclude": ["node_modules"],
+  "compilerOptions": {
+    "outDir": "../../../dist-types/dynamic-plugins/wrappers/backstage-plugin-techdocs-module-addons-contrib",
+    "rootDir": ".",
+    "jsx": "preserve"
+  }
+}

dynamic-plugins/wrappers/backstage-plugin-techdocs-module-addons-contrib/turbo.json

@@ -0,0 +1,10 @@
+{
+  "extends": ["//"],
+  "tasks": {
+    "tsc": {
+      "outputs": [
+        "../../../dist-types/dynamic-plugins/wrappers/backstage-plugin-techdocs-module-addons-contrib/**"
+      ]
+    }
+  }
+}

dynamic-plugins/wrappers/backstage-plugin-techdocs/package.json

@@ -33,10 +33,7 @@
     "@backstage/plugin-catalog-react": "1.15.1",
     "@backstage/plugin-search-react": "1.8.5",
     "@backstage/plugin-techdocs": "1.12.2",
-    "@backstage/plugin-techdocs-module-addons-contrib": "1.1.20",
-    "@backstage/plugin-techdocs-react": "1.2.13",
-    "@material-ui/core": "4.12.4",
-    "jss": "10.10.0"
+    "@backstage/plugin-techdocs-react": "1.2.13"
   },
   "peerDependencies": {
     "react": "16.13.1 || ^17.0.0 || ^18.0.0"

dynamic-plugins/wrappers/backstage-plugin-techdocs/src/index.ts

@@ -1,6 +1,7 @@
-export * from '@backstage/plugin-techdocs';
+export * from "@backstage/plugin-techdocs";
 export {
-  EntityTechdocsContent, TechDocsReaderPage, TechdocsSearchFilter,
-  techdocsSearchType
-} from './wrapped';
-
+  EntityTechdocsContent,
+  TechDocsReaderPage,
+  TechdocsSearchFilter,
+  techdocsSearchType,
+} from "./wrapped";

dynamic-plugins/wrappers/backstage-plugin-techdocs/src/types.ts

@@ -0,0 +1,13 @@
+export type TechdocsAddon = {
+  scope: string;
+  module: string;
+  importName: string;
+  Component: React.ComponentType<React.PropsWithChildren>;
+  config: {
+    props?: Record<string, any>;
+  };
+};
+
+export type DynamicConfig = {
+  techdocsAddons: TechdocsAddon[];
+};

dynamic-plugins/wrappers/backstage-plugin-techdocs/src/utils.tsx

@@ -0,0 +1,14 @@
+import { DynamicConfig, TechdocsAddon } from "./types";
+
+function getTechdocsAddonData(dynamicConfig: DynamicConfig): TechdocsAddon[] {
+  return dynamicConfig?.techdocsAddons ?? [];
+}
+
+export function getTechdocsAddonComponents(dynamicConfig: DynamicConfig) {
+  const techdocsAddonsData = getTechdocsAddonData(dynamicConfig);
+  return techdocsAddonsData.map(
+    ({ scope, module, importName, Component, config }) => (
+      <Component key={`${scope}-${module}-${importName}`} {...config.props} />
+    ),
+  );
+}

dynamic-plugins/wrappers/backstage-plugin-techdocs/src/wrapped.tsx

@@ -2,8 +2,6 @@ import {
   EntityTechdocsContent as EntityTechdocsContentBase,
   TechDocsReaderPage as TechDocsReaderPageBase,
 } from "@backstage/plugin-techdocs";
-import { TechDocsAddons } from "@backstage/plugin-techdocs-react";
-
 import { SearchFilter, useSearch } from "@backstage/plugin-search-react";
 
 import {
@@ -12,25 +10,24 @@ import {
 } from "@backstage/plugin-catalog-react";
 
 import { useApi } from "@backstage/core-plugin-api";
-
-import { ReportIssue } from "./addons";
+import { TechDocsAddons } from "@backstage/plugin-techdocs-react";
+import { getTechdocsAddonComponents } from "./utils";
+import { type DynamicConfig } from "./types";
 
 export const TechDocsReaderPage = {
   element: TechDocsReaderPageBase,
-  staticJSXContent: (
-    <TechDocsAddons>
-      <ReportIssue />
-    </TechDocsAddons>
-  ),
+  staticJSXContent: (dynamicConfig: DynamicConfig) => {
+    const children = getTechdocsAddonComponents(dynamicConfig);
+    return <TechDocsAddons>{children}</TechDocsAddons>;
+  },
 };
 
 export const EntityTechdocsContent = {
   element: EntityTechdocsContentBase,
-  staticJSXContent: (
-    <TechDocsAddons>
-      <ReportIssue />
-    </TechDocsAddons>
-  ),
+  staticJSXContent: (dynamicConfig: DynamicConfig) => {
+    const children = getTechdocsAddonComponents(dynamicConfig);
+    return <TechDocsAddons>{children}</TechDocsAddons>;
+  },
 };
 
 export const TechdocsSearchFilter = () => {