Purpose
Bootstrap a new backend dynamic plugin for Red Hat Developer Hub (RHDH). RHDH is the enterprise-ready Backstage application that supports dynamic plugins - plugins that can be installed or uninstalled without rebuilding the application.
Note: This skill covers backend plugins only. Frontend dynamic plugins have different requirements (Scalprum configuration, mount points, dynamic routes) and are covered in a separate skill.
When to Use
Use this skill when creating a new backend plugin intended for RHDH dynamic plugin deployment. This includes:
- New backend API plugins
- Backend modules for existing plugins (e.g.,
catalog-backend-module-*) - Scaffolder actions and templates
- Catalog processors and providers
- Authentication modules
- Any server-side functionality for RHDH
Do NOT use this skill for:
- Frontend plugins (UI components, pages, cards)
- Frontend plugin wiring (mount points, dynamic routes)
- Themes or frontend customizations
Prerequisites
Before starting, ensure the following are available:
- Node.js 22+ and Yarn
- Container runtime (
podmanordocker) - Access to a container registry (e.g., quay.io) for publishing
Workflow Overview
- Determine RHDH Version - Identify target RHDH version for compatibility
- Scaffold App and Plugin - Create Backstage app and generate backend plugin
- Implement Plugin Logic - Write the plugin code using new backend system
- Export and Package - Build, export, and package using RHDH CLI (see export-and-package skill)
- Configure for RHDH - Create dynamic-plugins.yaml configuration
Step 1: Determine RHDH Version
Check the target RHDH version and find the compatible Backstage version. Consult ../rhdh/references/versions.md file for the version compatibility matrix and available RHDH versions.
Ask the user which RHDH version they are targeting if not specified.
Step 2: Scaffold App and Plugin
Run the scaffold script from the directory where the app should be created:
python scripts/scaffold.py \
--rhdh-version 1.9 \
--plugin-id my-plugin
Run python scripts/scaffold.py --help for all options (e.g., --path, --create-app-version, --json).
The Backstage app exists only to provide the correct CLI version for plugin generation. All development and testing happens in the plugin directory.
The generated plugin structure:
plugins/<plugin-id>-backend/
├── src/
│ ├── index.ts # Main entry point
│ ├── plugin.ts # Plugin definition (new backend system)
│ └── service/
│ └── router.ts # Express router
├── package.json
└── README.md
Step 3: Implement Plugin Logic
Backend plugins must use the new backend system for dynamic plugin compatibility. The plugin entry point should export a default using createBackendPlugin() or createBackendModule().
Example plugin structure (src/plugin.ts):
import {
coreServices,
createBackendPlugin,
} from '@backstage/backend-plugin-api';
import { createRouter } from './service/router';
export const myPlugin = createBackendPlugin({
pluginId: 'my-plugin',
register(env) {
env.registerInit({
deps: {
httpRouter: coreServices.httpRouter,
logger: coreServices.logger,
config: coreServices.rootConfig,
},
async init({ httpRouter, logger, config }) {
httpRouter.use(
await createRouter({
logger,
config,
}),
);
httpRouter.addAuthPolicy({
path: '/health',
allow: 'unauthenticated',
});
},
});
},
});
export default myPlugin;
The src/index.ts must export the plugin as default:
export { default } from './plugin';
Build and verify the plugin compiles:
cd plugins/<plugin-id>-backend
yarn build
Step 4: Export and Package
Export the plugin as a dynamic plugin and package it for deployment. For detailed export and packaging options, see the export-and-package skill.
Quick Export
cd plugins/<plugin-id>-backend
npx @red-hat-developer-hub/cli@latest plugin export
This creates dist-dynamic/ with the dynamic plugin package.
Quick Package and Push
npx @red-hat-developer-hub/cli@latest plugin package \
--tag quay.io/<namespace>/<plugin-name>:v0.1.0
podman push quay.io/<namespace>/<plugin-name>:v0.1.0
For advanced options (dependency handling, multi-plugin bundles, tgz/npm packaging), consult the export-and-package skill.
Step 5: Configure for RHDH
Create the dynamic plugin configuration for RHDH. Add to dynamic-plugins.yaml:
plugins:
- package: oci://quay.io/<namespace>/<plugin-name>:v0.1.0!<plugin-id>-backend-dynamic
disabled: false
pluginConfig:
# Plugin-specific configuration (optional)
myPlugin:
someOption: value
For local development/testing, copy dist-dynamic to RHDH's dynamic-plugins-root:
cp -r dist-dynamic /path/to/rhdh/dynamic-plugins-root/<plugin-id>-backend-dynamic
Windows note: Use
xcopy /E /I dist-dynamic \path\to\rhdh\dynamic-plugins-root\<plugin-id>-backend-dynamicorrobocopy dist-dynamic \path\to\rhdh\dynamic-plugins-root\<plugin-id>-backend-dynamic /Einstead ofcp -r.
See examples/dynamic-plugins.yaml for a complete configuration example.
Common Issues
Plugin Not Loading
- Verify plugin uses new backend system (
createBackendPlugin) - Check plugin is exported as default export
- Ensure version compatibility with target RHDH
Dependency Conflicts
- Use
--shared-packageto exclude problematic shared deps - Use
--embed-packageto bundle required deps
Build Failures
- Run
yarn tscto check TypeScript errors before export - Ensure all
@backstage/*versions match target RHDH
Additional Resources
Related Skills
- export-and-package - Complete export/packaging workflow (OCI, tgz, npm)
Reference Files
rhdh/references/versions.md- Complete version compatibility matrix
Example Files
examples/dynamic-plugins.yaml- Example RHDH plugin configuration