generate-frontend-wiring（生成前端接线）

Purpose

Analyze an existing Backstage frontend plugin and generate the RHDH dynamic plugin wiring configuration. This skill inspects the plugin's source files to determine exports and generates the corresponding app-config.yaml configuration.

When to Use

Use this skill when:

• User has an existing Backstage frontend plugin
• User wants to deploy it to RHDH as a dynamic plugin
• User needs the wiring configuration for dynamic-plugins.yaml

Prerequisites

The plugin directory must contain:

• package.json with plugin metadata
• src/plugin.ts or src/plugin.tsx with plugin definition
• src/index.ts exporting plugin components

Workflow

Step 1: Locate Plugin Files

Find and read the essential plugin files:

1. package.json - Get package name
2. src/plugin.ts - Find exported extensions (pages, cards)
3. src/index.ts - Find public exports (APIs, components)
4. dist-dynamic/dist-scalprum/plugin-manifest.json - Get scalprum name if built

Step 2: Determine Scalprum Name

The scalprum name is used to reference the plugin in RHDH configuration:

1. If plugin-manifest.json exists: Use the name field
2. If scalprum in package.json: Use scalprum.name
3. Otherwise derive from package name:

- @my-org/backstage-plugin-foo becomes my-org.backstage-plugin-foo - @internal/backstage-plugin-foo becomes internal.backstage-plugin-foo

Step 3: Identify Exports

Analyze the plugin source to find:

Routable Extensions (pages):

• Look for createRoutableExtension in plugin.ts
• These become dynamicRoutes entries
• Extract the export name (e.g., MyPluginPage)

Entity Cards/Content:

• Look for createComponentExtension in plugin.ts
• These become mountPoints entries
• Identify if they use useEntity (entity-scoped)

API Factories:

• Look for createApiFactory and createApiRef in plugin.ts or api.ts
• These become apiFactories entries
• Extract the apiRef export name

Icons:

• Look for icon exports (React components returning SVG/Icon)
• These become appIcons entries

Step 4: Generate Configuration

Output the complete wiring configuration in YAML format:

# RHDH Dynamic Plugin Configuration
# Add to your dynamic-plugins.yaml or app-config.yaml

dynamicPlugins:
  frontend:
    <scalprum-name>:
      dynamicRoutes:
        - path: /<plugin-id>
          importName: <PageComponentName>
          menuItem:
            icon: <icon-name>
            text: <Plugin Display Name>

      mountPoints:
        - mountPoint: entity.page.overview/cards
          importName: <CardComponentName>
          config:
            if:
              allOf:
                - isKind: component

      apiFactories:
        - importName: <apiRefName>

      appIcons:
        - name: <iconName>
          importName: <IconComponentName>

Step 5: Present to User

Show the generated configuration with:

1. The YAML configuration block
2. A table explaining each entry and its source
3. Notes about any optional configurations
4. Ask if it should be saved to a file

Example Output

For a plugin with:

• Package: @internal/backstage-plugin-demoplugin
• Page: DemopluginPage
• API: todoApiRef

Generate:

dynamicPlugins:
  frontend:
    internal.backstage-plugin-demoplugin:
      dynamicRoutes:
        - path: /demoplugin
          importName: DemopluginPage
          menuItem:
            icon: extension
            text: Demo Plugin
      apiFactories:
        - importName: todoApiRef

Configuration Options Reference

Dynamic Routes

dynamicRoutes:
  - path: /my-plugin           # URL path
    importName: MyPage         # Exported component name
    module: PluginRoot         # Optional: scalprum module (default: PluginRoot)
    menuItem:
      icon: dashboard          # System icon or custom appIcon
      text: My Plugin          # Sidebar menu text

Mount Points

mountPoints:
  - mountPoint: entity.page.overview/cards
    importName: MyCard
    config:
      layout:
        gridColumn: '1 / -1'   # Full width
      if:
        allOf:
          - isKind: component
          - hasAnnotation: my-plugin/enabled

API Factories

apiFactories:
  - importName: myApiFactory   # Or myApiRef if plugin exports it

App Icons

appIcons:
  - name: myIcon
    importName: MyIconComponent

Common Patterns

Page Plugin

Plugin that adds a standalone page:

dynamicRoutes:
  - path: /my-plugin
    importName: MyPluginPage
    menuItem:
      icon: extension
      text: My Plugin

Entity Card Plugin

Plugin that adds a card to entity pages:

mountPoints:
  - mountPoint: entity.page.overview/cards
    importName: MyEntityCard
    config:
      if:
        allOf:
          - isKind: component

Page + Card Plugin

Plugin with both page and entity integration:

dynamicRoutes:
  - path: /my-plugin
    importName: MyPluginPage
    menuItem:
      icon: myIcon
      text: My Plugin

mountPoints:
  - mountPoint: entity.page.overview/cards
    importName: MyEntityCard

appIcons:
  - name: myIcon
    importName: MyIcon

Notes

• The generated configuration is a starting point; adjust as needed
• Use references/frontend-wiring.md for complete configuration options
• Entity cards may need condition tuning based on target entity kinds
• Custom icons must be exported from the plugin's index.ts

Reference Files

• references/frontend-wiring.md - Complete mount points, routes, bindings
• references/entity-page.md - Entity page customization