From 66ff69b21229f64687e2307fcc71bae2ed9a92fa Mon Sep 17 00:00:00 2001 From: Stan Lewis Date: Fri, 2 Oct 2026 14:18:40 -0400 Subject: [PATCH 1/3] docs(plugin): add comprehensive dynamic plugin development guide - Add docs/Plugin-Development-CLI.md covering standalone scaffolding, local runtime testing, dependency auditing, upgrading, and dynamic export - Document plugin new template shapes, version pinning, and standalone harnesses - Document plugin check-versions (and versions:lint alias), 3-tier version mapping, audit statuses, and CI pipeline recipes - Document plugin upgrade (and versions:bump alias), dry-run mode, and lockfile synchronization - Document plugin dev Compose runtime lifecycle, automated config include, and watch mode - Document air-gapped/offline operations with local manifests and RHDH_OFFLINE - Update README.md with cross-links to the new guide and list all plugin development commands Assisted-By: opencode Signed-off-by: Stan Lewis rh-pre-commit.version: 2.4.0 rh-pre-commit.check-secrets: ENABLED --- README.md | 19 +- docs/Plugin-Development-CLI.md | 423 +++++++++++++++++++++++++++++++++ 2 files changed, 438 insertions(+), 4 deletions(-) create mode 100644 docs/Plugin-Development-CLI.md diff --git a/README.md b/README.md index 91fe1b1..6c1fe43 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ When you build an OCI image with `--tag` (instead of exporting to a directory wi ## Checking Plugin Versions -Use `plugin check-versions` to compare a plugin's `@backstage/*` dependencies with the Backstage release used by an RHDH version: +Use `plugin check-versions` (or alias `plugin versions:lint`) to compare a plugin's `@backstage/*` dependencies with the Backstage release used by an RHDH version: ```bash rhdh-cli plugin check-versions --rhdh-version 2.0.0 @@ -54,9 +54,11 @@ For air-gapped environments, provide a local release manifest with `--manifest-f When adding support for a new RHDH release, update `RHDH_COMPATIBILITY_MATRIX` in `src/lib/rhdhVersion.ts` with its Backstage version before releasing the corresponding CLI version. This matrix is maintained manually until its release metadata can be automated. +For full auditing details, exit codes, and CI pipeline recipes, see the [Plugin Development Guide](docs/Plugin-Development-CLI.md#auditing-plugin-dependencies-plugin-check-versions). + ## Upgrading Plugin Versions -Use `plugin upgrade` to update a plugin's `@backstage/*` dependencies to the versions from an RHDH release manifest: +Use `plugin upgrade` (or alias `plugin versions:bump`) to update a plugin's `@backstage/*` dependencies to the versions from an RHDH release manifest: ```bash rhdh-cli plugin upgrade --rhdh-version 2.0.0 @@ -68,6 +70,8 @@ Use `--dry-run` to preview dependency changes without writing files and `--skip- For air-gapped environments, provide a local Backstage release manifest with `--manifest-file` and set `RHDH_OFFLINE=true` to skip the RHDH GitHub metadata lookup. +For advanced upgrade options and lockfile details, see the [Plugin Development Guide](docs/Plugin-Development-CLI.md#upgrading-plugin-dependencies-plugin-upgrade). + ## Creating a Plugin Use `plugin new` to create a standalone, version-pinned dynamic plugin project: @@ -78,6 +82,8 @@ rhdh-cli plugin new my-plugin --type frontend --rhdh-version 2.1.0 Supported types are `frontend` (a New Frontend System, or NFS, page), `backend` (a minimal new-backend-system plugin), and `catalog-processor-module` (a catalog processor module). Frontend and backend projects include a `dev/` harness and `yarn start` for isolated development; catalog processor modules do not because they require a host backend plugin. Use `--name ` as an alternative to the positional name, and `--output ` to select a destination. Use `--plugin-package ` to set the generated package name; it defaults to `@internal/backstage-plugin-`. The generated project uses the target RHDH release's Backstage manifest for every `@backstage/*` dependency. For air-gapped environments, provide `--manifest-file` and set `RHDH_OFFLINE=true`. Export and package generated plugins with `npx @red-hat-developer-hub/cli`, or through RHDH Dynamic Plugin Factory, rather than adding the CLI as a project dependency. +For complete template details and configuration options, see the [Plugin Development Guide](docs/Plugin-Development-CLI.md#scaffolding-a-new-plugin-plugin-new). + ## Development ### Testing a Plugin in RHDH Local @@ -110,6 +116,8 @@ Use `rhdh-cli plugin dev status` for the interpreted runtime state, `rhdh-cli pl The CLI manages a single plugin entry in `configs/dynamic-plugins/rhdh-cli.generated.local.yaml`. Each `start` or `update` run overwrites this file with the current plugin's package path, disabled flag, and pull policy. Extra `pluginConfig` for the plugin (such as app-config keys) belongs in `dynamic-plugins.override.yaml` under a `plugins:` entry for the same package, not in the generated file. +For full lifecycle workflows, configuration automation, and watch mode details, see the [Plugin Development Guide](docs/Plugin-Development-CLI.md#local-containerized-runtime-development-plugin-dev). + ### Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for local development setup, coding guidelines, changelog discipline, versioning strategy, and the release process. @@ -141,10 +149,12 @@ The CLI provides two categories of commands: ### Plugin Development Commands +- `plugin new`: Scaffold a standalone, version-pinned dynamic plugin project +- `plugin dev`: Export a dynamic plugin and manage its lifecycle against an existing RHDH Local runtime (`start`, `update`, `restart`, `stop`, `logs`, `status`) +- `plugin check-versions` (alias: `plugin versions:lint`): Audit plugin dependencies against target RHDH Backstage release manifests +- `plugin upgrade` (alias: `plugin versions:bump`): Upgrade plugin dependencies to match a target RHDH release - `plugin export`: Export a Backstage plugin as a dynamic plugin - `plugin package`: Package dynamic plugins for distribution -- `plugin check-versions`: Verify plugin compatibility with RHDH versions -- `plugin dev`: Export a dynamic plugin and manage its lifecycle against an existing RHDH Local runtime (`start`, `update`, `restart`, `stop`, `logs`, `status`) ### Intent-Based RHDH Interaction Commands @@ -184,6 +194,7 @@ All commands support `--help` for detailed usage and `--output json` for machine **📚 For complete documentation, setup guides, and examples, see:** +- **[Plugin Development Guide](docs/Plugin-Development-CLI.md)** - Complete guide for scaffolding, local runtime testing, dependency auditing, upgrading, and dynamic export - **[Intent-Based CLI Documentation](docs/Intent-Based-CLI.md)** - Complete guide for RHDH interaction commands ### Optional TechDocs Features diff --git a/docs/Plugin-Development-CLI.md b/docs/Plugin-Development-CLI.md new file mode 100644 index 0000000..44830eb --- /dev/null +++ b/docs/Plugin-Development-CLI.md @@ -0,0 +1,423 @@ +# RHDH CLI - Plugin Development Guide + +Complete guide for using `rhdh-cli` to scaffold, develop, audit, upgrade, and package dynamic plugins for Red Hat Developer Hub (RHDH). + +--- + +## Table of Contents + +- [Overview & Architecture](#overview--architecture) +- [Command Summary](#command-summary) +- [Scaffolding a New Plugin (`plugin new`)](#scaffolding-a-new-plugin-plugin-new) + - [Syntax & Options](#syntax--options) + - [Supported Plugin Types](#supported-plugin-types) + - [Upstream Template Reuse](#upstream-template-reuse) + - [Standalone Development Harness](#standalone-development-harness) +- [Auditing Plugin Dependencies (`plugin check-versions`)](#auditing-plugin-dependencies-plugin-check-versions) + - [Syntax & Options](#syntax--options-1) + - [Version Mapping & 3-Tier Resolution](#version-mapping--3-tier-resolution) + - [Audit Statuses](#audit-statuses) + - [CI Pipeline Integration](#ci-pipeline-integration) +- [Upgrading Plugin Dependencies (`plugin upgrade`)](#upgrading-plugin-dependencies-plugin-upgrade) + - [Syntax & Options](#syntax--options-2) + - [Dry-Run Preview](#dry-run-preview) + - [Lockfile Synchronization](#lockfile-synchronization) + - [Range Preservation & Non-Backstage Packages](#range-preservation--non-backstage-packages) +- [Local Containerized Runtime Development (`plugin dev`)](#local-containerized-runtime-development-plugin-dev) + - [Prerequisites](#prerequisites) + - [Lifecycle Subcommands](#lifecycle-subcommands) + - [Automated Configuration with `--configure`](#automated-configuration-with---configure) + - [Continuous Development with `--watch`](#continuous-development-with---watch) + - [Inspecting Runtime & Logs](#inspecting-runtime--logs) +- [Exporting & Packaging Plugins](#exporting--packaging-plugins) + - [Dynamic Export (`plugin export`)](#dynamic-export-plugin-export) + - [OCI Container Packaging (`plugin package`)](#oci-container-packaging-plugin-package) +- [Air-Gapped & Offline Operations](#air-gapped--offline-operations) + +--- + +## Overview & Architecture + +Developing dynamic plugins for Red Hat Developer Hub previously required maintaining a full Backstage monorepo host application (`packages/app` and `packages/backend`), introducing significant boilerplate and upgrade friction. Furthermore, RHDH releases incorporate curated Backstage versions and skip intermediate upstream releases, making manual dependency resolution error-prone. + +The `rhdh-cli` plugin developer on-ramp provides: + +1. **Zero Host Overhead:** Scaffold, develop, build, and test standalone dynamic plugins as self-contained Yarn Berry workspaces without hosting a full Backstage app. +2. **5-Minute "Time to Hello World":** Scaffold a working plugin and run it against a local containerized RHDH instance in under five minutes. +3. **Automated Dependency Alignment:** Automatically align `@backstage/*` dependencies against the official Backstage release manifest for your target RHDH release. +4. **Live Containerized Feedback:** Test plugins inside a real RHDH Local Compose environment with automated staging, HTTP readiness polling, and watch-mode reload. + +--- + +## Command Summary + +| Command | Alias | Description | +| -------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------- | +| `rhdh-cli plugin new` | — | Scaffold a standalone, version-pinned dynamic plugin project | +| `rhdh-cli plugin check-versions` | `plugin versions:lint` | Audit plugin dependencies against target RHDH Backstage release manifests | +| `rhdh-cli plugin upgrade` | `plugin versions:bump` | Upgrade `@backstage/*` dependencies and sync lockfile to target RHDH release | +| `rhdh-cli plugin dev` | — | Drive a local containerized RHDH Compose runtime (`start`, `update`, `restart`, `stop`, `logs`, `status`) | +| `rhdh-cli plugin export` | — | Build and export a plugin package into `./dist-dynamic/` for dynamic loading | +| `rhdh-cli plugin package` | — | Package exported dynamic plugins into container images (OCI) for deployment | + +--- + +## Scaffolding a New Plugin (`plugin new`) + +Creates a standalone, version-pinned dynamic plugin project that is ready to develop, test, and export. + +### Syntax & Options + +```bash +rhdh-cli plugin new [options] +``` + +**Arguments:** + +- ``: The plugin name. Used to derive the default output directory and package name. + +**Options:** + +- `--type `: Plugin type: `frontend`, `backend`, or `catalog-processor-module`. +- `--template `: Upstream template name from `@backstage/cli-module-new` (alternative to `--type`). +- `--rhdh-version `: Target RHDH release version for dependency pinning (e.g. `2.1.0`, `2.1`, `2.0.0`). Defaults to the latest supported GA release (`2.1.0`). +- `--output `: Target directory for the scaffolded project (defaults to ``). +- `--plugin-package `: Override the generated `package.json` package name (defaults to `@internal/backstage-plugin-`). +- `--module-id `: Override the module identifier for module-type templates (defaults to ``). + +**Example:** + +```bash +# Scaffold a frontend plugin for RHDH 2.1 +rhdh-cli plugin new my-custom-plugin --type frontend --rhdh-version 2.1.0 +``` + +### Supported Plugin Types + +| Type | Description | Included Features | +| -------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------- | +| `frontend` | New Frontend System (NFS) frontend plugin | Routed page (`PageBlueprint`), `EntityCard` extension, i18n support, and MSW v2-backed unit tests | +| `backend` | New Backend System (NBS) backend plugin | Default dynamic export in `src/index.ts`, standalone backend router, and test utilities | +| `catalog-processor-module` | Backend module extending the catalog | Custom catalog processor module registration extending `@backstage/plugin-catalog-backend` | + +### Upstream Template Reuse + +Rather than maintaining divergent templates, `rhdh-cli plugin new` renders portable templates directly from the release-matched `@backstage/cli-module-new` package. It applies an RHDH standalone adapter that configures: + +- Standalone Yarn Berry (`yarn@4.x`) configuration with `node-modules` linker. +- Pinned `@backstage/*` dependencies strictly matching the target RHDH release manifest. +- Versioned `backstage.json` recording the underlying Backstage release. +- Standalone TypeScript configuration and build scripts. + +Generated projects do **not** depend on `@red-hat-developer-hub/cli` as a runtime dependency. The generated README directs authors to use `npx @red-hat-developer-hub/cli` for export and packaging. + +### Standalone Development Harness + +Frontend and backend plugins include an isolated `dev/` harness: + +```bash +cd my-custom-plugin +yarn install +yarn start +``` + +This launches a lightweight local dev server to develop and iterate on UI components or backend endpoints in isolation without running a full container stack. + +--- + +## Auditing Plugin Dependencies (`plugin check-versions`) + +Audits the `@backstage/*` dependencies declared in `package.json` against the official Backstage release manifest for a specified RHDH release. This catches dependency drift before it causes build or runtime failures. + +### Syntax & Options + +```bash +rhdh-cli plugin check-versions [options] +rhdh-cli plugin versions:lint [options] # alias +``` + +**Options:** + +- `--rhdh-version `: Target RHDH version to validate against (e.g. `2.1.0`, `2.1`, `2.0.0`, `1.10`, `latest`). Defaults to latest supported GA release. +- `--manifest-file `: Path to a local Backstage release manifest JSON file for air-gapped/offline verification. +- `--json`: Output structured JSON suitable for CI/CD automation and scripts. + +### Version Mapping & 3-Tier Resolution + +RHDH versions (e.g. `2.1.0`) differ from Backstage versions (e.g. `1.54.6`). `rhdh-cli` resolves the target version using a 3-tier strategy: + +1. **Remote Metadata (Tier 1):** Fetches `build-metadata.json` from the target RHDH release branch in the `redhat-developer/rhdh` repository. +2. **Static Compatibility Matrix (Tier 2):** Fallback table embedded in the CLI for offline use or when remote lookups are skipped (`RHDH_OFFLINE=true`): + - `2.1.0` / `2.1` $\rightarrow$ Backstage `1.54.6` + - `2.0.4` / `2.0.0` / `2.0` $\rightarrow$ Backstage `1.52.0` + - `1.10.0` / `1.10` $\rightarrow$ Backstage `1.49.4` + - `1.9.0` / `1.9` $\rightarrow$ Backstage `1.45.3` + - `1.8.0` / `1.8` $\rightarrow$ Backstage `1.42.5` +3. **Manifest Resolution (Tier 3):** Fetches the concrete package manifest from `versions.backstage.io` (or a local `--manifest-file`). To target a Backstage version directly, prefix it with `backstage:`, e.g. `--rhdh-version backstage:1.54.0`. + +### Audit Statuses + +| Status | Symbol | Meaning | +| -------------- | ------ | ------------------------------------------------------------------- | +| `match` | `✓` | Declared dependency matches the exact manifest version | +| `mismatch` | `✗` | Declared dependency version differs from the manifest version | +| `unmanifested` | `⚠` | `@backstage/*` package is not part of the official release manifest | +| `unverifiable` | `⚠` | Package uses `backstage:^` without a readable `backstage.json` | + +**Exit Codes:** + +- `0`: All `@backstage/*` dependencies match the target release manifest. +- `1`: Version mismatches or unmanifested packages were detected. + +### CI Pipeline Integration + +Use `plugin check-versions` in your CI workflow to ensure pull requests do not introduce drifted dependencies: + +```yaml +# .github/workflows/ci.yaml +- name: Audit Backstage Dependencies + run: | + npx @red-hat-developer-hub/cli plugin check-versions --rhdh-version 2.1 --json +``` + +If mismatches are found, the command exits with code 1, reports mismatched packages, and provides the remediation command: + +``` +Remediation: Run rhdh-cli plugin upgrade 2.1.0 to align dependencies with RHDH v2.1.0. +``` + +--- + +## Upgrading Plugin Dependencies (`plugin upgrade`) + +Aligns all `@backstage/*` dependencies in `package.json` (`dependencies`, `devDependencies`, `peerDependencies`) and `backstage.json` to the target RHDH release manifest versions. + +### Syntax & Options + +```bash +rhdh-cli plugin upgrade [rhdhVersion] [options] +rhdh-cli plugin versions:bump [rhdhVersion] [options] # alias +``` + +**Arguments:** + +- `[rhdhVersion]`: Target RHDH version (e.g. `2.1.0`, `2.1`, `2.0.0`, `latest`). Defaults to latest GA release when omitted. + +**Options:** + +- `--dry-run`: Displays planned package modifications in a table without modifying files on disk. +- `--skip-install`: Updates `package.json` and `backstage.json` but skips running the package manager install. +- `--manifest-file `: Path to a local Backstage release manifest for offline/air-gapped usage. +- `--json`: Output upgrade results as structured JSON. + +### Dry-Run Preview + +To inspect planned version changes without altering any files: + +```bash +rhdh-cli plugin upgrade 2.1.0 --dry-run +``` + +Output: + +``` +Resolving Backstage version for RHDH v2.1.0... +Target Backstage release: 1.54.9 [remote] + +Planned Dependency Upgrades: + +Package Section Current Target Status +------------------------------------------------------------------- +@backstage/core-plugin-api dependencies ^1.12.7 ^1.12.9 UPGRADE +@backstage/core-components dependencies ^0.18.11 ^0.18.13 UPGRADE + +Dry run completed. 2 dependencies would be updated in package.json. +``` + +### Lockfile Synchronization + +By default, after updating `package.json` and `backstage.json`, `plugin upgrade` automatically detects whether your project uses Yarn (`yarn.lock`) or npm (`package-lock.json`) and runs `yarn install` or `npm install` to synchronize lockfiles. + +Use `--skip-install` if you want to inspect file changes or run your install separately with custom flags: + +```bash +rhdh-cli plugin upgrade 2.1.0 --skip-install +``` + +### Range Preservation & Non-Backstage Packages + +- **Preserves Specifier Style:** If your dependency was declared as `^1.12.0`, `~1.12.0`, or `1.12.0`, the prefix is preserved when bumping to the target version (e.g. `^1.12.9`). +- **Preserves Third-Party Packages:** Dependencies outside the `@backstage/*` namespace (e.g. `react`, `lodash`, `express`) are left untouched. +- **Updates `backstage.json`:** Synchronizes the `version` field in `backstage.json` when present. + +--- + +## Local Containerized Runtime Development (`plugin dev`) + +Drives an end-to-end local development workflow using [RHDH Local](https://github.com/redhat-developer/rhdh-local) and Podman Compose or Docker Compose. The CLI exports the plugin, stages it into RHDH Local's bind-mounted plugin directory, manages containers, and waits for HTTP readiness. + +``` +┌──────────────────┐ plugin export ┌────────────────────────┐ +│ Plugin Project │ ────────────────────────► │ local-plugins/ │ +└──────────────────┘ └───────────┬────────────┘ + │ + Compose bind-mount + install + │ + ▼ + ┌───────────────────────┐ + │ RHDH Local Runtime │ + │ http://localhost │ + └───────────────────────┘ +``` + +### Prerequisites + +1. An existing checkout of [RHDH Local](https://github.com/redhat-developer/rhdh-local). +2. Podman Compose (`podman-compose`) or Docker Compose (`docker compose`) installed and available on `PATH`. + +Set the `RHDH_LOCAL_DIR` environment variable to avoid passing `--rhdh-local-dir` on every invocation: + +```bash +export RHDH_LOCAL_DIR=/path/to/rhdh-local +``` + +### Lifecycle Subcommands + +Run `rhdh-cli plugin dev [options]`: + +| Subcommand | Description | +| ----------------- | --------------------------------------------------------------------------------------------- | +| `start` (default) | Build & export the plugin, stage into RHDH Local, start containers, and wait for readiness | +| `update` | Re-export and re-stage the plugin into the running runtime with readiness polling | +| `restart` | Restart the RHDH service without re-exporting the plugin (useful after modifying configs) | +| `status` | Report interpreted container and plugin-installer status | +| `logs` | Stream or display container logs (`--rhdh`, `--installer`, `--follow`) | +| `stop` | Stop and remove RHDH Local runtime containers (add `--clean` to remove networks/staged files) | + +### Automated Configuration with `--configure` + +On initial startup, supply `--configure` to automatically register the plugin in RHDH Local's configuration: + +```bash +rhdh-cli plugin dev start --configure --rhdh-local-dir /path/to/rhdh-local +``` + +`--configure` adds an include for `configs/dynamic-plugins/rhdh-cli.generated.local.yaml` to `dynamic-plugins.override.yaml` (which is gitignored in RHDH Local), leaving user-defined configuration untouched. + +`start` prints labeled progress phases: + +- `[1/4] Build and export plugin` +- `[2/4] Start RHDH Local runtime` +- `[3/4] Install dynamic plugins` +- `[4/4] Wait for RHDH readiness` + +Once reachable, the CLI prints the URL to open in your browser: + +``` +RHDH is ready at http://localhost:7007 +``` + +### Continuous Development with `--watch` + +Pass `--watch` to keep the CLI running in the background. It monitors `src/`, `package.json`, and `tsconfig.json` and automatically triggers debounced, serialized export/stage/restart cycles whenever source files change: + +```bash +# Start runtime and watch for changes +rhdh-cli plugin dev start --watch + +# Or attach watcher to an already running runtime +rhdh-cli plugin dev update --watch +``` + +Features of watch mode: + +- **Debounced (500ms):** Coalesces rapid sequential file saves into a single update cycle. +- **Serialized Cycles:** If changes occur while an update is actively running, exactly one follow-up cycle runs after completion. +- **Event-Driven Waits:** Listens to container lifecycle events (`die`/`start`) rather than polling raw subprocesses. +- **Readiness Notification:** Prompts you to refresh your browser only when RHDH is confirmed ready. + +### Inspecting Runtime & Logs + +```bash +# Check container and installer status +rhdh-cli plugin dev status + +# Stream application logs +rhdh-cli plugin dev logs --follow + +# Inspect installer logs if plugin failed to load +rhdh-cli plugin dev logs --installer +``` + +--- + +## Exporting & Packaging Plugins + +### Dynamic Export (`plugin export`) + +Prepares an exported dynamic plugin in `./dist-dynamic/` ready to be loaded by RHDH's dynamic plugin loader: + +```bash +rhdh-cli plugin export +``` + +For frontend plugins: + +- Uses Backstage's standard Module Federation and NFS metadata (`backstage.features`). +- Generates `dist/remoteEntry.js` and dynamic package manifests. + +For backend plugins: + +- Validates that `dist-types/` declarations exist (run `yarn tsc` first). +- Packages runtime dependencies and generates the dynamic plugin entry point. + +### OCI Container Packaging (`plugin package`) + +Packages exported plugins from `./dist-dynamic/` into a container image for distribution via registries like Quay.io: + +```bash +# Package to local container image using Podman (default) +rhdh-cli plugin package --tag quay.io/my-org/my-plugin:v1.0.0 + +# Using Docker instead of Podman +rhdh-cli plugin package --tag quay.io/my-org/my-plugin:v1.0.0 --container-tool docker + +# Package to a directory +rhdh-cli plugin package --export-to /path/to/output-dir +``` + +Requirements for `plugin package`: + +- `bash`, `npm` (v7+), and `tar` available on `$PATH`. +- `podman`, `docker`, or `buildah` when packaging with `--tag`. + +--- + +## Air-Gapped & Offline Operations + +In air-gapped or restricted-network environments without access to `github.com` or `versions.backstage.io`, `rhdh-cli` supports fully offline execution: + +1. **Supply a Local Backstage Manifest (`--manifest-file`):** Download the Backstage release manifest JSON (from `https://versions.backstage.io/v1/releases//manifest.json`) and point the CLI to it: + + ```bash + rhdh-cli plugin check-versions --rhdh-version 2.1.0 --manifest-file /path/to/manifest.json + rhdh-cli plugin upgrade 2.1.0 --manifest-file /path/to/manifest.json + ``` + + You can also set the `BACKSTAGE_MANIFEST_FILE` environment variable globally. + +2. **Skip GitHub Metadata Lookups (`RHDH_OFFLINE=true`):** Set `RHDH_OFFLINE=true` to force the version resolver to use the embedded static compatibility matrix (Tier 2) and bypass remote network calls: + + ```bash + export RHDH_OFFLINE=true + export BACKSTAGE_MANIFEST_FILE=/path/to/manifest.json + + rhdh-cli plugin check-versions --rhdh-version 2.1.0 + rhdh-cli plugin upgrade 2.1.0 + ``` + +--- + +## Reporting Issues + +Report bugs or feature requests through the Jira project: [Red Hat Developer Hub (RHIDP)](https://issues.redhat.com/projects/RHIDP/summary). From 78caf1ecdc06f9a8d6ed5c95b888f73ca7540c76 Mon Sep 17 00:00:00 2001 From: Stan Lewis Date: Fri, 2 Oct 2026 14:45:23 -0400 Subject: [PATCH 2/3] docs(plugin): address fullsend review feedback on plugin development guide - Add --name option to plugin new syntax reference - Avoid hardcoding current GA version in --rhdh-version option description - Add missing 1.7.0 and 1.6.0 entries to static compatibility matrix table - Clarify Yarn lockfile detection behavior in lockfile synchronization section - Accurately describe stop --clean behavior preserving staged dynamic plugin artifacts - Correct container event types and clarify HTTP readiness polling in watch mode Assisted-By: opencode Signed-off-by: Stan Lewis rh-pre-commit.version: 2.4.0 rh-pre-commit.check-secrets: ENABLED --- docs/Plugin-Development-CLI.md | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/docs/Plugin-Development-CLI.md b/docs/Plugin-Development-CLI.md index 44830eb..8464cb2 100644 --- a/docs/Plugin-Development-CLI.md +++ b/docs/Plugin-Development-CLI.md @@ -78,9 +78,10 @@ rhdh-cli plugin new [options] **Options:** +- `--name `: The plugin name (alternative to positional ``). - `--type `: Plugin type: `frontend`, `backend`, or `catalog-processor-module`. - `--template `: Upstream template name from `@backstage/cli-module-new` (alternative to `--type`). -- `--rhdh-version `: Target RHDH release version for dependency pinning (e.g. `2.1.0`, `2.1`, `2.0.0`). Defaults to the latest supported GA release (`2.1.0`). +- `--rhdh-version `: Target RHDH release version for dependency pinning (e.g. `2.1.0`, `2.1`, `2.0.0`). Defaults to the latest supported GA release. - `--output `: Target directory for the scaffolded project (defaults to ``). - `--plugin-package `: Override the generated `package.json` package name (defaults to `@internal/backstage-plugin-`). - `--module-id `: Override the module identifier for module-type templates (defaults to ``). @@ -153,6 +154,8 @@ RHDH versions (e.g. `2.1.0`) differ from Backstage versions (e.g. `1.54.6`). `rh - `1.10.0` / `1.10` $\rightarrow$ Backstage `1.49.4` - `1.9.0` / `1.9` $\rightarrow$ Backstage `1.45.3` - `1.8.0` / `1.8` $\rightarrow$ Backstage `1.42.5` + - `1.7.0` / `1.7` $\rightarrow$ Backstage `1.39.1` + - `1.6.0` / `1.6` $\rightarrow$ Backstage `1.36.1` 3. **Manifest Resolution (Tier 3):** Fetches the concrete package manifest from `versions.backstage.io` (or a local `--manifest-file`). To target a Backstage version directly, prefix it with `backstage:`, e.g. `--rhdh-version backstage:1.54.0`. ### Audit Statuses @@ -236,7 +239,7 @@ Dry run completed. 2 dependencies would be updated in package.json. ### Lockfile Synchronization -By default, after updating `package.json` and `backstage.json`, `plugin upgrade` automatically detects whether your project uses Yarn (`yarn.lock`) or npm (`package-lock.json`) and runs `yarn install` or `npm install` to synchronize lockfiles. +By default, after updating `package.json` and `backstage.json`, `plugin upgrade` automatically detects Yarn (`yarn.lock`) presence (defaulting to npm when no `yarn.lock` is found) and runs `yarn install` or `npm install` to synchronize lockfiles. Use `--skip-install` if you want to inspect file changes or run your install separately with custom flags: @@ -285,14 +288,14 @@ export RHDH_LOCAL_DIR=/path/to/rhdh-local Run `rhdh-cli plugin dev [options]`: -| Subcommand | Description | -| ----------------- | --------------------------------------------------------------------------------------------- | -| `start` (default) | Build & export the plugin, stage into RHDH Local, start containers, and wait for readiness | -| `update` | Re-export and re-stage the plugin into the running runtime with readiness polling | -| `restart` | Restart the RHDH service without re-exporting the plugin (useful after modifying configs) | -| `status` | Report interpreted container and plugin-installer status | -| `logs` | Stream or display container logs (`--rhdh`, `--installer`, `--follow`) | -| `stop` | Stop and remove RHDH Local runtime containers (add `--clean` to remove networks/staged files) | +| Subcommand | Description | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `start` (default) | Build & export the plugin, stage into RHDH Local, start containers, and wait for readiness | +| `update` | Re-export and re-stage the plugin into the running runtime with readiness polling | +| `restart` | Restart the RHDH service without re-exporting the plugin (useful after modifying configs) | +| `status` | Report interpreted container and plugin-installer status | +| `logs` | Stream or display container logs (`--rhdh`, `--installer`, `--follow`) | +| `stop` | Stop RHDH Local runtime containers; add `--clean` to also remove containers and networks (volumes, configuration, and staged plugin artifacts are preserved) | ### Automated Configuration with `--configure` @@ -333,7 +336,7 @@ Features of watch mode: - **Debounced (500ms):** Coalesces rapid sequential file saves into a single update cycle. - **Serialized Cycles:** If changes occur while an update is actively running, exactly one follow-up cycle runs after completion. -- **Event-Driven Waits:** Listens to container lifecycle events (`die`/`start`) rather than polling raw subprocesses. +- **Event-Driven Waits:** Listens to container lifecycle events (`died`/`die` for installer completion, `cleanup`/`die` for container teardown) with HTTP readiness polling for RHDH service availability. - **Readiness Notification:** Prompts you to refresh your browser only when RHDH is confirmed ready. ### Inspecting Runtime & Logs From 575afc04a213d48978e0c25d95cd443905de73b7 Mon Sep 17 00:00:00 2001 From: Stan Lewis Date: Mon, 5 Oct 2026 10:14:29 -0400 Subject: [PATCH 3/3] docs(plugin): update plugin new options and dev progress labels - Document --manifest-file option for plugin new and air-gapped usage - Align dev start progress phase labels with CLI log output Assisted-By: opencode Signed-off-by: Stan Lewis rh-pre-commit.version: 2.4.0 rh-pre-commit.check-secrets: ENABLED --- docs/Plugin-Development-CLI.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/Plugin-Development-CLI.md b/docs/Plugin-Development-CLI.md index 8464cb2..30ddb9c 100644 --- a/docs/Plugin-Development-CLI.md +++ b/docs/Plugin-Development-CLI.md @@ -85,6 +85,7 @@ rhdh-cli plugin new [options] - `--output `: Target directory for the scaffolded project (defaults to ``). - `--plugin-package `: Override the generated `package.json` package name (defaults to `@internal/backstage-plugin-`). - `--module-id `: Override the module identifier for module-type templates (defaults to ``). +- `--manifest-file `: Path to a local Backstage release manifest JSON file for air-gapped/offline scaffolding. **Example:** @@ -309,10 +310,10 @@ rhdh-cli plugin dev start --configure --rhdh-local-dir /path/to/rhdh-local `start` prints labeled progress phases: -- `[1/4] Build and export plugin` -- `[2/4] Start RHDH Local runtime` -- `[3/4] Install dynamic plugins` -- `[4/4] Wait for RHDH readiness` +- `[1/4] Building and exporting plugin...` +- `[2/4] Starting RHDH Local runtime...` +- `[3/4] Installing dynamic plugins...` +- `[4/4] Waiting for RHDH to be ready...` Once reachable, the CLI prints the URL to open in your browser: @@ -403,6 +404,7 @@ In air-gapped or restricted-network environments without access to `github.com` 1. **Supply a Local Backstage Manifest (`--manifest-file`):** Download the Backstage release manifest JSON (from `https://versions.backstage.io/v1/releases//manifest.json`) and point the CLI to it: ```bash + rhdh-cli plugin new my-custom-plugin --type frontend --manifest-file /path/to/manifest.json rhdh-cli plugin check-versions --rhdh-version 2.1.0 --manifest-file /path/to/manifest.json rhdh-cli plugin upgrade 2.1.0 --manifest-file /path/to/manifest.json ``` @@ -415,6 +417,7 @@ In air-gapped or restricted-network environments without access to `github.com` export RHDH_OFFLINE=true export BACKSTAGE_MANIFEST_FILE=/path/to/manifest.json + rhdh-cli plugin new my-custom-plugin --type frontend rhdh-cli plugin check-versions --rhdh-version 2.1.0 rhdh-cli plugin upgrade 2.1.0 ```