create-plugin

<essential_principles>

Prerequisites

• Node.js 22+ and Yarn
• Container runtime (podman or docker) for OCI packaging
• Access to a container registry (e.g., quay.io) for publishing

</essential_principles>

What would you like to do?

#	Category	Command	Description
1	Create	backend	Scaffold and implement a backend dynamic plugin
2	Create	frontend	Scaffold and implement a frontend dynamic plugin
3	Package	export	Export, package, and push a plugin for RHDH deployment
4	Configure	wiring	Analyze a frontend plugin and generate wiring config

Single source of truth for command descriptions: scripts/command-metadata.json

Wait for response before proceeding.

Response	Reference
1, "backend", "create backend", "API plugin", "scaffolder action"	references/backend.md
2, "frontend", "create frontend", "page", "card", "theme"	references/frontend.md
3, "export", "package", "OCI", "tgz", "publish", "push"	references/export.md
4, "wiring", "mount points", "routes", "entity tabs"	references/wiring.md
First word doesn't match	Infer intent from context. "Create a new API plugin" → backend. "Package my plugin as OCI" → export. "Generate mount points" → wiring.

Shared Knowledge

Script paths: All scripts/ and references/ paths below are relative to this SKILL.md file's directory. Resolve them against the skill directory before invoking.

RHDH Version Resolution

Before scaffolding, determine the target RHDH version. Consult ../rhdh/references/versions.md for the compatibility matrix. If that file is not found (skill installed standalone), ask the user for the target RHDH version directly.

Scaffold Script

Both backend and frontend plugins use a unified scaffold script:

python scripts/scaffold.py \
  --type backend \
  --rhdh-version 1.9 \
  --plugin-id my-plugin

Run python scripts/scaffold.py --help for all options (--type, --path, --with-theme, --create-app-version, --json).

Export Script

Automates the full export → package → push pipeline:

python scripts/export-plugin.py \
  --plugin-dir plugins/my-plugin \
  --tag quay.io/ns/my-plugin:v0.1.0 \
  --push --clean

Run python scripts/export-plugin.py --help for all options (--format, --shared-package, --embed-package, --json).

Plugin Lifecycle

The typical workflow chains these commands:

1. backend or frontend — Scaffold and implement
2. export — Build, export, package, push
3. wiring (frontend only) — Generate dynamic-plugins.yaml config

Each reference file is self-contained. Load only the one you need.

<reference_index>

Reference Index

Command References

File	Load when...
references/backend.md	Creating a backend plugin (API, scaffolder action, processor)
references/frontend.md	Creating a frontend plugin (page, card, theme)
references/export.md	Exporting, packaging, or publishing a plugin
references/wiring.md	Generating frontend wiring configuration

Deep-Dive References

File	Load when...
references/export-options.md	Need details on --shared-package, --embed-package, dependency categories
references/packaging-formats.md	Comparing OCI vs tgz vs npm, multi-plugin bundles, private registries
references/integrity-hashes.md	Generating or verifying SHA-512/SHA-256 integrity hashes
references/frontend-wiring.md	Complete mount point, route, binding, entity tab reference
references/entity-page.md	Entity page customization — tabs, cards, conditions, grid layout

Examples

File	Contents
examples/dynamic-plugins.yaml	Backend, frontend, multi-plugin, tgz, npm, and local config patterns
examples/frontend-wiring.yaml	All frontend wiring patterns — tabs, cards, search, themes, scaffolder

</reference_index>

Common Issues

Plugin Not Loading

• Backend: Verify new backend system (createBackendPlugin) with default export
• Frontend: Verify scalprum.name matches key under dynamicPlugins.frontend.<key>
• Both: Check version compatibility with target RHDH

Build/Export Failures

• Run yarn tsc to check TypeScript errors before export
• Clear stale artifacts: rm -rf dist dist-dynamic && yarn build
• Missing deps: yarn add -D <missing-package>

MUI v5 Styles Missing (Frontend)

Add class name generator to src/index.ts:

import { unstable_ClassNameGenerator as ClassNameGenerator } from '@mui/material/className';
ClassNameGenerator.configure(componentName =>
  componentName.startsWith('v5-') ? componentName : `v5-${componentName}`
);