tribes-plugin-template/docs/plugin-contract.md

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:

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.