Procedure

1. Clone the source code for the Entity Feedback plugin, as follows:

   $ git clone https://github.com/backstage/community-plugins.git
   $ cd community-plugins

2. Prepare your environment to build the plugin by enabling Yarn for your Node.js installation, as follows:

   $ corepack enable yarn

3. Install the dependencies, compile the code, and build the plugins, as follows:

   $ cd workspaces/entity-feedback
   $ yarn install
   $ yarn tsc
   $ yarn build:all

   Note

   After this step, with upstream Backstage, you publish the built plugins to a NPM or NPM-compatible registry. In this example, as you are building this plugin to support it being loaded dynamically by Red Hat Developer Hub, you can skip the npm publish step that publishes the plugin to a NPM registry. Instead, you can package the plugin for dynamic loading and publish it as a container image on Quay.io or your preferred container registry.

4. Prepare the Entity Feedback frontend plugin by using the Red Hat Developer Hub CLI. The following command uses the plugin files in the dist folder that was generated by the yarn build:all command, and creates a new dist-scalprum folder that contains the necessary configuration and source files to enable dynamic loading:

   $ cd plugins/entity-feedback
   $ npx @red-hat-developer-hub/cli@latest plugin export

   When this command packages a frontend plugin, it uses a default Scalprum configuration if one is not found. The Scalprum configuration is used to specify the plugin entry point and exports, and then to build a dist-scalprum folder that contains the dynamic plugin. The default Scalprum configuration is shown below, however a scalprum key can be added to the package.json file used by your plugin to set custom values, if necessary:

   {
     "name": "backstage-community.plugin-entity-feedback",
     "exposedModules": {
       "PluginRoot": "./src/index.ts"
     }
   }

   The following plugin-manifest.json file, which Red Hat Developer Hub uses to load the plugin, is located in the dist-dynamic/dist-scalprum folder:

   {
     "name": "backstage-community.plugin-entity-feedback",
     "version": "0.6.0",
     "extensions": [],
     "registrationMethod": "callback",
     "baseURL": "auto",
     "loadScripts": [
       "backstage-community.plugin-entity-feedback.fd691533c03cb52c30ac.js"
     ],
     "buildHash": "fd691533c03cb52c30acbb5a80197c9d"
   }

5. Package the plugin into a container image and publish it to Quay.io or your preferred container registry:

   $ export QUAY_USER=replace-with-your-username
   $ export PLUGIN_NAME=entity-feedback-plugin
   $ export VERSION=$(cat package.json | jq .version -r)
   
   $ npx @red-hat-developer-hub/cli@latest plugin package \
     --tag quay.io/$QUAY_USER/$PLUGIN_NAME:$VERSION
   
   $ podman login quay.io
   $ podman push quay.io/$QUAY_USER/$PLUGIN_NAME:$VERSION

6. Repeat the same steps for the backend plugin. Scalprum is not required for backend plugins, and a dist-dynamic folder is generated instead of a dist-scalprum folder:

   $ cd ../entity-feedback-backend/
   $ npx @red-hat-developer-hub/cli@latest plugin export
   
   $ export QUAY_USER=replace-with-your-username
   $ export PLUGIN_NAME=entity-feedback-plugin-backend
   $ export VERSION=$(cat package.json | jq .version -r)
   
   $ npx @red-hat-developer-hub/cli@latest plugin package \
     --tag quay.io/$QUAY_USER/$PLUGIN_NAME:$VERSION
   
   $ podman push quay.io/$QUAY_USER/$PLUGIN_NAME:$VERSION

   Those commands result in two container images being published to your container registry.

   Figure 2. Container images published to Quay.io

   

Procedure

1. Navigate to the plugin’s root directory (not the dist-dynamic directory).

2. Run the following command to package the plugin into an OCI image:

   Example command to package an exported custom plugin

   $ npx @red-hat-developer-hub/cli@latest plugin package --tag quay.io/example/image:v0.0.1

   In the previous command, the --tag argument specifies the image name and tag.

3. Run one of the following commands to push the image to a registry:

   Example command to push an image to a registry using podman

   $ podman push quay.io/example/image:v0.0.1

   Example command to push an image to a registry using docker

   $ docker push quay.io/example/image:v0.0.1

   The output of the package-dynamic-plugins command provides the plugin’s path for use in the dynamic-plugin-config.yaml file.

Procedure

1. Navigate to the dist-dynamic directory.

2. Run the following command to create a tgz archive:

   Example command to create a tgz archive

   $ npm pack

   You can obtain the integrity hash from the output of the npm pack command by using the --json flag as follows:

   Example command to obtain the integrity hash of a tgz archive

   $ npm pack --json | head -n 10

3. Host the archive on a web server accessible to your RHDH instance, and reference its URL in the dynamic-plugin-config.yaml file as follows:

   Example dynamic-plugin-config.yaml file

   plugins:
     - package: https://example.com/backstage-plugin-myplugin-1.0.0.tgz
       integrity: sha512-<hash>

4. Run the following command to package the plugins:

   Example command to package a dynamic plugin

   $ npm pack --pack-destination ~/test/dynamic-plugins-root/

   Tip

   To create a plugin registry using HTTP server on OpenShift Container Platform, run the following commands:

   Example commands to build and deploy an HTTP server in OpenShift Container Platform

   $ oc project my-rhdh-project
   $ oc new-build httpd --name=plugin-registry --binary
   $ oc start-build plugin-registry --from-dir=dynamic-plugins-root --wait
   $ oc new-app --image-stream=plugin-registry

5. Configure your RHDH to use plugins from the HTTP server by editing the dynamic-plugin-config.yaml file:

   Example configuration to use packaged plugins in RHDH

   plugins:
     - package: http://plugin-registry:8080/backstage-plugin-myplugin-1.9.6.tgz

Procedure

1. Navigate to the dist-dynamic directory.

2. Run the following command to publish the package to your private NPM registry:

   Example command to publish a plugin package to an NPM registry

   $ npm publish --registry <npm_registry_url>

   Tip

   You can add the following to your package.json file before running the export command:

   Example package.json file

   {
     "publishConfig": {
       "registry": "<npm_registry_url>"
     }
   }

   If you modify publishConfig after exporting the dynamic plugin, re-run the plugin export command to ensure the correct configuration is included.