Packaging your Plugin

Plugins must be built and packaged before being being published or distributed. We have been using for local plugin development a "vanilla" Backstage project created with the Backstage CLI, and we will always keep it clean and simple.

A real-world normal Backstage build will refer to released plugins as dependencies during build time. A real world VeeCode DevPortal instance will dynamically load plugins during start time instead.

Build the plugin

To build all plugins under the host Backstage project just go to its root folder and run:

yarn tsc
yarn build:all

This will generate a dist folder under each plugin folder and a dist-types folder under the root folder.

Package the plugin

You can now package the plugin using the npm pack command:

cd plugins/<your-plugin>
npm pack

warning

If you get "missing a backstage.pluginPackages" error, run yarn fix --publish at the project root folder and try again.

Publish the plugin

A published plugin becomes available to other Backstage projects who wish to statically link it.

Check if your plugin is marked as "private" in its package.json file. If it is, remove the "private" field or set it to false:

{
  "name": "@something/your-plugin",
  "private": false,
  ...
}

You can now publish the plugin to npm using the npm publish command:

cd plugins/<your-plugin>
npm publish

tip

You can rely on a local npm registry like Verdaccio for development and testing purposes. Verdaccio can be started with a simple command:

verdaccio -l 0.0.0.0:4873

If you are using a local registry like Verdaccio, just add its URL:

npm publish --registry http://localhost:4873

Publish a Dynamic Plugin

A dynamic plugin is a plugin that can be loaded at runtime. It is a plugin that is not statically linked to the host Backstage project, but is loaded at start time.

Technically, a dynamic plugin is just a slightly different repackaging of a regular plugin, but with a different name.

To create a dynamic package run this command at the plugin folder after you have already built and packaged it successfully as a "normal" plugin:

cd plugins/<your-plugin>
npx @red-hat-developer-hub/cli@latest plugin export

The distributed version of the plugin will now be available in a new dist-dynamic folder. You can now package and publish it as a dynamic plugin:

cd dist-dynamic
npm pack
npm publish --registry <your-local-registry-url>

info

The @red-hat-developer-hub/cli replaced the old @janus-idp/cli tool for dynamic plugin exporting. You may still find references to the old tool in the documentation or pages that were not yet updated.

Packaging Options

A dynamic plugin is usually packaged and published to a private npm registry, but you have other options:

• You can export the plugin to an OCI registry like Quay.io or Docker Hub (just use npx @red-hat-developer-hub/cli@latest plugin package instead of export)
• You can use the tgz file generated by the npm pack command:
  • Host it in an internal web server and use its URL in the package field or
  • Use a local path in the package field (use volume mounts or a custom image)
• You can bundle the plugin within a custom DevPortal image and use a local path in the package field (thus making it another preloaded plugin).

There are a few other options too, but they are not recommended for production use. We will not cover them here, for we recommend using an internal npm registry like Nexus, Artifactory or even Verdaccio.

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.

Dynamic plugins are tipically published to a private npm registry, and the DevPortal instance will load them from there.