Chapter 3. Custom plugins in Red Hat Developer Hub

Prerequisites

• You have installed the @red-hat-developer-hub/cli package. Use the latest version (@latest tag) for compatibility with the most recent features and fixes.

  Note

  Use the npx @red-hat-developer-hub/cli@latest plugin export command to export an existing custom plugin as a derived dynamic plugin package.

  You must use this command when you have the source code for a custom plugin and want to integrate it into RHDH as a dynamic plugin.

  The command processes the plugin’s source code and dependencies and generates the necessary output for dynamic loading by RHDH.

  For an example of using this command, see Example of installing a custom plugin in Red Hat Developer Hub.

• You have installed and configured Node.js and NPM.
• The custom plugin is compatible with your Red Hat Developer Hub version. For more information, see Version compatibility matrix.

• The custom plugin must have a valid package.json file in its root directory, containing all required metadata and dependencies.

  Backend plugins

  To ensure compatibility with the dynamic plugin support and enable their use as dynamic plugins, existing backend plugins must be compatible with the new Backstage backend system. Additionally, these plugins must be rebuilt using a dedicated CLI command.

  You must export the new Backstage backend system entry point (created using createBackendPlugin() or createBackendModule()) as the default export from either the main package or an alpha package. Export as an alpha package if the plugin instance support still uses alpha APIs. This does not add any additional requirement on top of the standard plugin development guidelines of the plugin instance.

  The dynamic export mechanism identifies private dependencies and sets the bundleDependencies field in the package.json file. This export mechanism ensures that you publish the dynamic plugin package as a self-contained package, with its private dependencies bundled in a private node_modules folder.

  Certain plugin dependencies require specific handling in the derived packages, such as:

  • Shared dependencies: The RHDH application provides these dependencies and lists them as peerDependencies in the package.json file. The dynamic plugin package does not bundle shared dependencies. For example, by default, all @backstage scoped packages use sharing.

    You can use the --shared-package flag to specify shared dependencies that Red Hat Developer Hub application provides and that the dynamic plugin package does not bundle.

    To treat a @backstage package as private, use the negation prefix (!). For example, when a plugin depends on the package in @backstage that is not provided by the Red Hat Developer Hub application.

  • Embedded dependencies: The dynamic plugin package bundles these dependencies with their dependencies hoisted to the top level. By default, the package embeds packages with -node or -common suffixes.

    You can use the --embed-package flag to specify additional embedded packages. For example, packages from the same workspace that do not follow the default naming convention.

    The following is an example of exporting a dynamic plugin with shared and embedded packages:

    $ npx @red-hat-developer-hub/cli@latest plugin export --shared-package '!/@backstage/plugin-notifications/' --embed-package @backstage/plugin-notifications-backend

    In the earlier example:

  • The export treats the @backstage/plugin-notifications package as a private dependency and bundles it in the dynamic plugin package, despite being in the @backstage scope.
  • The export marks the @backstage/plugin-notifications-backend package as an embedded dependency and bundles it in the dynamic plugin package.

  Front-end plugins

  Front-end plugins can use scalprum for configuration. The CLI can generate this configuration automatically during the export process. When running the following command, the CLI logs the generated default configuration:

  $ npx @red-hat-developer-hub/cli@latest plugin export

  The following is an example of default scalprum configuration:

  "scalprum": {
    "name": "<package_name>",  // The Webpack container name matches the NPM package name, with "@" replaced by "." and "/" removed.
    "exposedModules": {
      "PluginRoot": "./src/index.ts"  // The default module name is "PluginRoot" and doesn't need explicit specification in the app-config.yaml file.
    }
  }

  You can add a scalprum section to the package.json file. For example:

  "scalprum": {
    "name": "custom-package-name",
    "exposedModules": {
      "BazModuleName": "./src/baz.ts",
      "QuxModuleName": "./src/qux.ts"
      // Define multiple modules here, with each exposed as a separate entry point in the Webpack container.
    }
  }

  Dynamic plugins might need adjustments for Developer Hub needs, such as static JSX for mountpoints or dynamic routes. These changes are optional but might be incompatible with static plugins.

  To include static JSX, define an additional export and use it as the dynamic plugin’s importName. For example:

  // For a static plugin
  $ export const EntityTechdocsContent = () => {...}
  
  // For a dynamic plugin
  $ export const DynamicEntityTechdocsContent = {
    element: EntityTechdocsContent,
    staticJSXContent: (
      <TechDocsAddons>
        <ReportIssue />
      </TechDocsAddons>
    ),
  };

Procedure

• Use the plugin export command from the @red-hat-developer-hub/cli package to export the plugin:

  $ npx @red-hat-developer-hub/cli@latest plugin export

  Ensure that you run the earlier command in the root directory of the plugin’s JavaScript package (containing package.json file).

  The dist-dynamic subdirectory has the resulting derived package. The exported package name consists of the original plugin name with -dynamic appended.

  Warning

  Do not publish the derived dynamic plugin JavaScript packages to the public NPM registry. For more appropriate packaging options, see Section 3.2, “Package and publish custom plugins as dynamic plugins”. If you must publish to the NPM registry, use a private registry.

• Open Container Initiative (OCI) image (recommended)
• TGZ file

• JavaScript package

  Important

  You must publish exported dynamic plugin packages only to private NPM registries.

• package: The plugin’s package definition, which can be an OCI image, a TGZ file, a JavaScript package, or a directory path.
• disabled: A boolean value indicating whether you enable or disable the plugin.
• integrity: The integrity hash of the package, required for TGZ file and JavaScript packages.
• pluginConfig: The plugin’s configuration. For backend plugins, this is optional; for front-end plugins, you must include it. The pluginConfig is a fragment of the app-config.yaml file, and the system merges any added properties with the RHDH app-config.yaml file.

• You need to ensure that you build your custom plugin with a compatible version of Backstage. In Developer Hub, click Settings. Your custom plugin must be compatible with the Backstage Version (or the closest earlier version) that the Metadata section of Red Hat Developer Hub displays.

  For example, if you view the history of the backstage.json file for the Entity Feedback plugin, the 1fc87de commit is the closest earlier version to Backstage version of 1.39.1.

  

Prerequisites

• Your local environment meets the following requirements:
• Node.js: Version 22.x
• Yarn: Version 4.x
• git CLI
• jq CLI: Command-line JSON processor
• OpenShift CLI (oc): The client for interacting with your OpenShift cluster.
• Container runtime: You need either podman or docker to package the plugin into an OCI image and to log in to registries.
• Container registry access: Access to an OCI-compliant container registry, such as the internal OpenShift registry or a public registry such as Quay.io.

Procedure

• To add your custom dynamic plugins to Red Hat Developer Hub, update the dynamic-plugins.yaml file by using the following configuration that the npx @red-hat-developer-hub/cli@latest plugin package command generates:

  plugins:
    - package: oci://quay.io/_<user_name>_/entity-feedback-plugin:0.5.0
      disabled: false
    - package: oci://quay.io/_<user_name>_/entity-feedback-plugin-backend:0.6.0
      disabled: false

  Note

  Ensure that your container images are publicly accessible, or that you have configured a pull secret in your environment. A pull secret provides Red Hat Developer Hub with credentials to authenticate pulling your plugin container images from a container registry.