@spree/docs 0.1.0

package/dist/developer/customization/model-preferences.md

@@ -0,0 +1,130 @@
+---
+title: Model Preferences
+---
+
+Model preferences allow you to easily extend Spree models with configuration options. Thanks to this you can store useful information on Spree models, eg.
+
+```ruby
+user.preferred_language = "English"
+user.save
+```
+
+## Defining Model Preferences
+
+To define a model preference, you need to add them to your model class.
+
+Make sure to generate a migration to add the `preferences` column to the table. This column will store the preferences in a serialized format.
+
+```ruby
+rails g migration AddPreferencesToSpreeUsers preferences:text
+```
+
+Run the migration.
+
+```ruby
+rails db:migrate
+```
+
+```ruby
+class Spree::User < ApplicationRecord
+  # ... you existing code ...
+
+  # include the preferable module
+  include Spree::Preferences::Preferable
+  # define the preferences
+  preference :language, :string, default: "English"
+  preference :sms_marketing, :boolean, default: false
+end
+```
+
+This will add a `language` preference to the `User` model. The preference will be stored in the newly created `preferences` column of the `spree_users` table. You can add more preferences to the model in the same way.
+
+## Accessing Model Preferences
+
+Once preferences have been defined for a model, they can be accessed either using the shortcut methods that are generated for each preference or the generic methods that are not specific to a particular preference.
+
+### Shortcut Methods
+
+There are several shortcut methods that are generated. They are shown below.
+
+Query methods:
+
+```ruby
+user.prefers_sms_marketing? # => false
+```
+
+Reader methods:
+
+```ruby
+user.preferred_sms_marketing      # => false
+user.preferred_language   # => "English"
+```
+
+Writer methods:
+
+```ruby
+user.prefers_sms_marketing = false         # => false
+user.preferred_language = "English"    # => "English"
+```
+
+> **NOTE:** Remember to run `user.save` after setting the preference value to save the changes to the database.
+
+Check if a preference is available:
+
+```ruby
+user.has_preference? :sms_marketing
+```
+
+### Generic Methods
+
+Each shortcut method is essentially a wrapper for the various generic methods shown below:
+
+Query method:
+
+```ruby
+user.prefers?(:sms_marketing)       # => false
+user.prefers?(:language)  # => false
+```
+
+Reader methods:
+
+```ruby
+user.preferred(:sms_marketing)      # => false
+user.preferred(:language)   # => "English"
+```
+
+```ruby
+user.get_preference :sms_marketing
+user.get_preference :language
+```
+
+Writer method:
+
+```ruby
+user.set_preference(:sms_marketing, false)     # => false
+user.set_preference(:language, "English")  # => "English"
+```
+
+### Accessing All Preferences
+
+You can get a hash of all stored preferences by accessing the `preferences` helper:
+
+```ruby
+user.preferences # => {"language"=>"English", "sms_marketing"=>false}
+```
+
+This hash will contain the value for every preference that has been defined for the model instance, whether the value is the default or one that has been previously stored.
+
+## Models with preferences
+
+The following Spree models already have preferences defined:
+
+* `Spree::Calculator`
+* `Spree::Gateway`
+* `Spree::PageBlock`
+* `Spree::PageSection`
+* `Spree::Page`
+* `Spree::PaymentMethod`
+* `Spree::PromotionRule`
+* `Spree::Store`
+* `Spree::Theme`

package/dist/developer/customization/permissions.md

@@ -0,0 +1,265 @@
+---
+title: Permissions
+---
+
+Spree uses [CanCanCan](https://github.com/CanCanCommunity/cancancan) for authorization. The permission system allows you to define granular access control for different user roles.
+
+## Permission Sets (Recommended)
+
+Permission Sets provide a clean, modular way to manage permissions. Each permission set is a reusable group of permissions that can be assigned to roles.
+
+### How It Works
+
+1. **Roles** - Determine which permission sets govern a user's access (e.g., `admin`, `customer_service`)
+2. **Permission Sets** - Contain the logic defining what actions users can perform on resources
+3. **Role Configuration** - Associates roles with their corresponding permission sets
+
+### Configuring Roles
+
+In your `config/initializers/spree.rb`, configure which permission sets are assigned to each role:
+
+```ruby
+Rails.application.config.after_initialize do
+  # Default permissions for all users (guests and logged-in customers)
+  Spree.permissions.assign(:default, [Spree::PermissionSets::DefaultCustomer])
+
+  # Full admin access
+  Spree.permissions.assign(:admin, [Spree::PermissionSets::SuperUser])
+
+  # Custom role with specific permissions
+  Spree.permissions.assign(:customer_service, [
+    Spree::PermissionSets::DashboardDisplay,
+    Spree::PermissionSets::OrderManagement,
+    Spree::PermissionSets::UserDisplay
+  ])
+
+  # Merchandiser role for product management
+  Spree.permissions.assign(:merchandiser, [
+    Spree::PermissionSets::DashboardDisplay,
+    Spree::PermissionSets::ProductManagement,
+    Spree::PermissionSets::StockManagement
+  ])
+end
+```
+
+### Built-in Permission Sets
+
+| Permission Set | Description |
+|---------------|-------------|
+| `SuperUser` | Full admin access with safety restrictions |
+| `DefaultCustomer` | Basic storefront permissions (browse, checkout, manage own account) |
+| `DashboardDisplay` | View admin dashboard |
+| `OrderDisplay` | Read-only access to orders |
+| `OrderManagement` | Full order management (view, edit, refund, etc.) |
+| `ProductDisplay` | Read-only access to products and catalog |
+| `ProductManagement` | Full catalog management (products, variants, taxonomies) |
+| `UserDisplay` | Read-only access to users |
+| `UserManagement` | Full user management |
+| `StockDisplay` | Read-only access to inventory |
+| `StockManagement` | Full inventory management |
+| `PromotionManagement` | Manage promotions and coupon codes |
+| `ConfigurationManagement` | Manage store settings, shipping, taxes, etc. |
+| `RoleManagement` | Manage roles (except the protected admin role) |
+
+### Creating Custom Permission Sets
+
+Create a new permission set in `app/models/spree/permission_sets/`:
+
+```ruby
+# app/models/spree/permission_sets/warehouse_management.rb
+module Spree
+  module PermissionSets
+    class WarehouseManagement < Base
+      def activate!
+        can :manage, Spree::StockItem
+        can :manage, Spree::StockLocation
+        can :manage, Spree::StockMovement
+        can :manage, Spree::Shipment
+        can [:read, :admin], Spree::Order
+      end
+    end
+  end
+end
+```
+
+Then assign it to a role:
+
+```ruby
+Spree.permissions.assign(:warehouse_staff, [
+  Spree::PermissionSets::DashboardDisplay,
+  Spree::PermissionSets::WarehouseManagement
+])
+```
+
+### Permission Set API
+
+Within a permission set, you have access to:
+
+- `can(action, subject, conditions = {})` - Grant permission
+- `cannot(action, subject, conditions = {})` - Deny permission
+- `can?(action, subject)` - Check if permission exists
+- `user` - The current user
+- `store` - The current store (for multi-store setups)
+
+```ruby
+module Spree
+  module PermissionSets
+    class OrderManagementForOwnOrders < Base
+      def activate!
+        # Users can only manage orders they created
+        can :manage, Spree::Order, created_by_id: user.id
+
+        # But cannot cancel any order
+        cannot :cancel, Spree::Order
+
+        # Unless it's cancellable
+        can :cancel, Spree::Order, &:allow_cancel?
+      end
+    end
+  end
+end
+```
+
+### Managing Permission Configuration
+
+```ruby
+# Assign permission sets to a role
+Spree.permissions.assign(:customer_service, [
+  Spree::PermissionSets::OrderDisplay,
+  Spree::PermissionSets::UserManagement
+])
+
+# Add more permission sets to an existing role
+Spree.permissions.assign(:customer_service, [
+  Spree::PermissionSets::StockDisplay
+])
+
+# Clear all permission sets from a role
+Spree.permissions.clear(:customer_service)
+
+# Check what permission sets a role has
+Spree.permissions.permission_sets_for(:customer_service)
+# => [Spree::PermissionSets::OrderDisplay, ...]
+
+# Check if a role is configured
+Spree.permissions.role_configured?(:customer_service)
+# => true
+```
+
+## Users and Roles
+
+Spree comes with an `admin` role by default. You can create more roles in the Admin Panel or via Rails console:
+
+```ruby
+Spree::Role.find_or_create_by(name: 'customer_service')
+Spree::Role.find_or_create_by(name: 'merchandiser')
+Spree::Role.find_or_create_by(name: 'warehouse_staff')
+```
+
+Assign a role to a user:
+
+```ruby
+user = Spree.user_class.find_by(email: 'john@example.com')
+role = Spree::Role.find_by(name: 'customer_service')
+user.spree_roles << role
+```
+
+### Default Role Behavior
+
+- Users with **no roles assigned** automatically get the `:default` role permissions
+- No `RoleUser` records are created for regular customers
+- Only users with special permissions need explicit role assignments
+
+## Legacy Approach: Custom Ability Classes
+
+> **NOTE:** The permission sets approach above is recommended for new projects. The legacy approach below is supported for backward compatibility.
+
+### Adding Custom Permissions via Decorator
+
+Create a new ability class in `app/models/customer_service_ability.rb`:
+
+```ruby
+class CustomerServiceAbility
+  include CanCan::Ability
+
+  def initialize(user)
+    if user.respond_to?(:has_spree_role?) && user.has_spree_role?('customer_service')
+      can :manage, Spree::Order
+    end
+  end
+end
+```
+
+Register it via a decorator in `app/models/spree/ability_decorator.rb`:
+
+```ruby
+module Spree
+  module AbilityDecorator
+    def abilities_to_register
+      [CustomerServiceAbility]
+    end
+  end
+
+  Ability.prepend(AbilityDecorator)
+end
+```
+
+### Replacing the Ability Class
+
+You can replace the entire ability class via [Dependencies](/developer/customization/dependencies):
+
+```ruby
+# config/initializers/spree.rb
+Spree::Dependencies.ability_class = 'CustomAbility'
+```
+
+```ruby
+# app/models/custom_ability.rb
+class CustomAbility < Spree::Ability
+  def initialize(user, options = {})
+    alias_cancan_delete_action
+
+    @user = user || Spree.user_class.new
+    @store = options[:store] || Spree::Current.store
+
+    if @user.respond_to?(:has_spree_role?) && @user.has_spree_role?('admin')
+      apply_admin_permissions(@user, options)
+    elsif @user.respond_to?(:has_spree_role?) && @user.has_spree_role?(:customer_service)
+      apply_customer_service_permissions(@user)
+    else
+      apply_user_permissions(@user, options)
+    end
+
+    protect_admin_role
+  end
+
+  protected
+
+  def apply_customer_service_permissions(user)
+    can :manage, Spree::Order
+    can [:read, :admin], Spree.user_class
+  end
+end
+```
+
+## CanCanCan Reference
+
+Spree's permission system is built on CanCanCan. Key concepts:
+
+- `can :action, Subject` - Grant permission
+- `can :manage, Subject` - Grant all actions (create, read, update, destroy)
+- `cannot :action, Subject` - Explicitly deny permission
+- `can :action, Subject, conditions` - Conditional permission
+
+```ruby
+# Examples
+can :read, Spree::Product                           # Can read any product
+can :manage, Spree::Order, user_id: user.id        # Can manage own orders
+can :update, Spree::Order do |order|               # Block conditions
+  order.user == user && !order.completed?
+end
+cannot :destroy, Spree::Order                       # Cannot destroy any order
+can :destroy, Spree::Order, &:can_be_deleted?      # Unless it's deletable
+```
+
+See the [CanCanCan documentation](https://github.com/CanCanCommunity/cancancan) for more details.

package/dist/developer/customization/quickstart.md

@@ -0,0 +1,229 @@
+---
+title: Quickstart
+og:title: Spree Customization Quickstart
+description: Learn how to customize every part of the Spree stack
+---
+
+Spree is a flexible platform allowing you to customize every part of it to suit your business needs. This guide presents customization options **in order of recommendation** - start from the top and only move down if simpler options don't meet your needs.
+
+## Quick Reference
+
+| What you want to do | Recommended approach |
+|---------------------|---------------------|
+| Change store settings (currency, zones, languages) | [Store Settings](#store-settings) |
+| Tweak Spree behavior globally | [Configuration](#configuration) |
+| React to model changes (sync, notifications) | [Events & Subscribers](#events-and-subscribers) |
+| Notify external services | [Webhooks](#webhooks) |
+| Swap core services (cart, checkout, etc.) | [Dependencies](#dependencies) |
+| Add admin menu items | [Admin Navigation](#admin-extensions) |
+| Add sections to admin forms | [Admin Partials](#admin-extensions) |
+| Add searchable/filterable fields | [Ransack Configuration](#search-and-filtering) |
+| Add associations/validations to models | [Decorators](#decorators) (last resort) |
+
+**Best for:** Changing currency, shipping zones, languages, and other business settings.
+
+    There's a lot of Store settings you can change in the admin panel without touching the code.
+
+    Go to **Admin > Settings**
+
+    <img src="/images/spree_admin_store_settings.png" alt="Spree Admin Store Settings" />
+
+  <details>
+<summary>Configuration</summary>
+
+**Best for:** Tweaking Spree's behavior globally without modifying source code.
+
+    Global application configuration allows you to customize various aspects of Spree:
+
+    ```ruby config/initializers/spree.rb
+    Spree.config do |config|
+      config.allow_guest_checkout = false
+      config.products_per_page = 20
+    end
+    ```
+
+    Please see [Configuration](/developer/customization/configuration) section for more information.
+
+</details>
+
+
+  <details>
+<summary>Events and Subscribers</summary>
+
+**Best for:** Reacting to model changes, syncing with external services, sending notifications, audit logging.
+
+    > **INFO:** Events are the **recommended way** to add behavior when something happens in Spree, replacing the need for decorator callbacks.
+
+    Spree's event system lets you subscribe to events like `order.completed`, `product.updated`, `payment.paid`, etc.:
+
+    ```ruby app/subscribers/my_app/order_completed_subscriber.rb
+    module MyApp
+      class OrderCompletedSubscriber < Spree::Subscriber
+        subscribes_to 'order.completed'
+
+        def handle(event)
+          order = Spree::Order.find_by(id: event.payload['id'])
+          return unless order
+
+          # Sync to external service, send notification, etc.
+          ExternalService.notify_order_placed(order)
+        end
+      end
+    end
+    ```
+
+    **Key benefits:**
+    - Loose coupling - your code doesn't depend on Spree internals
+    - Async by default - keeps requests fast
+    - Easier testing and upgrades
+
+    Please see [Events](/developer/core-concepts/events) section for more information.
+
+</details>
+
+
+  <details>
+<summary>Webhooks</summary>
+
+**Best for:** Notifying external services (ERPs, CRMs, fulfillment systems) when events occur.
+
+    Webhooks send HTTP POST requests to external URLs when Spree events happen:
+
+    - Order completed → Notify fulfillment system
+    - Product updated → Sync with PIM
+    - Customer created → Add to CRM
+
+    Configure webhooks in **Admin > Developers > Webhooks** or via the API.
+
+    Please see [Webhooks](/developer/core-concepts/webhooks) section for more information.
+
+</details>
+
+
+  <details>
+<summary>Dependencies</summary>
+
+**Best for:** Swapping core services, serializers, and abilities with your own implementations.
+
+    Spree allows you to replace core classes without modifying them:
+
+    ```ruby config/initializers/spree.rb
+    Spree::Dependencies.cart_add_item_service = "MyCartAddItemService"
+    Spree::Dependencies.cart_remove_item_service = "MyCartRemoveItemService"
+    ```
+
+    This is cleaner than decorating services because you provide a complete replacement rather than patching behavior.
+
+    Please see [Dependencies](dependencies) section for more information.
+
+</details>
+
+
+  <details>
+<summary>Admin Extensions</summary>
+
+**Best for:** Adding menu items, form sections, dashboard widgets, and other UI elements to the admin panel.
+
+    Spree provides declarative APIs for extending the admin without decorators or view overrides:
+
+    **Navigation API** - Add menu items:
+    ```ruby config/initializers/spree.rb
+    Rails.application.config.after_initialize do
+      Spree.admin.navigation.sidebar.add :brands,
+        label: :brands,
+        url: :admin_brands_path,
+        icon: 'award',
+        position: 35
+    end
+    ```
+
+    **Partials API** - Add sections to forms:
+    ```ruby config/initializers/spree.rb
+    Spree.admin.partials.product_form << 'spree/admin/products/erp_section'
+    ```
+
+    Please see:
+    - [Admin Navigation](/developer/admin/navigation) - For adding menu items
+    - [Admin Partials](/developer/admin/extending-ui) - For extending UI
+    - [Admin Tables](/developer/admin/tables) - For customizing list views
+
+</details>
+
+
+  <details>
+<summary>Search and Filtering</summary>
+
+**Best for:** Making custom fields searchable/sortable in the admin and API.
+
+    Instead of decorating models to add `ransackable_attributes`, use the Ransack configuration API:
+
+    ```ruby config/initializers/spree.rb
+    Spree.ransack.add_attribute :product, :erp_id
+    Spree.ransack.add_association :product, :brand
+    ```
+
+    Please see [Search & Filtering](/developer/core-concepts/search-filtering#extending-ransackable-configuration) section for more information.
+
+</details>
+
+
+  <details>
+<summary>Authentication</summary>
+
+**Best for:** Using your own user model or authentication system.
+
+    Spree allows you to use your own authentication system instead of the default Devise-based one.
+
+    You can find more information in the [Authentication](authentication) section.
+
+</details>
+
+
+  <details>
+<summary>Checkout flow</summary>
+
+**Best for:** Customizing checkout steps and flow.
+
+    With Spree you can change the checkout flow to fit your business needs - add steps, remove steps, or change the order.
+
+    Please see [Checkout flow customization section](checkout) for more information.
+
+</details>
+
+
+  <details>
+<summary>Decorators</summary>
+
+**Best for:** Adding associations, validations, scopes, and methods to Spree models. Use as a last resort.
+
+    > **WARNING:** Decorators should be used **only when no other option works**. They tightly couple your code to Spree internals and can break during upgrades.
+> 
+>       **Do NOT use decorators for:**
+>       - After-save callbacks → Use [Events](/developer/core-concepts/events) instead
+>       - External service sync → Use [Webhooks](/developer/core-concepts/webhooks) instead
+>       - Custom service logic → Use [Dependencies](dependencies) instead
+>       - Admin UI changes → Use [Admin Extensions](#admin-extensions) instead
+
+    Decorators are still appropriate for structural changes:
+
+    ```ruby app/models/spree/product_decorator.rb
+    module Spree
+      module ProductDecorator
+        def self.prepended(base)
+          base.belongs_to :brand, class_name: 'MyApp::Brand', optional: true
+          base.validates :external_id, presence: true
+          base.scope :featured, -> { where(featured: true) }
+        end
+
+        def full_title
+          "#{brand&.name} #{name}"
+        end
+      end
+
+      Product.prepend(ProductDecorator)
+    end
+    ```
+
+    Please see [Decorators](decorators) section for more information.
+
+</details>

package/dist/developer/customization/routes.md

@@ -0,0 +1,24 @@
+---
+title: Routes
+description: Learn how to customize the routes in Spree
+---
+
+## Default configuration
+
+By default Spree is mounted at the root of your domain, this code will be inserted into `config/routes.rb`:
+
+```ruby
+mount Spree::Core::Engine, at: '/'
+```
+
+This means that Spree will be available at the root of your domain, for example `http://localhost:3000`.
+
+## Customizing the mount point
+
+You can customize this simply by changing the `:at` specification in `config/routes.rb` to be something else. For example, if you would like Spree to be mounted at `/shop`, you can write this:
+
+```ruby
+mount Spree::Core::Engine, at: `/shop`
+```
+
+The different parts of Spree (API, Admin) will be mounted there as well, eg. `http://localhost:3000/shop/products`.