Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

7.7 KB
Raw Blame
---
title: Admin Dashboard
sidebarTitle: Overview
description: Customize and extend the Spree Admin Dashboard to manage products, orders, customers, promotions, and store settings for your ecommerce platform.
canonical: "https://spreecommerce.org/docs/v5/developer/admin/admin"
---

The Spree Admin Dashboard is a full-featured administration interface for managing your e-commerce store.

<Frame>
  <img src="/images/spree_admin_dashboard.png" alt="Spree Admin Dashboard" />
</Frame>

## What You Can Do

The Admin Dashboard allows store administrators to manage:

- **Products** - Create and manage products, variants, images, and inventory
- **Orders** - Process orders, refunds, and shipments
- **Customers** - View customer accounts and order history
- **Promotions** - Create discounts, coupon codes, and special offers
- **Settings** - Configure store settings, shipping, taxes, and payments

## Customization Options

As a developer, you can fully customize the Admin Dashboard:

<CardGroup cols={2}>
  <Card title="Add New Sections" icon="plus" href="/developer/tutorial/admin">
    Create entirely new admin pages for custom features like Brands, Vendors, or any custom model
  </Card>
  <Card title="Extend Existing UI" icon="puzzle-piece" href="/developer/admin/extending-ui">
    Inject custom fields, buttons, and sections into existing admin pages
  </Card>
  <Card title="Custom Navigation" icon="bars" href="/developer/admin/navigation">
    Add menu items to the sidebar or create custom navigation structures
  </Card>
  <Card title="Custom Styling" icon="palette" href="/developer/admin/custom-css">
    Add your own CSS to match your brand or modify the look and feel
  </Card>
</CardGroup>

## Architecture Overview

Spree Admin follows standard Rails conventions with some Spree-specific patterns:

```
app/
├── controllers/
│   └── spree/
│       └── admin/
│           └── products_controller.rb    # Your custom controllers
├── views/
│   └── spree/
│       └── admin/
│           └── products/
│               ├── index.html.erb        # List view
│               ├── _form.html.erb        # Shared form partial
│               └── _table_row.html.erb   # Table row partial
├── helpers/
│   └── spree/
│       └── admin/
│           └── products_helper.rb        # View helpers
└── assets/
    └── tailwind/
        └── spree_admin.css               # Custom Tailwind styles
```

## Key Concepts

### Controllers

Admin controllers inherit from `Spree::Admin::ResourceController` which provides:

- Full CRUD operations (index, new, create, edit, update, destroy)
- Automatic authorization checks
- Flash messages and redirects
- Search and filtering with Ransack

```ruby
# app/controllers/spree/admin/brands_controller.rb
module Spree
  module Admin
    class BrandsController < ResourceController
      # That's it! CRUD is handled automatically.
      # Override methods only when needed.
    end
  end
end
```

<Info>
  Learn more about creating admin sections in the [Admin Dashboard Tutorial](/v5/developer/tutorial/admin).
</Info>

### Views & Templates

Views use standard Rails ERB templates with Spree's [Form Builder](/v5/developer/admin/form-builder) and [Components](/v5/developer/admin/components):

```erb
<%# app/views/spree/admin/brands/_form.html.erb %>
<div class="card mb-6">
  <div class="card-header">
    <h5 class="card-title"><%= Spree.t(:general_settings) %></h5>
  </div>
  <div class="card-body">
    <%= f.spree_text_field :name, required: true %>
    <%= f.spree_text_area :description %>
    <%= f.spree_file_field :logo, width: 300, height: 300 %>
    <%= f.spree_check_box :active %>
  </div>
</div>
```

### JavaScript & Interactivity

Spree Admin uses [Hotwire](https://hotwire.dev/) (Turbo + Stimulus) for interactivity:

- **Turbo Drive** - Fast page navigation without full reloads
- **Turbo Frames** - Update parts of the page independently
- **Turbo Streams** - Real-time updates over WebSocket
- **Stimulus** - Lightweight JavaScript controllers

```erb
<%# Using Stimulus controllers %>
<div data-controller="dropdown">
  <button data-action="dropdown#toggle">Menu</button>
  <div data-dropdown-target="menu">...</div>
</div>
```

<Info>
  Add custom JavaScript using [Stimulus controllers](/v5/developer/admin/custom-javascript).
</Info>

### Styling

The Admin Dashboard uses [Tailwind CSS v4](https://tailwindcss.com/) for styling. You can:

- Use Tailwind utility classes directly in your views
- Override theme variables (colors, spacing, typography)
- Add custom components using `@layer components`

```erb
<%# Using Tailwind utility classes in views %>
<div class="bg-white rounded-lg shadow-sm border border-zinc-200 p-4">
  <h3 class="text-lg font-bold text-zinc-900">My Custom Card</h3>
  <p class="text-sm text-zinc-600 mt-2">Card content here</p>
</div>
```

<Info>
  Learn how to customize styles in [Custom CSS](/v5/developer/admin/custom-css).
</Info>

## Quick Reference

### Available Tools

| Tool | Purpose | Documentation |
|------|---------|---------------|
| Form Builder | Create consistent forms with validation | [Form Builder](/v5/developer/admin/form-builder) |
| Components | Dropdowns, dialogs, icons, badges, etc. | [Components](/v5/developer/admin/components) |
| Helper Methods | Navigation, links, utilities | [Helper Methods](/v5/developer/admin/helper-methods) |
| UI Extensions | Inject content into existing pages | [Extending UI](/v5/developer/admin/extending-ui) |

### Common Tasks

| Task | How To |
|------|--------|
| Add a new admin page | Use the scaffold generator: `bin/rails g spree:admin:scaffold Spree::Brand` |
| Add sidebar navigation | Use `Spree.admin.navigation.sidebar.add` in an initializer |
| Add form fields | Use `f.spree_text_field`, `f.spree_select`, etc. |
| Show flash messages | They're automatic with `ResourceController` |
| Check permissions | Use `can?(:update, @product)` in views |

### Generator Commands

<CodeGroup>

```bash Spree CLI (Docker)
# Generate a complete admin section (controller, views, routes)
spree generate spree:admin:scaffold Spree::Brand

# Generate just a controller
spree generate controller Spree::Admin::Brands --skip-routes
```

```bash Without Spree CLI
# Generate a complete admin section (controller, views, routes)
bin/rails g spree:admin:scaffold Spree::Brand

# Generate just a controller
bin/rails g controller Spree::Admin::Brands --skip-routes
```

</CodeGroup>

## Authentication & Authorization

### Authentication

Admin users must be authenticated to access the dashboard. Spree supports:

- Built-in Devise authentication
- Custom authentication adapters
- SSO integration

<Info>
  See [Authentication](/v5/developer/admin/authentication) for setup details.
</Info>

### Authorization

Spree uses [CanCanCan](https://github.com/CanCanCommunity/cancancan) for authorization:

```ruby
# Check permissions in controllers
authorize! :update, @product

# Check permissions in views
<% if can?(:destroy, @product) %>
  <%= link_to_delete(@product) %>
<% end %>
```

<Info>
  See [Permissions](/v5/developer/customization/permissions) for defining custom abilities.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Tutorial: Build Admin UI" icon="graduation-cap" href="/developer/tutorial/admin">
    Step-by-step guide to creating a complete admin section
  </Card>
  <Card title="Form Builder" icon="rectangle-list" href="/developer/admin/form-builder">
    Learn all available form field helpers
  </Card>
  <Card title="Components" icon="puzzle-piece" href="/developer/admin/components">
    Explore UI components like dropdowns, dialogs, and icons
  </Card>
  <Card title="Extending UI" icon="expand" href="/developer/admin/extending-ui">
    Add custom content to existing admin pages
  </Card>
</CardGroup>