RHDH Frontend Dynamic Plugin Bootstrap

Purpose

Bootstrap a new frontend dynamic plugin for Red Hat Developer Hub (RHDH). Frontend dynamic plugins provide UI components, pages, entity cards, themes, and visual customizations that integrate with the RHDH application shell.

Note: This skill covers frontend plugins only. Backend dynamic plugins (APIs, scaffolder actions, processors) are covered in a separate skill.

When to Use

Use this skill when creating a new frontend plugin intended for RHDH dynamic plugin deployment. This includes:

New pages and routes
Entity page cards and tabs
Sidebar menu items
Custom themes
Scaffolder field extensions
TechDocs addons
Search result types and filters
Any UI component for RHDH

Do NOT use this skill for:

Backend API plugins
Scaffolder actions (server-side)
Catalog processors or providers
Authentication modules

Prerequisites

Before starting, ensure the following are available:

Node.js 22+ and Yarn
Container runtime (podman or docker)
Access to a container registry (e.g., quay.io) for publishing

Workflow Overview

Determine RHDH Version - Identify target RHDH version for compatibility
Create Backstage App - Scaffold Backstage app with matching version
Create Frontend Plugin - Generate new frontend plugin using Backstage CLI
Implement Plugin Components - Build React components and exports
Configure Scalprum - Set up module federation for dynamic loading
Export and Package - Build, export, and package using RHDH CLI (see export-and-package skill)
Configure Plugin Wiring - Define routes, mount points, and menu items

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: Create Backstage Application

Create a new Backstage application in the current directory using the version-appropriate create-app:

# For RHDH 1.8 (adjust version as needed)
echo "backstage" | npx @backstage/create-app@0.7.3 --path .

After creation, install dependencies:

yarn install

Step 3: Decide if you want to use RHDH themes.

If you want to use RHDH themes, follow the steps below. If you don't want to use RHDH themes, skip to Step 4.

Add RHDH theme to Backstage app dependencies:

yarn workspace app add @red-hat-developer-hub/backstage-plugin-theme

Update packages/app/src/App.tsx and apply the themes to createApp:

import { getThemes } from '@red-hat-developer-hub/backstage-plugin-theme';

// ...

const app = createApp({
  apis,
  // ...
  themes: getThemes(),
});

Step 3: Create Frontend Plugin

Generate a new frontend plugin:

yarn new --select frontend-plugin --option id=<plugin-id>

The plugin will be created at plugins/<plugin-id>/

Generated structure:

plugins/<plugin-id>/
├── src/
│   ├── index.ts              # Public exports
│   ├── plugin.ts             # Plugin definition
│   ├── routes.ts             # Route references
│   └── components/
│       └── ExampleComponent/
├── package.json
└── dev/
    └── index.tsx             # Development harness

Step 4: If you decided to use RHDH themes, add RHDH Theme to Development Harness

By default, yarn start uses standard Backstage themes. To preview your plugin with RHDH styling during local development, configure the RHDH theme package.

Install Theme Package

cd plugins/<plugin-id>
yarn add @red-hat-developer-hub/backstage-plugin-theme

Configure Development Harness

Update dev/index.tsx to use RHDH themes:

import { getAllThemes } from '@red-hat-developer-hub/backstage-plugin-theme';
import { createDevApp } from '@backstage/dev-utils';
import { myPlugin, MyPage } from '../src';

createDevApp()
  .registerPlugin(myPlugin)
  .addPage({
    element: <MyPage />,
    title: 'My Plugin',
    path: '/my-plugin',
  })
  .addThemes(getAllThemes())
  .render();

Available Theme APIs

getThemes() / useThemes() - Latest RHDH light and dark themes
getAllThemes() / useAllThemes() - All themes including legacy versions
useLoaderTheme() - Returns Material-UI v5 theme object

Note: When deployed to RHDH, the application shell provides theming automatically. This configuration is only needed for local development.

Step 5: Implement Plugin Components

Page Component

Create a full-page component for dynamic routes:

// src/components/MyPage/MyPage.tsx
import React from 'react';
import { Page, Header, Content } from '@backstage/core-components';

export const MyPage = () => (
  <Page themeId="tool">
    <Header title="My Plugin" />
    <Content>
      <h1>Hello from My Plugin</h1>
    </Content>
  </Page>
);

Entity Card Component

Create a card for entity pages:

// src/components/MyCard/MyCard.tsx
import React from 'react';
import { InfoCard } from '@backstage/core-components';
import { useEntity } from '@backstage/plugin-catalog-react';

export const MyEntityCard = () => {
  const { entity } = useEntity();
  return (
    <InfoCard title="My Plugin Info">
      <p>Entity: {entity.metadata.name}</p>
    </InfoCard>
  );
};

Export Components

Export all components in src/index.ts:

// src/index.ts
export { myPlugin } from './plugin';
export { MyPage } from './components/MyPage';
export { MyEntityCard } from './components/MyCard';

Build and verify:

cd plugins/<plugin-id>
yarn build

Step 6: 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>
npx @red-hat-developer-hub/cli@latest plugin export

Output shows the generated Scalprum configuration. Creates dist-dynamic/ with dist-scalprum/ (webpack federated modules).

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 (custom Scalprum config, multi-plugin bundles, tgz/npm packaging), consult the export-and-package skill.

Step 7: Configure Plugin Wiring

Frontend plugins require configuration in dynamic-plugins.yaml to define how they integrate with RHDH.

Basic Example

plugins:
  - package: oci://quay.io/<namespace>/<plugin-name>:v0.1.0!my-plugin
    disabled: false
    pluginConfig:
      dynamicPlugins:
        frontend:
          my-org.plugin-my-plugin:  # Must match scalprum.name
            dynamicRoutes:
              - path: /my-plugin
                importName: MyPage
                menuItem:
                  icon: dashboard
                  text: My Plugin

Key Wiring Options

Option	Purpose
`dynamicRoutes`	Full page routes with optional sidebar menu items
`mountPoints`	Entity page cards, tabs, and other integrations
`menuItems`	Sidebar ordering and nesting
`appIcons`	Custom icons for routes and menus
`entityTabs`	New tabs on entity pages

For complete wiring configuration (mount points, conditional rendering, custom tabs, themes, scaffolder extensions), use the generate-frontend-wiring skill.

Known Issues

MUI v5 Styles Missing

If using MUI v5, add class name generator to src/index.ts:

import { unstable_ClassNameGenerator as ClassNameGenerator } from '@mui/material/className';

ClassNameGenerator.configure(componentName =>
  componentName.startsWith('v5-') ? componentName : `v5-${componentName}`
);

export * from './plugin';

Grid Spacing Missing

Apply spacing manually to MUI v5 Grid:

<Grid container spacing={2}>
  <Grid item>...</Grid>
</Grid>

Additional Resources

Related Skills

export-and-package - Complete export/packaging workflow
generate-frontend-wiring - Advanced wiring configuration (mount points, tabs, themes, etc.)