Tribes Plugin Template

Template for creating Tribes plugins.

Getting Started

1. Click "Use this template" on GitHub to create your own repo
2. Clone and rename:

git clone https://github.com/you/your-plugin.git
cd your-plugin
./scripts/rename.sh your_plugin YourPlugin

3. Edit manifest.json — set description, capabilities, requirements
4. Implement your plugin in lib/your_plugin/plugin.ex
5. Run tests:

mix deps.get
mix test

Development

For local development alongside a Tribes checkout:

# Build plugin code once (host loads BEAM from _build/dev/lib/<otp_app>/ebin)
cd /path/to/your-plugin
mix compile

# Symlink into the host plugins directory
cd /path/to/tribes
ln -s /path/to/your-plugin plugins/your_plugin

# Start Tribes dev server
iex --sname dev -S mix phx.server

When you change plugin Elixir code, re-run mix compile in the plugin repo.

Project Structure

your_plugin/
├── manifest.json           # Plugin metadata (Nix build + runtime)
├── mix.exs                 # Dependencies
├── lib/
│   ├── your_plugin/
│   │   ├── plugin.ex       # Tribes.Plugin entry point
│   │   └── application.ex  # OTP supervision tree (optional)
│   └── your_plugin_web/
│       └── live/            # LiveView pages
├── assets/                 # JS/CSS (one bundle per plugin)
├── priv/
│   ├── static/             # Built assets for release
│   └── repo/migrations/    # Ecto migrations
└── test/

Manifest

manifest.json declares your plugin's identity and capabilities:

{
  "name": "your_plugin",
  "entry_module": "Tribes.Plugins.YourPlugin.Plugin",
  "host_api": "1",
  "otp_app": "your_plugin",
  "provides": ["some_capability@1"],
  "requires": ["ecto@1"],
  "enhances_with": ["inference@1"]
}

• entry_module — must be Tribes.Plugins.*.Plugin
• otp_app — required and must match name
• provides — capabilities this plugin makes available
• requires — hard dependencies (build fails without them)
• enhances_with — optional dependencies (plugin degrades gracefully)

See the Plugin System docs for the full specification.

Testing

Three test levels:

• Unit tests (test/your_plugin/) — plugin logic in isolation
• Manifest tests (test/your_plugin/manifest_test.exs) — manifest schema validation
• Contract tests (test/contract_test.exs) — runtime spec matches manifest

Run all: mix test

Building for Release

MIX_ENV=prod mix compile

mkdir -p dist/your_plugin
cp -r _build/prod/lib/your_plugin/ebin dist/your_plugin/
cp -r priv dist/your_plugin/
cp manifest.json dist/your_plugin/

For Nix-based deployment, add your plugin to the host's plugins.json.

Licence

TODO: Choose a licence.