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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Document new improved dependencies system
Damian Legawieceeadd2a9b73a
diff --git a/docs/developer/customization/dependencies.mdx b/docs/developer/customization/dependencies.mdxindex 9fd52f5533..2240c16ece 100644--- a/docs/developer/customization/dependencies.mdx+++ b/docs/developer/customization/dependencies.mdx@@ -5,7 +5,7 @@ section: customization## 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 (user for [Permissions](permissions)), and [API Serializers](https://github.com/spree/spree/tree/master/api/app/serializers/spree/v2) (used for generating JSON API responses).+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@@ -14,31 +14,31 @@ This will change every aspect of the application (both APIs, Admin Panel, and StIn your `config/initializers/spree.rb` file, you can set the following:```ruby-Spree::Dependencies.cart_add_item_service = 'MyAddToCartService'+Spree.cart_add_item_service = MyAddToCartService```-or+or using the block syntax:```rubySpree.dependencies do |dependencies|- dependencies.cart_add_item_service = 'MyAddToCartService'+ dependencies.cart_add_item_service = MyAddToCartServiceend```Now let's create your custom service.```bash-mkdir app/services -f && touch app/services/my_add_to_cart_service.rb+mkdir -p app/services && touch app/services/my_add_to_cart_service.rb```And add the following code to it:```ruby-module MyAddToCartService < Spree::Cart::AddItem+class MyAddToCartService < Spree::Cart::AddItemdef call(order:, variant:, quantity: nil, public_metadata: {}, private_metadata: {}, options: {})ApplicationRecord.transaction dorun :add_to_line_item- run Spree::Dependencies.cart_recalculate_service.constantize+ run Spree.cart_recalculate_servicerun :update_in_external_systemendend@@ -56,19 +56,27 @@ This code will:1. Inherit from `Spree::Cart::AddItem`2. Override the `call` method to add your custom logic3. Call `run :add_to_line_item` to add the item to the cart-4. Call `run Spree::Dependencies.cart_recalculate_service.constantize` to recalculate 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-<Warning>-Values set in the initializer have to be strings, eg. `'MyNewAwesomeAddItemToCart'`-</Warning>+## 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+# 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 customizationIf 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-mkdir app/controllers/spree -f && touch app/controllers/spree/cart_controller_decorator.rb+mkdir -p app/controllers/spree && touch app/controllers/spree/cart_controller_decorator.rb```and add the following code to it:@@ -100,8 +108,8 @@ Storefront API and Platform API have separate Dependencies injection points so yIn your Spree initializer (`config/initializers/spree.rb`) please add:```ruby-Spree::Api::Dependencies.storefront_cart_serializer = 'MyNewAwesomeCartSerializer'-Spree::Api::Dependencies.storefront_cart_add_item_service = 'MyNewAwesomeAddItemToCart'+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.@@ -109,15 +117,116 @@ This will swap the default Cart serializer and Add Item to Cart service for yourYou can mix and match both global and API-level customizations:```ruby-Spree::Dependencies.cart_add_item_service = 'MyNewAwesomeAddItemToCart'-Spree::Api::Dependencies.storefront_cart_add_item_service = 'AnotherAddItemToCart'+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+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+bin/rake spree:dependencies:list | grep cart+```++### Show only overridden dependencies++```bash+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+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+# 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+# 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```-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`+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-By default values can be easily checked by looking at the source code of Dependencies classes:+Default values can be easily checked by:-* [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)+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)