64 lines
4.1 KiB
Markdown
64 lines
4.1 KiB
Markdown
---
|
|
name: developing-blockninja-plugins
|
|
description: Use when creating, modifying, building, or publishing BlockNinja CMS plugins or themes — work in plugins/* repos, plugin registration, blocks, templates, plugin Connect services, migrations, ninja plugin commands, check-safety for plugins, or block/core SDK usage in standalone plugin repos.
|
|
---
|
|
|
|
# Developing BlockNinja Plugins
|
|
|
|
## Overview
|
|
|
|
Never write plugin code from memory — every SDK symbol is locally verifiable. Truth lives at:
|
|
|
|
- **SDK source:** `~/src/blockninja/core` — import prefix `git.dev.alexdunmow.com/block/core/...` is the ONLY one allowed; never `block/cms/...`
|
|
- **Canonical guide:** `~/src/blockninja/cms/docs/PLUGIN_DEVELOPMENT.md`
|
|
- **Publish workflow + hard rules:** `~/src/blockninja/plugins/CLAUDE.md`
|
|
- **Exemplars:** `plugins/messenger` (compact), `plugins/symposium` (service-heavy: RPC, jobs, AI, embeddings)
|
|
|
|
Core-vs-plugin: platform-wide behavior → core; domain-specific or owns its own data/UI → plugin (decision table in PLUGIN_DEVELOPMENT.md).
|
|
|
|
## Doc routing
|
|
|
|
| Working on | Read first (under `cms/docs/`) |
|
|
|---|---|
|
|
| Scaffold, registration, blocks, `CoreServices` | PLUGIN_DEVELOPMENT.md |
|
|
| Depositing media into the library (seed `EnsureMedia` / runtime `CoreServices.Media`) | PLUGIN_DEVELOPMENT.md §Depositing Media |
|
|
| Plugin migrations / DB tables — each plugin owns a Postgres schema (named after it), never `public` | PLUGIN_DEVELOPMENT.md §Migrations |
|
|
| **Platform data tables** — provision via `Provisioner.EnsureDataTable` (`RegisterWithProvisioner`); the row-as-JSONB store the admin Data Platform / buckets / **data Views** read, idempotent + **View-rootable**. NOT the plugin's own Postgres schema above | PLUGIN_DEVELOPMENT.md §Provisioning → Data tables |
|
|
| Public HTTP routes (webhooks, widgets) | PLUGIN_HTTP_HANDLERS.md |
|
|
| Load/Unload, runtime state, goroutines | PLUGIN_LIFECYCLE_HOOKS.md |
|
|
| Themes, templates, master pages, CSS | TEMPLATE_PLUGINS.md |
|
|
| Block editor / settings UI (Module Federation) | PLUGIN_EDITOR_SDK.md |
|
|
| .so build pipeline, loader internals | compiled-plugin-architecture.md |
|
|
| Release, registry, install | `plugins/CLAUDE.md` (not cms/docs) |
|
|
|
|
## Verifying SDK symbols
|
|
|
|
Before using an unfamiliar SDK call, check: (1) the pinned SDK the build compiles against — `go doc git.dev.alexdunmow.com/block/core/plugin CoreServices` from the plugin dir; (2) nearest exemplar usage in messenger/symposium; (3) the CMS-side implementation in `cms/backend` for semantics.
|
|
|
|
**Missing capability** ⇒ two sanctioned paths only: extend `block/core` (long-term; needs SDK release + re-pin + image rebuild), or vendor the cms-internal package into the plugin's `internal/` with a provenance header (established convention — check-safety vendors cms `internal/theme` this way). NEVER `replace` directives; NEVER `block/cms` imports.
|
|
|
|
**Version pinning:** `go.mod` pins `block/core` to exactly what the CMS uses:
|
|
`grep 'block/core ' ~/src/blockninja/cms/backend/go.mod`
|
|
|
|
## Gates — run before commit / bump / publish
|
|
|
|
```bash
|
|
make # CGO build; templ/sqlc drift surfaces here
|
|
cd ~/src/blockninja/check-safety && go run . <plugin-path> # MUST exit 0
|
|
make archive-check # proves `git archive HEAD` (= what publish ships) compiles
|
|
```
|
|
|
|
check-safety traps: plugin `web/` lint extends `../../../cms/web/eslint.config.js`, so it only runs from the canonical sibling layout; raw `<button>` in plugin UI fails (use `@block-ninja/ui` Button); `any` usage warns.
|
|
|
|
## Release traps
|
|
|
|
```bash
|
|
ninja plugin bump patch # commits plugin.mod — does NOT git-tag
|
|
git tag vX.Y.Z # manual; must equal plugin.mod version (hard rule 6)
|
|
git push origin main vX.Y.Z # explicit — --follow-tags skips lightweight tags
|
|
ninja plugin publish # ships `git archive HEAD`: untracked files DON'T ship;
|
|
# web/dist and ALL generated Go must be committed
|
|
```
|
|
|
|
New plugin: `ninja plugin init`, minimal files per PLUGIN_DEVELOPMENT.md §Minimal Layout, copy the Makefile from messenger. First publish lands `private`; review via orchestrator dashboard.
|