spree-admin

Spree Legacy Rails Admin (spree_admin)

Commands below use the Spree CLI form (spree …, Docker). On a classic Rails app without the CLI (typical pre-5.4), use the native mapping in the spree-project skill — bin/rails / bundle exec rake from the app root, paths without the backend/ prefix.

The admin is a Rails engine — server-rendered ERB views, Stimulus + Turbo for interactivity, Tailwind for styling. (Spree 6.0 will introduce a new React-based admin; on Spree 5.x, spree_admin is the admin.)

Project layout

The Rails admin lives in the spree_admin gem, mounted at /admin. View it as a normal Rails app:

spree_admin gem
├── app/
│   ├── controllers/spree/admin/         # admin controllers
│   ├── views/spree/admin/<resource>/    # ERB views per resource
│   ├── helpers/spree/admin/             # view helpers
│   ├── presenters/spree/admin/          # presenter pattern for complex views
│   ├── javascript/spree/admin/          # Stimulus controllers, importmap-managed
│   └── models/spree/admin/navigation*   # nav + nav builder
└── lib/generators/spree/admin/
    ├── install/                         # bin/rails g spree:admin:install
    └── scaffold/                        # bin/rails g spree:admin:scaffold

In a host app (backend/), you customize by overriding files at the same paths under backend/app/. Rails view path resolution prefers the host app's files over the gem's.

Adding a new admin resource (the one-command path)

Spree ships an admin scaffold generator that produces the full CRUD admin for any model. After the model + migration exist (use spree:api_resource or spree:model):

spree rails g spree:admin:scaffold Spree::Brand

This emits:

File	Purpose
backend/app/controllers/spree/admin/brands_controller.rb	Controller inheriting Spree::Admin::ResourceController
backend/app/views/spree/admin/brands/index.html.erb	Listing page (renders render_table @collection, :brands; columns come from the table registry)
backend/app/views/spree/admin/brands/new.html.erb	Create form page
backend/app/views/spree/admin/brands/edit.html.erb	Edit form page
backend/app/views/spree/admin/brands/_form.html.erb	Shared form partial
backend/config/initializers/spree_admin_brands_table.rb	Table column registration
backend/config/initializers/spree_admin_brands_navigation.rb	Sidebar nav registration
backend/config/routes.rb	namespace :admin { resources :brands } injected into the add_routes block