create-plugin

What this skill does

<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>

<intake>

## 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.**

</intake>

<routing>

| Response | Reference |
|----------|----------|
| 1, "backend", "create backend", "API plugin", "scaffolder action" | [references/backend.md](references/backend.md) |
| 2, "frontend", "create frontend", "page", "card", "theme" | [references/frontend.md](references/frontend.md) |
| 3, "export", "package", "OCI", "tgz", "publish", "push" | [references/export.md](references/export.md) |
| 4, "wiring", "mount points", "routes", "entity tabs" | [references/wiring.md](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`. |

</routing>

## 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:

```bash
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:

```bash
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`:

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