backstage

A lightweight, mountable admin interface for Ruby on Rails 8 — no code generation, no Sprockets, no Devise.

Background

Several of my personal projects — sortirauresto.com, voices.live, planango.com, and bookscovery.com — need an admin interface. The obvious candidates were ActiveAdmin and Administrate, but both bring more than I wanted: heavy dependency trees, assumptions about your asset pipeline, and in ActiveAdmin's case a hard tie to Sprockets — which is no longer the recommended way to compile assets in Rails 8. I wanted something that would drop in cleanly with Propshaft and import maps, configure itself from a single YAML file, and stay out of the way of whatever authentication I already had.

So I built one.

What it does

Auto-discovers columns and builds index and edit pages from ActiveRecord reflection
YAML model registration — adding a model takes one line in config/backstage.yml
Optional per-resource Ruby DSL for field overrides, associations, sidebars, and custom actions
Searchable, sortable, paginated index tables with enum filter tabs
Belongs-to dropdowns, has-many checkbox lists, named dashboards with custom scopes
Turbo Stream responses for delete and custom actions — no full-page reloads
Pico CSS vendored — zero asset pipeline setup required
No auth opinions — plugs into whatever current_user method you already have

Design philosophy

The guiding principle is that configuration should be declarative and the gem should be invisible. You register a model in YAML and it works. If you need more control, you add a resource file in config/backstage/. If you need custom actions, you subclass Backstage::ResourcesController. There are no generators that scatter files through your app, no mandatory initializers, no stylesheet overrides.

Authentication is deliberately out of scope. Backstage calls a configurable method on current_user to decide whether to grant access — that's it. If your app uses Devise, Sorcery, a hand-rolled session, or anything else, it works.

How it was built

The gem was designed using the BMAD product development process. A full specification was written before a line of implementation code was produced; the spec is available in the repository. Implementation was then carried out with Claude Code, working from the spec.

Status

Backstage is experimental — use it at your own risk. That said, it is running in production across my own projects, and the public API (the YAML keys, the Ruby DSL methods, and the Turbo Stream helpers on ResourcesController) follows semantic versioning. Internal classes are not part of the public API and may change between minor versions.