Dynamic Plugin export for Red Hat Developer Hub based iDPs

backstage-community-plugin-announcements-dynamic-export.md

Dynamic Plugin export for Red Hat Developer Hub based iDPs

This tutorial describes how to export a existing Backstage plugin as a Dynamic plugin to be loaded into Red Hat Developer Hub.

For this demo I choose the Announcements plugin for Backstage as it is composed by multiple components including front-end UI, backend and search-backend.

Reference documentation:

• Official guide from the product documentation
• A simple getting started project for building Dynamic Plugins with Red Hat Developer Hub

Preparation

Clone the Backstage community-plugins repo to you workstation.

Note: The following procedure does not change the original plugin code base. It leverages the @janus-idp/cli to export and package the original plugin as a dynamic plugin.

cd community-plugins/workspaces/announcements/plugins
yarn install
yarn tsc
yarn build:all

Frontend

cd announcements
npx @janus-idp/cli@latest package export-dynamic-plugin --clean

#packaging as an NPM artifact (to publish to a Private NPM Registry)
cd dist-dynamic
npm pack

#packaging as an OCI artifact (to publish to an OCI Container Registry)
npx @janus-idp/cli@latest package package-dynamic-plugins --tag quay.io/repository/backstage-community-plugin-announcements-dynamic:latest

cd ../..

Backend

cd announcements-backend
npx @janus-idp/cli@latest package export-dynamic-plugin --clean --embed-package @backstage-community/plugin-search-backend-module-announcements --embed-package @backstage/plugin-signals-node

#packaging as an NPM artifact (to publish to a Private NPM Registry)
cd dist-dynamic
npm pack

#packaging as an OCI artifact (to publish to an OCI Container Registry)
cd ../
npx @janus-idp/cli@latest package package-dynamic-plugins --tag quay.io/repository/backstage-community-plugin-announcements-backend-dynamic:latest

cd ../..

Search

cd search-backend-module-announcements
npx @janus-idp/cli@latest package export-dynamic-plugin --clean --embed-package @backstage-community/plugin-announcements-common --embed-package @backstage-community/plugin-announcements-node

#packaging as an NPM artifact (to publish to a Private NPM Registry)
cd dist-dynamic
npm pack

#packaging as an OCI artifact (to publish to an OCI Container Registry)
cd ../
npx @janus-idp/cli@latest package package-dynamic-plugins --tag quay.io/repository/backstage-community-search-backend-module-announcements-dynamic:latest

cd ../..

Enabling the plugins

add to your dynamic-plugins-config.yaml

    plugins:
      #...
      - package: oci://quay.io/redhat_na_ssa/rhdh-dynamic-plugins/backstage-community-plugin-announcements-dynamic:0.1.4!backstage-community-plugin-announcements-dynamic
        disabled: false
      - package: oci://quay.io/redhat_na_ssa/rhdh-dynamic-plugins/backstage-community-plugin-search-backend-module-announcements-backend-dynamic:0.1.4!backstage-community-plugin-search-backend-module-announcements-backend-dynamic
        disabled: false
      - package: oci://quay.io/redhat_na_ssa/rhdh-dynamic-plugins/backstage-community-plugin-search-backend-module-announcements-dynamic:0.1.3!backstage-community-plugin-search-backend-module-announcements-dynamic
        disabled: false

Adding the front-end plugin to the portal UI

Add the following snippet to the app-config

    dynamicPlugins:
      frontend:
        backstage-community.plugin-announcements:
          dynamicRoutes:
            - path: /announcements
              importName: AnnouncementsPage
              menuItem:
                text: 'Announcements'
                icon: star #this comes from https://github.com/redhat-developer/rhdh/blob/main/packages/app/src/components/DynamicRoot/CommonIcons.tsx#L23-L47
          # add announcements widgets to the Home Page cards
          mountPoints:
            - mountPoint: home.page/cards
              importName: NewAnnouncementBanner
              config:
                layouts:
                  xl: { h: 1, y: 1 }
                  lg: { h: 1, y: 1 }
                  md: { h: 1, y: 1 }
                  sm: { h: 1 }
                  xs: { h: 1 }
                  xxs: { h: 1 }
            - mountPoint: home.page/cards
              importName: AnnouncementsCard
              config:
                layouts:
                  xl: { w: 5, h: 4, x: 8, y: 10}
                  lg: { w: 5, h: 4, x: 8, y: 10}
                  md: { w: 5, h: 4, x: 8, y: 10}
                  sm: { w: 12, h: 4 }
                  xs: { w: 12, h: 4 }
                  xxs: { w: 12, h: 4 }
            - mountPoint: search.page.results
              importName: AnnouncementSearchResultListItem
            #- mountPoint: search.page.filters
            #  importName: TechdocsSearchFilter
            - mountPoint: search.page.types
              importName: Announcement
              config:
                props:
                  name: Announcements
                  icon: announcementSearchResultListItem.announcement

creating-a-plugins-wrapper.md

Creating a plugin wrapper

This guide shows how to wrapp a "static" backstage plugin as dynamic plugin so it can be loaded into Red Hat Developer Hub.

Pre requisites

• Node v20.x (I personaly use nvm to manage my NodeJS installations)
• npm (v10.8.x - usually alread comes with Node if installed with nvm)
• npx (usually alread comes with Node if installed with nvm)
• an IDE (I use VSCode)

Cloning a sample wrapper

Te easiest way to create a new plugin wrapper is cloning from an exsisting one and make changes to it. Here are some plugin wrappers you can clone and use as a reference:

• https://github.com/gashcrumb/dynamic-plugins-custom-authentication-module which was created by one of the engineers working on Developer Hub.
• https://github.com/rafaeltuelho/rhdh-dynamic-plugins/tree/main/wrappers/backstage-plugin-announcements, created as a wrapper for the Announcements plugin for Backstage

Implementing the wrapper

• based on the sample project cloned, make the appropriate name changes.
• rename the plugin's root directory name
• make changes to the plugin's package.json
• ajust the dependencies and its versions
  • add the wrapped/original plugin (the one you're wrapping) as a dependency!
  • see the following package.json taken from a wrapper I created for the Backstage Announcements plugin

{
  "name": "backstage-community-plugin-announcements", // wrapper name
  "version": "0.1.5",
  "main": "src/index.ts",
  "types": "src/index.ts",
  "license": "Apache-2.0",
  "publishConfig": {
    "access": "public"
  },
  "backstage": {
    "role": "frontend-plugin",
    "supported-versions": "1.35.1",
    "pluginId": "backstage-community-plugin-announcements",
    "pluginPackages": [
      "backstage-community-plugin-announcements"
    ]
  },
  "exports": {
    ".": "./src/index.ts",
    "./package.json": "./package.json"
  },
  "typesVersions": {
    "*": {
      "package.json": [
        "package.json"
      ]
    }
  },
  "sideEffects": false,
  "scripts": {
    "start": "backstage-cli package start",
    "build": "backstage-cli package build",
    "lint": "backstage-cli package lint",
    "test": "backstage-cli package test",
    "clean": "backstage-cli package clean",
    "prepack": "backstage-cli package prepack",
    "postpack": "backstage-cli package postpack",
    "export-dynamic": "janus-cli package export-dynamic-plugin --clean" // add this script to export your wrapper as dynamic!
  },
  "dependencies": {
    "@backstage-community/plugin-announcements": "0.1.4", // add the original plugin as a direct dependency
    "react-router-dom": "6.0.0-beta.0 || ^6.3.0",
    "react-use": "^17.2.4"
  },
  "peerDependencies": {
    "react": "^16.13.1 || ^17.0.0 || ^18.0.0"
  },
  "devDependencies": {
    "@backstage/cli": "^0.26.11",
    "@janus-idp/cli": "3.0.0",
    "@types/node": "^18.18.7",
    "@types/webpack-env": "^1.18.8",
    "react": "^16.13.1 || ^17.0.0 || ^18.0.0",
    "react-dom": "^16.13.1 || ^17.0.0 || ^18.0.0",
    "typescript": "5.7.3"
  },
  "files": [ //make sure in list the following paths generated by the export tooling
    "dist",
    "dist-dynamic/*.*",
    "dist-dynamic/dist/**"
  ],
  "packageManager": "[email protected]"
}

• create a src/index.ts to re-export the wrapeed plugin's Components, like

export *  from '@backstage-community/plugin-NAME';
//...
// if you need to do additional wiring or exporting new components do it from here...

• compile, build and export

yarn install
yarn tsc
yarn build

npx @janus-idp/cli@latest package export-dynamic-plugin --clean
npx @janus-idp/cli@latest package package-dynamic-plugins --tag quay.io/repository/backstage-community-plugin-NAME-dynamic

podman push quay.io/repository/backstage-community-plugin-NAME-dynamic
backstage-community-plugin-NAME-dynamic

NOTES:

• the correct plugins name to be referenced in the plugin's app-config is the one found inside dist-dynamic/dist-scalprum/plugin-manifest.json
• Additional reference guide: https://github.com/redhat-developer/rhdh/blob/main/docs/dynamic-plugins/wrapping-plugins.md