Spree Customization

Spree Customization — Where Does My Code Belong?

> 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.

Spree is heavily customizable. The work of any Spree project is mostly customization — wiring in external services, adding custom models, tweaking behavior, extending the admin. The thing that's hard isn't how to customize; it's which pattern fits a given problem.

This skill is a decision tree. It maps a customization need to the right specific skill — read those for the deep dive. Walk the table top to bottom; the higher options are simpler and survive upgrades better than the lower ones.

The decision tree

| What you're trying to do | Reach for | Deep-dive skill | |---|---|---| | Change merchant-facing settings (currencies, languages, tax zones, shipping methods, payment methods) | Admin Settings UI | — | | Tweak Spree's runtime behavior globally | Spree.config block (config. = …) in config/initializers/spree.rb; read anywhere via Spree::Config[:key] | (configuration is straightforward — see docs link below) | | React to something happening in Spree (order completed, product updated, customer registered, stock changed) | Events subscriber | spree-events-webhooks | | Notify an external service (ERP, CRM, fulfillment, analytics, Slack) when something happens | Events subscriber OR outbound webhook | spree-events-webhooks | | Replace how a core service computes (cart add, tax calculation, search, checkout flow, ability checks) | Dependency injection via Spree.dependencies | spree-dependencies | | Add a menu item / nav entry to the admin | Spree.admin.navigation.sidebar.add | spree-admin | | Add a section / form field to an existing admin page | Spree.admin.partials. .add ... | spree-admin | | Make a new attribute searchable / filterable in the API or admin | Spree.ransack.add_attribute(Class, :attr) | spree-api-v3 | | Customize the checkout flow (skip a step, add a step, change validation) | checkout_flow block on a Spree::Order decorator | spree-checkout | | Add a brand-new model + API endpoint (Brand, Vendor, etc.) | spree:api_resource generator | spree-resource | | Add a Spree model with no API surface (internal record, lookup table, supporting model) | spree:model generator | spree-resource | | Add an association / validation / scope / method to an existing Spree model | Decorator via spree:model_decorator | spree-decorators | | Add a before_action / new action / override existing action on an existing controller | Decorator via spree:controller_decorator | spree-decorators | | Pull in a third-party gem (Stripe, Adyen, search, i18n, social login) | gem 'spree_x' + install generator | spree-extensions | | Package customization to share across multiple Spree apps | Build an extension (Rails engine as a gem) | spree-extensions |

The priority order, in one sentence

Settings → Configuration → Events → Dependencies → Admin / Ransack APIs → Generators (resource or model) → Decorators → Extensions.

Lower-numbered options are easier to write, easier to test, and survive Spree upgrades cleanly. Decorators are reserved for structural changes to existing Spree classes (associations, validations, scopes, methods) — for behavioral changes (callbacks, side effects, sync), use Events instead.

Worked examples

"I need to sync orders to my ERP when they complete"

That's a side effect that fires when an order finishes. Don't decorate Spree::Order to add after_save — write a subscriber:

# app/subscribers/erp_order_sync_subscriber.rb
class ErpOrderSyncSubscriber _serializer = 'MyApp::FooSerializer'`.
- **Decorating a model to add `ransackable_attributes`** → use `Spree.ransack.add_attribute` instead. Same outcome, no coupling to model internals.
- **Building a private extension gem for one-app customization** → put the code directly in `app/` (subscribers, decorators, services). Extensions are for sharing across apps.
- **Forking Spree** → almost never necessary. If you find yourself wanting to, work through this table from the top first — the right pattern almost certainly exists.

## Where to read further

- **Spree's customization docs (the canonical decision tree):** `node_modules/@spree/docs/dist/developer/customization/quickstart.md`
- **Each specific pattern's deep dive:** the linked `spree-X` skill in the table above
- **Configuration reference:** `node_modules/@spree/docs/dist/developer/customization/configuration.md`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [spree](https://github.com/spree)
- **Source:** [spree/agent-skills](https://github.com/spree/agent-skills)
- **License:** MIT
- **Homepage:** https://spreecommerce.org/docs/developer/agentic/overview

Install and usage instructions live in the source repository linked above.