Skip to main content
Version: v3

Packaging your Plugin

Plugins must be built and packaged before being distributed. Development happens in a workspace from the devportal-plugins repository, and DevPortal loads the result as a dynamic plugin at start time.

Build the plugin​

To build all plugins under the workspace just go to the workspace root folder and run:

yarn tsc
yarn build:all

This type-checks the workspace and builds every package.

Export and test a workspace package locally​

A dynamic plugin is loaded at runtime rather than linked to the host project. For the single step-by-step procedure to export a workspace package and run it in devportal-local, see Creating Your Own Plugin. The helper uses the Red Hat Developer Hub CLI package @red-hat-developer-hub/cli (rhdh-cli).

Publish as an OCI artifact​

When the plugin works locally, publish it as an OCI image in a registry your DevPortal can pull from, then reference the image in a plugin entry.

Publish in your own registry​

The Red Hat Developer Hub CLI packages a plugin as an OCI image with its plugin package command. Follow the Red Hat Developer Hub documentation for the command, then push the image to your registry.

Propose a plugin for the DevPortal catalog​

VeeCode publishes the plugins of the DevPortal catalog from the public export overlays repository. That repository exports upstream Backstage plugins as dynamic plugins and publishes one OCI image per plugin. To propose a plugin, open a pull request that adds a plugin workspace:

  1. Create a directory under workspaces/<workspace-name>/.
  2. Add a source.json pointing at the upstream repository and version.
  3. Add a plugins-list.yaml listing the plugins to export.
  4. Optionally add a metadata/ directory with one Package manifest per plugin. These manifests feed smoke tests and the Extensions UI.

The repository's GitHub Actions workflows build and publish the images. Published images live under quay.io/veecode/<plugin-name>, with tags shaped like bs_<backstage-version>__<plugin-version>, for example bs_1.52.0__2.8.0.

Reference the image​

Reference the published image in a plugin entry by its digest. For an image in the DevPortal catalog the entry looks like this:

plugins:
  - package: oci://quay.io/veecode/<plugin-name>@sha256:<digest>
    disabled: false

An image that holds one plugin needs no !<plugin path> suffix: the installer reads the path from the image manifest. To turn on or change a plugin that is already in the default plugin list, follow Adding Plugins instead. See Loading a Dynamic Plugin and Configure dynamic plugins for the local stack for where the entry goes.

An OCI plugin image and its Extensions catalog entry are distinct artifacts. The catalog index is a separate OCI image that supplies the Extensions UI metadata; publishing the plugin image alone does not list it in the Marketplace.

Packaging options​

The OCI path above is the default for DevPortal 3.x. You have other options where the plugin owner needs them:

  • You can host the tgz file produced by npm pack on an internal web server and use its URL in the package field.
  • You can use a local path in the package field with a volume mount into the portal container. See Creating Your Own Plugin for the local development procedure.
  • You can publish the dynamic package to an npm registry, public or private, and pin it with an integrity hash. See Loading a Dynamic Plugin.

You can find more info on these packaging options in Red Hat Developer Hub documentation. Both VeeCode DevPortal and RHDH use the same dynamic loading mechanism.

Additional Notes​

It becomes clear that plugins may have a release cycle of their own, and any DevPortal instance should be able to load the specific plugins it chooses.

Last updated on