> ## Documentation Index
> Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Dependencies

## Overview

With Dependencies, you can easily replace parts of Spree core with your custom code. You can replace [Services](https://github.com/spree/spree/tree/master/core/app/services/spree), CanCanCan Abilities (used for [Permissions](permissions)), and [API Serializers](https://github.com/spree/spree/tree/master/api/app/serializers/spree/v2) (used for generating JSON API responses).

## Application (global) customization

This will change every aspect of the application (both APIs, Admin Panel, and Storefront).

In your `config/initializers/spree.rb` file, you can set the following:

```ruby theme={"theme":"night-owl"}
Spree.cart_add_item_service = MyAddToCartService
```

or using the block syntax:

```ruby theme={"theme":"night-owl"}
Spree.dependencies do |dependencies|
  dependencies.cart_add_item_service = MyAddToCartService
end
```

Now let's create your custom service.

```bash theme={"theme":"night-owl"}
mkdir -p app/services && touch app/services/my_add_to_cart_service.rb
```

And add the following code to it:

```ruby theme={"theme":"night-owl"}
class MyAddToCartService < Spree::Cart::AddItem
  def call(order:, variant:, quantity: nil, metadata: {}, options: {})
    ApplicationRecord.transaction do
      run :add_to_line_item
      run Spree.cart_recalculate_service
      run :update_in_external_system
    end
  end

  private

  def update_in_external_system(new_order_line_item)
    # Your custom logic here
  end
end
```

This code will:

1. Inherit from `Spree::Cart::AddItem`
2. Override the `call` method to add your custom logic
3. Call `run :add_to_line_item` to add the item to the cart
4. Call `run Spree.cart_recalculate_service` to recalculate the cart (returns the resolved class)
5. Call `run :update_in_external_system` to execute your custom logic, eg. updating Order in an external system such as ERP

## Using dependencies in your code

When you need to use a dependency in your code, you can access it directly via the `Spree` module:

```ruby theme={"theme":"night-owl"}
# Returns the resolved class (not a string)
Spree.cart_add_item_service.call(order: order, variant: variant, quantity: 1)

# For API dependencies, use the Spree.api accessor
Spree.api.storefront_cart_serializer.new(order).serializable_hash
```

## Controller level customization

If you need to replace [serializers](https://github.com/jsonapi-serializer/jsonapi-serializer) or Services in a specific API endpoint you can create a [code decorator](/developer/customization/decorators):

```bash theme={"theme":"night-owl"}
mkdir -p app/controllers/spree && touch app/controllers/spree/cart_controller_decorator.rb
```

and add the following code to it:

```ruby theme={"theme":"night-owl"}
module Spree
  module CartControllerDecorator
    def resource_serializer
      MyNewAwesomeCartSerializer
    end

    def add_item_service
      MyNewAwesomeAddItemToCart
    end
  end

  CartController.prepend(CartControllerDecorator)
end
```

This will change the serializer in this API endpoint to `MyNewAwesomeCartSerializer` and also it will swap the default `add_item_service` to `MyNewAwesomeAddItemToCart`.

Different API endpoints can have different dependency injection points. You can review their [source code](https://github.com/spree/spree/tree/master/api/app/controllers/spree/api/v2) to see what you can replace.

## API level customization

Storefront API and Platform API have separate Dependencies injection points so you can easily customize one without touching the other.

In your Spree initializer (`config/initializers/spree.rb`) please add:

```ruby theme={"theme":"night-owl"}
Spree.api.storefront_cart_serializer = MyNewAwesomeCartSerializer
Spree.api.storefront_cart_add_item_service = MyNewAwesomeAddItemToCart
```

This will swap the default Cart serializer and Add Item to Cart service for your custom ones within all Storefront API endpoints that use those classes.

You can mix and match both global and API-level customizations:

```ruby theme={"theme":"night-owl"}
Spree.cart_add_item_service = MyNewAwesomeAddItemToCart
Spree.api.storefront_cart_add_item_service = AnotherAddItemToCart
```

The second line will have precedence over the first one, and the Storefront API will use `AnotherAddItemToCart` and the rest of the application will use `MyNewAwesomeAddItemToCart`.

## Debugging dependencies

Spree provides rake tasks to help you debug and inspect dependencies:

### List all dependencies

```bash theme={"theme":"night-owl"}
bin/rake spree:dependencies:list
```

This will output all dependencies with their current values:

```
[CORE]
cart_add_item_service           Spree::Cart::AddItem
cart_create_service             Spree::Cart::Create
cart_recalculate_service        Spree::Cart::Recalculate [OVERRIDDEN]
...

[API]
storefront_cart_serializer      Spree::V2::Storefront::CartSerializer
storefront_cart_add_item_service  MyApp::CartAddItem [OVERRIDDEN]
...
```

You can use `grep` to filter results:

```bash theme={"theme":"night-owl"}
bin/rake spree:dependencies:list | grep cart
```

### Show only overridden dependencies

```bash theme={"theme":"night-owl"}
bin/rake spree:dependencies:overrides
```

This shows only the dependencies that have been customized, along with their original and current values:

```
[Core OVERRIDES]
cart_recalculate_service  Spree::Cart::Recalculate -> MyApp::CartRecalculate (config/initializers/spree.rb:15)

[API OVERRIDES]
storefront_cart_add_item_service  Spree::Cart::AddItem -> MyApp::CartAddItem (config/initializers/spree.rb:20)
```

### Validate all dependencies

```bash theme={"theme":"night-owl"}
bin/rake spree:dependencies:validate
```

This validates that all dependencies can be resolved to valid classes. If any dependency points to a non-existent class, it will report an error:

```
..........F.........
1 invalid dependencies:
  [Core] cart_add_item_service: uninitialized constant NonExistentClass
```

## Programmatic introspection

You can also inspect dependencies programmatically:

```ruby theme={"theme":"night-owl"}
# Check all current values
Spree::Dependencies.current_values
# => [{name: :cart_add_item_service, current: MyApp::CartAddItem, default: 'Spree::Cart::AddItem', overridden: true}, ...]

# Check if a specific dependency is overridden
Spree::Dependencies.overridden?(:cart_add_item_service)
# => true

# Get override information (where it was set)
Spree::Dependencies.override_info(:cart_add_item_service)
# => {value: MyApp::CartAddItem, source: "config/initializers/spree.rb:15", set_at: 2024-01-15 10:30:00}

# Validate all dependencies resolve to valid classes
Spree::Dependencies.validate!
# => true (or raises Spree::DependencyError)
```

## Backwards compatibility

The legacy string-based syntax is still supported for backwards compatibility:

```ruby theme={"theme":"night-owl"}
# Legacy syntax (still works)
Spree::Dependencies.cart_add_item_service = 'MyAddToCartService'
result = Spree::Dependencies.cart_add_item_service.constantize

# New syntax (recommended)
Spree.cart_add_item_service = MyAddToCartService
result = Spree.cart_add_item_service
```

Both syntaxes can coexist, but the new syntax is recommended as it's more concise and provides better error messages at assignment time.

## Default values

Default values can be easily checked by:

1. Using the rake task: `bin/rake spree:dependencies:list`
2. Looking at the source code:
   * [Application (global) dependencies](https://github.com/spree/spree/blob/main/core/lib/spree/core/dependencies.rb)
   * [API level dependencies](https://github.com/spree/spree/blob/main/api/lib/spree/api/dependencies.rb)