Skip to content

docs: Add dynamic plugin setup/installation instruction for the janus-idp plugins #1195

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 11, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,50 @@ A subset of available Janus IDP plugins is available at our [community site](htt

You can also see the [Plugin Marketplace](https://backstage.io/plugins) for other open-source plugins you can add to your Backstage instance.

## Dynamic Plugins Installation

It is possible to install plugins without code changes in a backstage that supports [Dynamic Plugins](https://github.com/janus-idp/backstage-showcase/blob/main/showcase-docs/dynamic-plugins.md) (e.g. [Janus IDP](https://janus-idp.io/) and [Red Hat Developer Hub](https://developers.redhat.com/rhdh)). Follow the steps below to install a dynamic plugin:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are there any prerequisite for enabling the dynamic plugins?
I mean, can a user just use this procedure in a random version of Janus-IDP/Backstage, or should they first make sure a specific version is available, or anything perhaps something else?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hello @jkilzi I confirmed that no additional configuration is required to enable dynamic plugins. Regarding what version to use, I know that dynamic plugins are available in RHDH starting on 1.0, but for Janus IDP I recommend users to check if the endpoint /api/dynamic-plugins-info/loaded-plugins, if it is available, then you can use dynamic plugins.

Please bear in mind that upstream backstage does not support dynamic plugins ATM.


- Map the dynamic plugins root directory in `app-config.local.yaml`:

```
dynamicPlugins:
rootDirectory: dynamic-plugins-root
```

- Place your package inside the plugins root directly. You can pack a local plugin or download from NPM using `npm pack`, then make sure to extract it correctly into the plugin root directory:

```
cd dynamic-plugins-root
mkdir {plugin name}
tar -xzvf {path to the NPM package tgz file} -C {plugin name} --strip-components=1
```

- Configure your plugin in `app-config.local.yaml`. For example, the configuration below will make a new menu item to access the plugin on route `my-plugin`:

```
dynamicPlugins:
rootDirectory: dynamic-plugins-root
frontend:
{plugin name}: # this should match the plugin name in package.json, remember to remove "@" and replace "/" by dots (".")
pluginConfig:
dynamicRoutes:
- path: /my-plugin
importName: MyPlugin # the exported react component that should be rendered
menuItem:
text: My Plugin
```

- Start backstage and you should see in logs that your plugin was correctly scanned by Backstage:

```
scalprum info Loaded dynamic frontend plugin '{plugin name}' from '${Backstage path}/dynamic-plugins-root/{plugin name}' type=plugin
```

Now when accessing Backstage you should see a new menu item with name `My Plugin` and when clicking on it your plugin will be rendered.

For more information check the [Dynamic Plugins Guide](https://github.com/janus-idp/backstage-showcase/blob/main/showcase-docs/dynamic-plugins.md).

---

✨ We would love for you to contribute to Janus IDP's collection of Backstage plugins and help make it even better than it is today! ✨
Expand Down