You've already forked tribes-plugin-template
self
0ba524bad9
CI / Test (push) Failing after 21s
Update the static plugin template to match the host-backed test/precommit wrapper generated by tribes-plugin-new. Clarify dependency boundaries around host_api, ui@1, and raw Mix aliases.
63 lines
2.6 KiB
Markdown
63 lines
2.6 KiB
Markdown
# Plugin Contract
|
|
|
|
## Manifest
|
|
|
|
`manifest.json` is the runtime contract consumed by Tribes:
|
|
|
|
- `name` and `otp_app` must match the Mix application name.
|
|
- `entry_module` must be a loadable `Tribes.Plugins.*.Plugin` module.
|
|
- `provides` declares capabilities exported by the plugin.
|
|
- `requires` declares hard plugin/API contracts beyond the `host_api` foundation.
|
|
- `enhances_with` declares optional host capabilities.
|
|
- `migrations` should be `true` when `priv/repo/migrations` contains plugin migrations.
|
|
- `children` should be `true` when the plugin starts its own supervision tree.
|
|
|
|
Declare `ui@1` in `requires` when rendering through `Tribes.Plugin.Layouts.app`,
|
|
importing `Tribes.UI.Components`, or using `use Tribes.UI`. The facade is
|
|
intentionally provider-backed, so host chrome and UI consumers must make the
|
|
runtime dependency explicit.
|
|
|
|
`host_api` is the versioned foundation contract. It provides the supported
|
|
Phoenix, Ash, PubSub, data, and cluster-event APIs for plugins. Do not add
|
|
separate framework capability requirements for APIs that belong to that
|
|
foundation.
|
|
|
|
Default LiveView pages should wrap their content in `Tribes.Plugin.Layouts.app`
|
|
and use `on_mount({Tribes.Plugin.LiveUserAuth, :live_user_optional})`. This
|
|
keeps plugin pages inside the replaceable Tribes chrome while avoiding a hard
|
|
compile-time dependency on host web macros.
|
|
|
|
## Entry Modules
|
|
|
|
The template uses a thin host bridge:
|
|
|
|
```elixir
|
|
defmodule Tribes.Plugins.MyPlugin.Plugin do
|
|
defdelegate register(context), to: MyPlugin.Plugin
|
|
end
|
|
```
|
|
|
|
Keep plugin implementation code in `MyPlugin.Plugin`. Keep the bridge stable so
|
|
the host plugin manager can load it from the plugin build output.
|
|
|
|
## Host Dependencies
|
|
|
|
`tribes_plugin_api` is the release-facing `host_api` foundation. It carries the
|
|
supported plugin behaviours, helpers, Phoenix/Ash data surface, and sync DSL.
|
|
Do not add the full `:tribes` app as a production dependency.
|
|
|
|
The template intentionally splits the `:tribes` path dependency by environment:
|
|
|
|
- In `:dev`, `:tribes` is compile-only. This lets `mix compile` create the
|
|
entry-module beam expected by the host plugin manager without starting a
|
|
nested Tribes application.
|
|
- In `:test`, `:tribes` is runtime-enabled. Host-backed tests need the real
|
|
repository, endpoint pipeline, and plugin contract helpers.
|
|
|
|
## Ash Resources
|
|
|
|
For cluster-synced plugin data, add Ash resources under the plugin namespace and
|
|
use `extensions: [AshNostrSync]` only for data that should replicate across the
|
|
cluster. Prefer one UUID primary key per synced resource. Document any local-only
|
|
tables, retention policies, or side effects in plugin docs.
|