Use when the user is customizing the Spree admin (the `spree_admin` gem) — adding a new resource page, registering a sidebar item, customizing a column in an admin table, overriding a view, scaffolding a new admin section. Common phrasings include "add admin page", "Rails admin", "spree_admin", "scaffold admin resource", "admin sidebar", "override admin view", "Hotwire admin", "Turbo admin".
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
name
spree-admin
description
Use when the user is customizing the Spree admin (the `spree_admin` gem) — adding a new resource page, registering a sidebar item, customizing a column in an admin table, overriding a view, scaffolding a new admin section. Common phrasings include "add admin page", "Rails admin", "spree_admin", "scaffold admin resource", "admin sidebar", "override admin view", "Hotwire admin", "Turbo 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:
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):
namespace :admin { resources :brands } injected into the add_routes block
The generator also injects routes into backend/config/routes.rb, inside the Spree::Core::Engine.add_routes do block (present in the spree-starter template). If your routes.rb lacks that block, add the routes manually:
# backend/config/routes.rbRails.application.routes.draw doSpree::Core::Engine.add_routes do
namespace :admindo
resources :brandsendend
mount Spree::Core::Engine, at:'/'end
add_routes (not raw Spree::Core::Engine.routes.append) is the supported mechanism — it guards against routes being drawn twice when the app reloads.
(If you're using spree:api_resource for the API, the routes for the API are separate from the admin routes — they live in different namespaces.)
Restart Rails to pick up the new initializers and routes:
spree restart
Customizing the sidebar
Sidebar entries are registered in initializers. Pattern:
# backend/config/initializers/spree_admin_brands_navigation.rbRails.application.config.after_initialize doSpree.admin.navigation.sidebar.add :brands,
label::brands, # i18n key or stringurl::admin_brands_path, # symbol → route helper, or stringicon:'list', # Tabler icon name (https://tabler.io/icons)position:55, # lower = earlier in sidebaractive: -> { controller_name == 'brands' }, # when to highlightif: -> { can?(:manage, Spree::Brand) } # CanCanCan visibility checkend
Common nav patterns:
# Top-level item that opens a sub-menuSpree.admin.navigation.sidebar.add :marketing, label::marketing, position:30do |nav|
nav.add :promotions, label::promotions, url::admin_promotions_path, position:10
nav.add :coupon_codes, label::coupon_codes, url::admin_coupon_codes_path, position:20end# Remove an existing entrySpree.admin.navigation.sidebar.remove :reports# Reorder an existing entrySpree.admin.navigation.sidebar.update :products, position:5
The full nav API is in spree/admin/app/models/spree/admin/navigation.rb if you need to read the source.
Customizing admin tables
Most admin listing pages (Products, Orders, Promotions, etc.) use a registered table definition — see the gem's config/initializers/spree_admin_tables.rb for the registered keys (note: the Customers page is registered as :users; a few pages like Payment Methods don't use the table registry). Add, remove, or reorder columns from an initializer:
# backend/config/initializers/spree_admin_products_table_customization.rbRails.application.config.after_initialize do# Add a column to the existing Products tableSpree.admin.tables.products.add :brand_name,
label::brand, # i18n keytype::string, # :string | :number | :date | :datetime | :money | :status | :link | :boolean | :image | :custom | :associationsortable:true,
filterable:true,
default:true, # visible by default (vs opt-in via column toggle)position:25# Remove a columnSpree.admin.tables.products.remove :sku# Update an existing columnSpree.admin.tables.products.update :name, label::product_nameend
For tables you generate yourself (via spree:admin:scaffold), the initializer is emitted with sensible defaults — name, created_at, updated_at. Add your domain-specific columns there.
Custom column rendering: when a column's value isn't a direct attribute, define a method on the model or a presenter/decorator. The column's key (the first argument to add) is used as the lookup method by default; pass method: to point at a different method name or a lambda that receives the record. For example, if you add a brand_name column to the Products table, define brand_name on the Product model or a presenter:
# In your model or decoratordefbrand_name
brand&.name
end
Overriding views
Drop the same-pathed file in the host app and Rails uses it. The gem ships spree/admin/app/views/spree/admin/products/index.html.erb; you override it at backend/app/views/spree/admin/products/index.html.erb.
Two real gotchas:
Copy the full file first, then edit. Partial overrides don't work — Rails picks the host app's file entirely. Use bundle show spree_admin to find the gem's view source.
View files have a data-controller Stimulus binding for interactive behavior. If you delete a data-controller="…" attribute, the related JS stops working. Keep the bindings unless you're explicitly replacing them.
For lighter overrides, use the admin's named injection points instead of overriding whole views. Views render registered partial lists (e.g. head, body_end, products_header, product_form) via render_admin_partials. Create your partial (e.g. backend/app/views/spree/admin/shared/_my_banner.html.erb) and register it in an initializer:
List all injection points with Spree.admin.partials.keys in a console.
Building admin UI — the form builder, components, and helpers
When you write admin views or partials (a scaffolded resource form, an injected product_form section, an overridden view), use the admin's own UI vocabulary instead of raw Rails helpers — you get consistent styling, labels, error display, and i18n for free.
Form builder (the important one)
Every admin form_with automatically uses Spree::Admin::FormBuilder (default_form_builder in the admin's BaseController) — no setup needed:
The full method set: spree_text_field, spree_number_field, spree_money_field (locale-aware separators, normalizes to decimal on submit, appends the currency symbol), spree_email_field, spree_date_field, spree_datetime_field, spree_text_area (auto-grows), spree_rich_text_area (Trix), spree_select / spree_collection_select (pass autocomplete: true for a searchable dropdown — use it on any select with 20+ options), spree_check_box, spree_radio_button (pass an explicit :id to bind the label to a specific radio; otherwise the label is matched by value), spree_file_field (drag-and-drop, preview, crop: true, allowed_file_types:).
Common options on every method: label: (string, or false to hide), required: (renders the asterisk), help: (text under the field), help_bubble: (tooltip icon next to the label), class:. Validation errors render under the field automatically; labels resolve via i18n (spree.<attribute> then activerecord.attributes.spree/<model>.<attribute>).
UI components
Helper-rendered components matching the admin's design system — use these instead of hand-rolled markup:
Model preferences:preference_fields / preference_field_for — render form inputs for a model's preference :x declarations automatically (this is how payment-method and store settings forms are built)
Full references ship in the local docs: node_modules/@spree/docs/dist/developer/admin/form-builder.md, components.md, and helper-methods.md.
Decorating admin controllers
The Spree admin controllers are normal Rails controllers — you can decorate them like any other. Scaffold the file with spree generate controller_decorator Spree::Admin::ProductsController — it emits backend/app/controllers/spree/admin/products_controller_decorator.rb with the prepended hook and the prepend wiring (the generator nests the modules and puts the fully-qualified prepend line outside; this equivalent hand-written form is more compact):
This is more invasive than nav/table customization — only reach for it when the action's behavior needs to change. Check whether a subscriber (for side effects) or a service swap (for business logic) would work first. See the spree-project skill for the full customization decision tree.
Stimulus controllers — admin interactivity
The Rails admin uses Stimulus + Turbo for client-side interactivity. Existing controllers live at spree_admin/app/javascript/spree/admin/controllers/:
Controller
What it does
sidebar_controller.js
Sidebar toggle + persistence
variants_form_controller.js
Variant management on product edit
page_builder_controller.js
Drag-and-drop CMS page builder
bulk_editor_controller.js
Multi-row table editing
dropdown_controller.js
Dropdown menus
To add your own Stimulus controller, drop it at backend/app/javascript/controllers/ and register it via the importmap (backend/config/importmap.rb). Reference it from a view with data-controller="my-controller".
For Turbo Streams (server-pushed UI updates), the same patterns apply as any Rails 7+ Hotwire app — render turbo_stream.* from the controller, target frames by ID.
Decision tree: what kind of admin change is this?
Want to...
Use
Add a sidebar item linking to your own page
Spree.admin.navigation.sidebar.add in an initializer
Add a column to an admin table
Spree.admin.tables.<name>.add in an initializer
Add a new resource CRUD section
bin/rails g spree:admin:scaffold Spree::YourModel
Write or edit a form
f.spree_* form-builder methods — see "Building admin UI" above
Add a modal / dropdown / badge / tooltip
The component helpers — see "Building admin UI" above
Change how an existing page looks
Override the view in backend/app/views/spree/admin/...
Add a new action to a controller
Decorator (last resort — see spree-project skill first)
Make a form field interactive
Stimulus controller + data-controller="..." in the view
Push real-time updates to the UI
Turbo Stream broadcasts from a subscriber or service
Change admin styling globally
Edit backend/app/assets/tailwind/spree_admin.css (created by the installer) — it imports the gem's base styles from app/assets/tailwind/spree/admin/index.css; add @theme overrides and custom Tailwind there
Where to read further
Admin source:bundle show spree_admin to find the installed gem path. The README at the root of the gem covers the philosophy.
Navigation API:Spree::Admin::Navigation source — the full method surface for nav customization.
Table API:Spree::Admin::Table (app/models/spree/admin/table.rb) and Spree::Admin::Table::Column (app/models/spree/admin/table/column.rb) inside the gem — column types, options, sorting/filtering details. The registry behind Spree.admin.tables is Spree::Admin::Engine::TablesEnvironment in lib/spree/admin/engine.rb.
Scaffold generator:bundle show spree_admin/lib/generators/spree/admin/scaffold/ has the template files you can copy for advanced customization.
Form builder / components / helpers:node_modules/@spree/docs/dist/developer/admin/form-builder.md, components.md, helper-methods.md — the full option tables for everything in "Building admin UI" above.
