You've already forked tribes-plugin-template
112 lines
2.8 KiB
Markdown
112 lines
2.8 KiB
Markdown
# Tribes Plugin Template
|
|
|
|
Template for creating [Tribes](https://github.com/your-org/tribes) plugins.
|
|
|
|
## Getting Started
|
|
|
|
1. Click **"Use this template"** on GitHub to create your own repo
|
|
2. Clone and rename:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
mix deps.get
|
|
mix test
|
|
```
|
|
|
|
## Development
|
|
|
|
For local development alongside a Tribes checkout:
|
|
|
|
```bash
|
|
# Symlink into the host plugins directory
|
|
cd /path/to/tribes
|
|
ln -s /path/to/your-plugin plugins/your_plugin
|
|
|
|
# Start Tribes dev server — your plugin loads automatically
|
|
iex --sname dev -S mix phx.server
|
|
```
|
|
|
|
Edit your plugin source. Phoenix code reloader picks up changes.
|
|
|
|
## 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:
|
|
|
|
```json
|
|
{
|
|
"name": "your_plugin",
|
|
"provides": ["some_capability@1"],
|
|
"requires": ["ecto@1"],
|
|
"enhances_with": ["inference@1"]
|
|
}
|
|
```
|
|
|
|
- **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](https://github.com/your-org/tribes/blob/master/docs/PLUGINS.md) 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`
|
|
|
|
For DB setup/migrations in local development, run:
|
|
|
|
```bash
|
|
mix tribes.migrate
|
|
```
|
|
|
|
This runs Tribes + Parrhesia + plugin migrations via `Tribes.Release`.
|
|
|
|
## Building for Release
|
|
|
|
```bash
|
|
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.
|