Compatibility matrix

The OpenChoreo plugin set is tested against a specific Backstage release line. Installing into a Backstage app on a different line typically requires pinning every @backstage/* package; see Troubleshooting.

Tested combination

Component	Version
Backstage release line	1.51.0
Node.js	20.x or 22.x
Yarn	4.13.x
@backstage/cli	0.36.x
OpenChoreo plugin set	1.2.x

Required resolutions

Add the following to your workspace root package.json. The MUI pin keeps material-ui-popup-state from resolving to a nested MUI 5.13.x that lacks the /version subpath (which Rspack fails to compile against). The React pins keep types consistent across the dep graph.

package.json

{
  "resolutions": {
    "@types/react": "^18",
    "@types/react-dom": "^18",
    "@mui/material": "^5.18.0"
  }
}

That is the minimum. After running yarn backstage-cli versions:bump --release 1.51.0 you do not need to copy a full @backstage/* resolutions block — versions:bump writes caret ranges to every package.json in your workspace and the lockfile pins them. Reach for explicit @backstage/* resolutions only when you hit a transitive-drift error at startup; the previous (1.1.x) install guide carried a 70-entry block because 1.1.x plugins were validated against a single point release.

Aligning your existing app

If your Backstage app is on a different release line, run:

yarn backstage-cli versions:bump --release 1.51.0
yarn install

…before adding the OpenChoreo packages.

Plugin packages

All plugins ship with both a default (legacy) export and a /alpha export for use with the New Frontend System (NFS). The default export remains the entry point for hosts on the legacy frontend; /alpha exports a createFrontendPlugin instance for use in createApp({ features: [...] }).

Core (required)

Installed and wired by section 4 of the install guide.

Package	Role	/alpha	Notes
@openchoreo/backstage-plugin	frontend-plugin	✓	Cell, Deploy, Definition tabs; overview cards.
@openchoreo/backstage-plugin-react	web-library	—	Shared React hooks (permission hooks, etc.).
@openchoreo/backstage-design-system	web-library	—	MUI v4 theme + form widgets.
@openchoreo/backstage-plugin-common	common-library	—	Constants, types, relation refs.
@openchoreo/backstage-plugin-backend	backend-plugin	—	Powers /api/openchoreo/*.
@openchoreo/backstage-plugin-catalog-backend-module	backend-plugin-module	—	Catalog entity provider + service factories.
@openchoreo/backstage-plugin-permission-backend-module-openchoreo-policy	backend-plugin-module	—	Permission policy.
@openchoreo/backstage-plugin-scaffolder-backend-module	backend-plugin-module	—	Scaffolder actions.
@openchoreo/backstage-plugin-auth-backend-module-openchoreo-auth	backend-plugin-module	—	OpenChoreo OIDC sign-in.
@openchoreo/openchoreo-client-node	node-library	—	Generated typed API client.
@openchoreo/openchoreo-auth	node-library	—	Token service + IDP middleware.

Optional tab packs

Installed and wired by sections 5–7 of the install guide. Each frontend/backend pair is installed together.

Package	Role	/alpha	Tabs delivered
@openchoreo/backstage-plugin-openchoreo-observability	frontend-plugin	✓	Component → Logs/Events/Metrics/Alerts/Wirelogs, System → Logs/Traces/Incidents/RCA/Cost.
@openchoreo/backstage-plugin-openchoreo-observability-backend	backend-plugin	—	Backend + /resolve-urls for the observability tabs.
@openchoreo/backstage-plugin-openchoreo-ci	frontend-plugin	✓	Component → Build.
@openchoreo/backstage-plugin-openchoreo-ci-backend	backend-plugin	—	Backend for the Build tab.
@openchoreo/backstage-plugin-openchoreo-workflows	frontend-plugin	✓	Standalone /workflows page + Runs tab on Workflow/ClusterWorkflow.
@openchoreo/backstage-plugin-openchoreo-workflows-backend	backend-plugin	—	Backend for the workflows page.

Also published

These packages live in the @openchoreo scope and ship on the same release cadence as the rest, but the canonical install guide does not wire them. They exist for downstream tools and special-case installs.

Package	Use
@openchoreo/openapi-client-generator-node	Build-time generator for the typed OpenChoreo API clients. Consumed by plugin authors, not Backstage runtime.
@openchoreo/backstage-plugin-platform-engineer-core	Platform-engineer home/dashboard surface used by the in-tree portal. Not part of the canonical install. Ships an /alpha entry point.
@openchoreo/backstage-plugin-platform-engineer-core-backend	Backend for the above.
@openchoreo/backstage-plugin-thunder-idp-client-node	TypeScript client for the ThunderID IDP user/group API. Used by catalog-backend-module-openchoreo-users below.
@openchoreo/backstage-plugin-catalog-backend-module-openchoreo-users	Syncs ThunderID users/groups into the Backstage catalog. Install only if your OpenChoreo cluster uses ThunderID as its IDP and you want user/group entities in Backstage.

Reporting compatibility issues

If you successfully install on a different Backstage release line, file an issue at openchoreo/backstage-plugins — we will add the combination to this matrix.