Plugins

Belt plugins are separate gems that extend the CLI and runtime. They're discovered automatically — no registration file or initializer hook needed.

Using a Plugin

# Gemfile
gem "belt-messaging"

bundle install
belt generate messaging    # run the plugin's generator
belt destroy messaging     # remove what the generator created

Available Plugins

Gem Purpose
belt-messaging Two-way SMS via AWS End User Messaging
belt-pay Stripe payments & subscriptions

Creating a Plugin

Scaffold a new plugin gem:

belt plugin new notifications
belt plugin new pay --path ~/Code --summary "Stripe payments for Belt"

This creates a gem with the correct structure and Belt integration points.

Plugin Discovery Contract

Belt discovers plugins automatically when:

  1. Gem is in the app's Gemfile and bundled
  2. Gem has a file at lib/belt/generators/<name>_generator.rb
  3. Class is Belt::Generators::<Name>Generator
  4. Class implements .run(args) (required)

Optional: .destroy(args) and .description for destroy path and help text.

Generator Checklist

A good plugin generator typically installs:

  1. Terraform module → infrastructure/modules/<name>/
  2. Lambda config → config/lambda/<name>.yml
  3. Lambda entrypoint → lambda/<name>.rb using Belt::LambdaHandler
  4. Routes / schema → inject into routes or schema when needed
  5. Optional overrides → --controllers flag for app-local subclasses
  6. Destroy path → removes everything the generator created
  7. Help text → .description + --help

Plugin Layout

belt-messaging/
├── belt-messaging.gemspec
├── lib/
│   ├── belt-messaging.rb              # require entrypoint
│   └── belt/
│       ├── messaging.rb               # Runtime API
│       ├── messaging/
│       │   ├── configuration.rb
│       │   ├── version.rb
│       │   ├── controllers/           # Default controllers
│       │   └── templates/             # ERB templates for generator
│       └── generators/
│           └── messaging_generator.rb # ← auto-discovered
└── spec/

Development Workflow

Point a Belt app at your plugin during development:

# In the app Gemfile
gem "belt-notifications", path: "../belt-notifications"

belt deploy detects path: gems and vendors them into vendor/cache for Lambda packaging.

See Also

Raw markdown