Export custom plugins in Red Hat Developer Hub

To use plugins in Red Hat Developer Hub, you can export plugins as derived dynamic plugin packages. These packages contain the plugin code and dependencies, ready for dynamic plugin integration into Developer Hub.

Before you begin

  • 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 Package and deploy dynamic plugins as OCI images. If you must publish to the NPM registry, use a private registry.