spree-dependencies

Spree Dependencies (Dependency Injection)

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.dependencies is the canonical way to replace a core Spree service with your own implementation — no fork, no monkey-patch, no decorator. You inherit from the Spree default, override the methods you need, and register your class as the dependency. Spree's own code calls your service everywhere it used to call the default.

The core has 70+ injection points (71 in 5.5); the API has 300+ more (303 in 5.5) for serializers, finders, and per-endpoint services. The full set is documented at node_modules/@spree/docs/dist/developer/customization/dependencies.md.

When to reach for this vs other patterns

Want to...	Use
Replace how a core service computes (cart add, cart recalculate, checkout step, ability checks, search, finder)	Dependency injection (this skill)
Replace an API serializer everywhere	Dependency injection — Spree.api.<serializer> = MyApp::Foo
React to something happening after a service runs (sync to ERP, notify)	Events subscriber — see spree-events-webhooks
Add an association / validation / scope / method to a model	Decorator — see spree-decorators
Add a brand-new model + API endpoint	spree:api_resource — see spree-resource
Tweak runtime config / preferences	Spree::Config[:key]

If Spree gives you a swappable service, use it. Decorating Spree::Cart::AddItem would couple you to the parent's step names and break on minor upgrades; subclassing + injection is the supported extension point.

The basic pattern

Step 1: subclass the Spree default

# app/services/my_app/cart/add_item.rb
class MyApp::Cart::AddItem < Spree::Cart::AddItem
  def call(order:, variant:, quantity: nil, metadata: {}, public_metadata: {}, private_metadata: {}, options: {})
    ApplicationRecord.transaction do
      run :add_to_line_item
      run :handle_stock_reservations            # keep the parent's steps you need
      run :update_in_external_system            # your custom step
      run Spree.cart_recalculate_service        # call other dependencies dynamically
    end
  end

  private

  def update_in_external_system(order:, line_item:, **rest)
    # Your custom logic
    success(order: order, line_item: line_item, **rest)
  end
end