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/clipackage. Use the latest version (@latesttag) for compatibility with the most recent features and fixes.Note Use the
npx @red-hat-developer-hub/cli@latest plugin exportcommand 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.jsonfile 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()orcreateBackendModule()) as the default export from either the main package or analphapackage. Export as analphapackage if the plugin instance support still usesalphaAPIs. 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
bundleDependenciesfield in thepackage.jsonfile. This export mechanism ensures that you publish the dynamic plugin package as a self-contained package, with its private dependencies bundled in a privatenode_modulesfolder.Certain plugin dependencies require specific handling in the derived packages, such as:
- Shared dependencies: The RHDH application provides these dependencies and lists them as
peerDependenciesin thepackage.jsonfile. The dynamic plugin package does not bundle shared dependencies. For example, by default, all@backstagescoped packages use sharing.You can use the
--shared-packageflag to specify shared dependencies that Red Hat Developer Hub application provides and that the dynamic plugin package does not bundle.To treat a
@backstagepackage as private, use the negation prefix (!). For example, when a plugin depends on the package in@backstagethat 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
-nodeor-commonsuffixes.You can use the
--embed-packageflag 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-backendIn the earlier example:
- The export treats the
@backstage/plugin-notificationspackage as a private dependency and bundles it in the dynamic plugin package, despite being in the@backstagescope. - The export marks the
@backstage/plugin-notifications-backendpackage as an embedded dependency and bundles it in the dynamic plugin package.
- Shared dependencies: The RHDH application provides these dependencies and lists them as
- Front-end plugins
-
Front-end plugins can use
scalprumfor 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 exportThe following is an example of default
scalprumconfiguration:"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
scalprumsection to thepackage.jsonfile. 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
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.
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.