Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
149 lines (115 loc) · 4.52 KB

GETTING_STARTED.md

File metadata and controls

149 lines (115 loc) · 4.52 KB
Raw

Getting Started

This walks through installing Seams in a fresh Rails app and generating your first canonical engine.

Prerequisites

  • Ruby 3.2+
  • Rails 7.1+ (8.x recommended)
  • A new or existing Rails application

1. Install

# Gemfile
gem "seams"
bundle install
bin/rails generate seams:install

The install generator scaffolds:

  • config/initializers/seams.rb
  • config/seams_engines.rb — registers each engine on the host's load path; require_relative "seams_engines" is injected into config/application.rb so engines load before Rails.application.initialize!
  • engines/.keep
  • lib/tasks/seams.rake
  • .github/workflows/ci.yml — lint + brakeman + per-engine test matrix
  • bin/seams — short CLI wrapper
  • script/run_affected_tests.sh, script/collate_coverage.rb — host-local helpers
  • doc/ARCHITECTURE.md — per-host architecture template

2. Generate your first engine

bin/seams auth

Look at what it created:

$ tree engines/auth -L 2
engines/auth
├── LICENSE
├── README.md
├── auth.gemspec
├── app/
│   ├── controllers/
│   ├── models/
│   └── views/
├── config/
│   └── routes.rb
├── db/
│   └── migrate/
├── lib/
└── spec/

3. Wire it up

Add the engine's mount line to your host routes:

# config/routes.rb
Rails.application.routes.draw do
  mount Auth::Engine, at: "/auth"
end

Add the authentication concern to your ApplicationController:

class ApplicationController < ActionController::Base
  include Auth::Authentication
end

Run migrations:

bin/rails db:migrate

4. Generate more engines

bin/seams core                          # shared primitives (Current, AuditLog, concerns)
bin/seams accounts                      # tenant boundary + Membership + system actor
bin/seams notifications                 # outbound email/SMS, swappable adapters
bin/seams notifications --channels in_app,email   # or pick a subset (default: all)
bin/seams billing                       # Stripe subscriptions + webhooks
bin/seams teams                         # multi-tenant teams + invitations
bin/seams teams --with roles            # or pick a subset of team features (default: all)
bin/seams permissions                   # host-editable role → ability grant map
bin/seams admin                         # Administrate dashboards (opt-in; see ARCHITECTURE_WAVE_11.md)
bin/seams design --shell                # design system + app layout + starter dashboard

Every time you generate a new engine the existing engines' .rubocop.yml files are auto-updated so the boundary cops cover the new engine without manual edits.

The recommended order is core → auth → accounts → notifications → billing → teams. Some engines depend on each other (accounts on auth, billing on accounts) — see each engine's README for the "Requires:" line. permissions, admin, and design are opt-in and can be added at any time. Run bin/seams design --shell to also get a ready-to-boot application layout and signed-in dashboard, which makes the other engines visible in a real, styled UI.

5. Inspect what you have

bin/seams list

Lists every engine and the events it emits.

6. Run the boundary cops

bundle exec rubocop

Per-engine .rubocop.yml already loads seams/cops. CI runs the same lint job in .github/workflows/ci.yml.

7. Run the engine specs

bin/seams test auth

Each engine has its own spec/ directory. The CI workflow runs all of them in parallel (one job per engine).

Next steps