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
[skip CI] Added README files for all gems
Damian Legawiec32e549f04bfc
diff --git a/admin/README.md b/admin/README.mdindex 77072675b8..13505d1db4 100644--- a/admin/README.md+++ b/admin/README.md@@ -1,21 +1,150 @@-# Spree Admin Dashboard+# Spree Admin-Welcome to the Spree Admin Dashboard repository. This is a new, shiny admin dashboard for Spree Commerce 5.+[](https://badge.fury.io/rb/spree_admin)-## Installation+Spree Admin provides a modern, fully-featured admin dashboard for managing your Spree Commerce store.++## Overview++This gem includes:-To install the Spree Admin Dashboard, run the following command:+- **Dashboard** - Analytics and KPI overview+- **Product Management** - Products, variants, properties, option types+- **Order Management** - Orders, payments, shipments, refunds+- **Customer Management** - Customer accounts and order history+- **Inventory Management** - Stock locations, stock items, transfers+- **Promotions** - Discounts, coupon codes, promotion rules+- **Content Management** - Pages, menus, navigation+- **Settings** - Store configuration, payment methods, shipping methods, taxes++## Installation```bashbundle add spree_admin+bin/rails g spree:admin:install+```++You will need to restart your web server and run `bin/dev` to start the development server for the admin dashboard.++## Features++### Dynamic Tables++Register customizable tables for your resources:++```ruby+# config/initializers/spree_admin_tables.rb+Rails.application.config.after_initialize do+ Spree.admin.tables.register(:gift_cards, model_class: Spree::GiftCard)++ Spree.admin.tables.gift_cards.add :code,+ label: :code,+ type: :string,+ sortable: true,+ filterable: true,+ default: true,+ position: 10+end+```++Column types: `:string`, `:currency`, `:date`, `:datetime`, `:boolean`, `:custom`++### Navigation++Configure sidebar and settings navigation:++```ruby+# config/initializers/spree_admin_navigation.rb+Rails.application.config.after_initialize do+ Spree.admin.navigation.sidebar.add :reports,+ label: :reports,+ url: :admin_reports_path,+ icon: 'chart-bar',+ position: 60,+ if: -> { can?(:manage, Spree::Report) }+end```-Run the install generator:+### Partial Hooks++Extend the admin interface with partial hooks (100+ available):++```erb+<%# app/views/spree/admin/orders/_show_sidebar.html.erb %>+<div class="card">+ <div class="card-body">+ Custom order sidebar content+ </div>+</div>+```++### Controllers++Admin controllers inherit from `Spree::Admin::ResourceController` for consistent CRUD:++```ruby+module Spree+ module Admin+ class GiftCardsController < ResourceController+ private++ def model_class+ Spree::GiftCard+ end++ def permitted_resource_params+ params.require(:gift_card).permit(+ Spree::PermittedAttributes.gift_card_attributes+ )+ end+ end+ end+end+```++### Form Builder++Use the Spree admin form builder for consistent styling:++```erb+<%= f.spree_text_field :name %>+<%= f.spree_text_area :description %>+<%= f.spree_check_box :active %>+<%= f.spree_select :status, options_for_status %>+```++## Technology Stack++- **Tailwind CSS** - Utility-first CSS framework+- **Turbo/Hotwire** - SPA-like interactions without JavaScript frameworks+- **Stimulus** - Modest JavaScript framework for controllers++## Testing```bash-bin/rails g spree:admin:install+cd admin+bundle exec rake test_app # First time only+bundle exec rspec+```++For controller specs, use `stub_authorization!` for authentication:++```ruby+RSpec.describe Spree::Admin::ProductsController, type: :controller do+ stub_authorization!+ render_views++ describe 'GET #index' do+ it 'renders the index template' do+ get :index+ expect(response).to render_template(:index)+ end+ end+end```-This will create the necessary files for the admin dashboard.+## Documentation-You will need to restart your web server and run `bin/dev` to start the development server for the admin dashboard.\ No newline at end of file+- [Admin Customization Guide](https://docs.spreecommerce.org/developer/customization/admin)+- [Navigation Configuration](https://docs.spreecommerce.org/developer/customization/admin-navigation)+- [Permissions Guide](https://docs.spreecommerce.org/developer/customization/permissions)\ No newline at end of filediff --git a/api/README.md b/api/README.mdnew file mode 100644index 0000000000..e2269924d0--- /dev/null+++ b/api/README.md@@ -0,0 +1,99 @@+# Spree API++[](https://badge.fury.io/rb/spree_api)++Spree API provides RESTful API endpoints for building custom storefronts, mobile applications, and third-party integrations with Spree Commerce.++## Overview++This gem includes:++- **Storefront API** - Customer-facing endpoints for cart, checkout, products, and accounts+- **Platform API** - Administrative endpoints for managing orders, products, and store settings+- **Webhooks** - Event-driven notifications to external systems+- **OAuth2 Authentication** - Token-based authentication via Doorkeeper+- **JSONAPI Serializers** - Standardized API responses++## Installation++This gem is included in every Spree installation. No additional steps are required.++## API Endpoints++### Storefront API (v2)++The Storefront API is designed for building custom frontends:++```+GET /api/v2/storefront/products+GET /api/v2/storefront/products/:id+GET /api/v2/storefront/taxons+POST /api/v2/storefront/cart+PATCH /api/v2/storefront/cart/add_item+PATCH /api/v2/storefront/checkout+POST /api/v2/storefront/account+```++### Platform API++The Platform API provides administrative access:++```+GET /api/v2/platform/orders+POST /api/v2/platform/products+PATCH /api/v2/platform/variants/:id+DELETE /api/v2/platform/line_items/:id+```++## Authentication++### OAuth2 Token Authentication++```bash+# Request access token+curl -X POST https://your-store.com/spree_oauth/token \+ -d "grant_type=password&[email protected]&password=secret"++# Use token in requests+curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \+ https://your-store.com/api/v2/storefront/account+```++### Guest Cart Token++For guest checkout, use the `X-Spree-Order-Token` header:++```bash+curl -H "X-Spree-Order-Token: ORDER_TOKEN" \+ https://your-store.com/api/v2/storefront/cart+```++## Serializers++API responses use JSONAPI format. Customize serializers by creating your own:++```ruby+# app/serializers/my_app/product_serializer.rb+module MyApp+ class ProductSerializer < Spree::V2::Storefront::ProductSerializer+ attribute :custom_field+ end+end++# Configure in initializer+Spree.api.storefront_product_serializer = 'MyApp::ProductSerializer'+```++## Testing++```bash+cd api+bundle exec rake test_app # First time only+bundle exec rspec+```++## Documentation++- [Storefront API Reference](https://docs.spreecommerce.org/api/storefront)+- [Platform API Reference](https://docs.spreecommerce.org/api/platform)+- [Authentication Guide](https://docs.spreecommerce.org/developer/api/authentication)\ No newline at end of filediff --git a/cli/README.md b/cli/README.mdindex 48437f07e0..9da67f0a47 100644--- a/cli/README.md+++ b/cli/README.md@@ -1,11 +1,182 @@-Spree CLI-===============+# Spree CLI-Command line utility to create new Spree extensions+[](https://badge.fury.io/rb/spree_cli)-To build a new Spree Extension, you can run-```ruby+Spree CLI is a command-line tool for Spree Commerce developers, providing generators and utilities for creating Spree extensions and managing Spree projects.++## Installation++This gem is included in every Spree installation.++For global installation (to generate extensions outside of a Spree project):++```bash+gem install spree_cli+```++## Commands++### Create New Extension++Generate a new Spree extension with all the necessary boilerplate:++```bashspree extension my_extension```-This will create a brand new project with all the developer tools and gems needed to developer your extension.+This creates a new directory `spree_my_extension` with:++```+spree_my_extension/+├── app/+│ ├── models/+│ ├── controllers/+│ └── views/+├── lib/+│ ├── spree_my_extension.rb+│ ├── spree_my_extension/+│ │ └── engine.rb+│ └── generators/+├── config/+│ ├── routes.rb+│ └── locales/+├── db/+│ └── migrate/+├── spec/+├── Gemfile+├── spree_my_extension.gemspec+├── README.md+└── LICENSE+```++### Extension Options++```bash+# Create extension with specific options+spree extension my_extension --path=/custom/path++# View help+spree help extension+```++## Extension Development++After creating an extension:++```bash+cd spree_my_extension++# Install dependencies+bundle install++# Create test application+bundle exec rake test_app++# Run tests+bundle exec rspec++# Build gem+gem build spree_my_extension.gemspec+```++### Extension Structure++Generated extensions follow Spree conventions:++```ruby+# lib/spree_my_extension/engine.rb+module SpreeMyExtension+ class Engine < Rails::Engine+ require 'spree/core'+ isolate_namespace Spree+ engine_name 'spree_my_extension'++ config.autoload_paths += %W(#{config.root}/lib)++ initializer 'spree_my_extension.environment', before: :load_config_initializers do |_app|+ SpreeMyExtension::Config = SpreeMyExtension::Configuration.new+ end++ def self.activate+ Dir.glob(File.join(File.dirname(__FILE__), '../../app/**/*_decorator*.rb')) do |c|+ Rails.configuration.cache_classes ? require(c) : load(c)+ end+ end++ config.to_prepare(&method(:activate).to_proc)+ end+end+```++### Adding Models++```ruby+# app/models/spree/my_model.rb+module Spree+ class MyModel < Spree.base_class+ # Model implementation+ end+end+```++### Adding Controllers++```ruby+# app/controllers/spree/admin/my_models_controller.rb+module Spree+ module Admin+ class MyModelsController < ResourceController+ # Controller implementation+ end+ end+end+```++### Adding Migrations++```bash+cd spree_my_extension+bin/rails g migration CreateSpreeMyModels+```++## Publishing Extensions++1. Update version in `lib/spree_my_extension/version.rb`+2. Update `CHANGELOG.md`+3. Build and publish:++```bash+gem build spree_my_extension.gemspec+gem push spree_my_extension-1.0.0.gem+```++## Usage++### In a Spree Application++Add your extension to the application's Gemfile:++```ruby+gem 'spree_my_extension', '~> 1.0'+```++Run installation:++```bash+bundle install+bin/rails g spree_my_extension:install+```++## Documentation++- [Extension Development Guide](https://docs.spreecommerce.org/developer/extending-spree/extensions)+- [Creating Extensions Tutorial](https://docs.spreecommerce.org/developer/tutorials/extensions)+- [Spree Extensions Directory](https://spreecommerce.org/extensions)++## Contributing++1. Fork the repository+2. Create a feature branch+3. Make your changes+4. Run tests+5. Submit a pull request\ No newline at end of filediff --git a/core/README.md b/core/README.mdnew file mode 100644index 0000000000..e5f31baa96--- /dev/null+++ b/core/README.md@@ -0,0 +1,116 @@+# Spree Core++[](https://badge.fury.io/rb/spree_core)++Spree Core is the foundation of Spree Commerce, containing all the essential models, services, and business logic that power an e-commerce application.++## Overview++This gem provides:++- **Domain Models** - Products, Variants, Orders, Payments, Shipments, Taxons, Stores, and more+- **Services** - Cart operations, checkout flows, order management, inventory handling+- **State Machines** - Order and payment state management+- **Events System** - Publish/subscribe architecture for loose coupling+- **Dependencies Injection** - Swappable service implementations via `Spree::Dependencies`+- **Permissions** - CanCanCan-based authorization with Permission Sets++## Installation++This gem is included in every Spree installation. No additional steps are required.++## Key Components++### Models++All models are namespaced under `Spree::` and include:++- `Spree::Product` / `Spree::Variant` - Product catalog+- `Spree::Order` / `Spree::LineItem` - Order management+- `Spree::Payment` / `Spree::PaymentMethod` - Payment processing+- `Spree::Shipment` / `Spree::ShippingMethod` - Shipping and fulfillment+- `Spree::Taxon` / `Spree::Taxonomy` - Product categorization+- `Spree::Store` - Multi-store support+- `Spree::Promotion` - Promotions and discounts+- `Spree::GiftCard` - Gift card functionality++### Services++Services follow a consistent interface pattern and are located in `app/services/spree/`:++```ruby+# Add item to cart+Spree.cart_add_item_service.call(+ order: order,+ variant: variant,+ quantity: 1+)+```++### Events System++Spree uses an event-driven architecture for decoupling components:++```ruby+# Publishing events+order.publish_event('order.completed')++# Subscribing to events+module Spree+ module MySubscriber+ include Spree::Event::Subscriber++ event_action :order_completed++ def order_completed(event)+ order = event.payload[:order]+ # Handle the event+ end+ end+end+```++### Dependencies++Swap out default implementations with custom services:++```ruby+# config/initializers/spree.rb+Spree::Dependencies.cart_add_item_service = 'MyCustom::CartAddItem'+```++## Configuration++Configure Spree in an initializer:++```ruby+# config/initializers/spree.rb+Spree.config do |config|+ config.currency = 'USD'+ config.default_country_iso = 'US'+end+```++## Testing++Spree Core includes testing support utilities:++```ruby+# spec/rails_helper.rb+require 'spree/testing_support/factories'+require 'spree/testing_support/authorization_helpers'+```++To run the test suite:++```bash+cd core+bundle exec rake test_app # First time only+bundle exec rspec+```++## Documentation++- [Official Documentation](https://docs.spreecommerce.org)+- [API Reference](https://api.spreecommerce.org)+- [Guides](https://docs.spreecommerce.org/developer)\ No newline at end of filediff --git a/emails/README.md b/emails/README.mdnew file mode 100644index 0000000000..ad877c9b4c--- /dev/null+++ b/emails/README.md@@ -0,0 +1,210 @@+# Spree Emails++[](https://badge.fury.io/rb/spree_emails)++Spree Emails provides transactional email templates and mailers for Spree Commerce, handling order confirmations, shipment notifications, and other customer communications.++## Overview++This gem includes:++- **Order Mailer** - Order confirmation and cancellation emails+- **Shipment Mailer** - Shipping and delivery notifications+- **Reimbursement Mailer** - Refund notifications+- **Event Subscribers** - Automatic email triggers on store events+- **Email Templates** - Customizable HTML and text templates++## Installation++```bash+bundle add spree_emails+```++## Email Types++### Order Emails++- **Order Confirmation** - Sent when an order is completed+- **Order Cancellation** - Sent when an order is cancelled++### Shipment Emails++- **Shipment Notification** - Sent when a shipment is shipped+- **Delivery Confirmation** - Sent when tracking shows delivered++### Reimbursement Emails++- **Refund Notification** - Sent when a reimbursement is processed++## Configuration++Transactional emails are controlled per-store via the `send_consumer_transactional_emails` preference. This can be configured in the admin dashboard under Store Settings, or programmatically:++```ruby+# Enable/disable transactional emails for a store+store = Spree::Store.current+store.update(send_consumer_transactional_emails: true)+```++The sender address is configured via the `mail_from_address` attribute on each store:++```ruby+store.update(mail_from_address: '[email protected]')+```++### Action Mailer Configuration++```ruby+# config/environments/production.rb+config.action_mailer.delivery_method = :smtp+config.action_mailer.smtp_settings = {+ address: 'smtp.example.com',+ port: 587,+ user_name: ENV['SMTP_USERNAME'],+ password: ENV['SMTP_PASSWORD'],+ authentication: 'plain',+ enable_starttls_auto: true+}+```++## Customization++### Overriding Templates++Copy email templates to your application:++```bash+# Copy all email templates+cp -r $(bundle show spree_emails)/app/views/spree/mailer app/views/spree/++# Or copy specific templates+cp $(bundle show spree_emails)/app/views/spree/mailer/order_mailer/confirm_email.html.erb \+ app/views/spree/mailer/order_mailer/+```++### Template Structure++```+app/views/spree/mailer/+├── order_mailer/+│ ├── confirm_email.html.erb+│ ├── confirm_email.text.erb+│ ├── cancel_email.html.erb+│ └── cancel_email.text.erb+├── shipment_mailer/+│ ├── shipped_email.html.erb+│ └── shipped_email.text.erb+└── reimbursement_mailer/+ ├── reimbursement_email.html.erb+ └── reimbursement_email.text.erb+```++### Custom Mailer++Create custom mailers by extending Spree's base mailer:++```ruby+# app/mailers/spree/order_mailer_decorator.rb+module Spree+ module OrderMailerDecorator+ def confirm_email(order, resend = false)+ @custom_data = fetch_custom_data(order)+ super+ end++ private++ def fetch_custom_data(order)+ # Custom logic+ end+ end+end++Spree::OrderMailer.prepend(Spree::OrderMailerDecorator)+```++### Adding New Email Types++```ruby+# app/mailers/spree/custom_mailer.rb+module Spree+ class CustomMailer < BaseMailer+ def welcome_email(user)+ @user = user+ mail(to: @user.email, subject: 'Welcome to our store!')+ end+ end+end+```++## Event Integration++Emails are triggered via Spree's event system. Create custom subscribers:++```ruby+# app/subscribers/spree/custom_email_subscriber.rb+module Spree+ module CustomEmailSubscriber+ include Spree::Event::Subscriber++ event_action :user_registered++ def user_registered(event)+ user = event.payload[:user]+ Spree::CustomMailer.welcome_email(user).deliver_later+ end+ end+end+```++## Disabling Emails++Disable transactional emails for a specific store:++```ruby+store = Spree::Store.current+store.update(send_consumer_transactional_emails: false)+```++This setting can also be managed in the admin dashboard under Store Settings.++To disable all Spree transactional emails globally, remove this gem from your application:++```bash+bundle remove spree_emails+```++### Using Third-Party Email Services++If you prefer to use a third-party email service like Klaviyo for transactional emails, you can use the [spree_klaviyo](https://github.com/spree/spree_klaviyo) extension. This allows you to leverage Klaviyo's email marketing platform for order confirmations, shipment notifications, and other transactional emails.++## Testing++Preview emails in development:++```ruby+# test/mailers/previews/spree/order_mailer_preview.rb+module Spree+ class OrderMailerPreview < ActionMailer::Preview+ def confirm_email+ order = Spree::Order.complete.last+ Spree::OrderMailer.confirm_email(order)+ end+ end+end+```++Visit `http://localhost:3000/rails/mailers/spree/order_mailer/confirm_email`++Run the test suite:++```bash+cd emails+bundle exec rake test_app # First time only+bundle exec rspec+```++## Documentation++- [Email Customization Guide](https://docs.spreecommerce.org/developer/customization/emails)+- [Events System](https://docs.spreecommerce.org/developer/core-concepts/events)\ No newline at end of filediff --git a/sample/README.md b/sample/README.mdnew file mode 100644index 0000000000..ad216fe8fe--- /dev/null+++ b/sample/README.md@@ -0,0 +1,155 @@+# Spree Sample++[](https://badge.fury.io/rb/spree_sample)++Spree Sample provides sample data for quickly populating a Spree Commerce store with products, categories, and other content for development and demonstration purposes.++## Overview++This gem includes:++- **Sample Products** - Demo products with images, variants, and pricing+- **Taxonomies & Taxons** - Product categories and navigation+- **Stores** - Default store configuration+- **Shipping & Payment** - Pre-configured shipping and payment methods+- **Stock** - Inventory data for sample products+- **Assets** - Product images and other media++## Installation++```bash+bundle add spree_sample+```++## Loading Sample Data++```bash+bin/rails spree_sample:load+```++## Sample Data Contents++### Products++- Multiple product types (apparel, accessories, etc.)+- Product variants with options (size, color)+- Product images+- Pricing information+- Stock quantities++### Taxonomies++- Categories taxonomy+- Brand taxonomy+- Sample taxons with product associations++### Store Configuration++- Default store settings+- Currency and locale+- SEO defaults++### Shipping++- Shipping categories+- Shipping methods with zones+- Calculator configurations++### Payment++- Payment methods+- Test payment gateway++## Customization++### Loading Specific Samples++Load only the data you need:++```ruby+require 'spree/sample'++# Load specific samples+Spree::Sample.load_sample('stores')+Spree::Sample.load_sample('taxonomies')+Spree::Sample.load_sample('products')+Spree::Sample.load_sample('variants')+```++### Custom Sample Data++Create your own sample data files:++```ruby+# db/samples/my_custom_data.rb+Spree::Product.find_or_create_by!(name: 'Custom Product') do |product|+ product.price = 29.99+ product.shipping_category = Spree::ShippingCategory.first+end+```++Load custom samples:++```ruby+load Rails.root.join('db/samples/my_custom_data.rb')+```++### Sample Data Structure++```+sample/+├── db/+│ ├── samples/+│ │ ├── stores.rb+│ │ ├── tax_categories.rb+│ │ ├── shipping_categories.rb+│ │ ├── taxonomies.rb+│ │ ├── products.rb+│ │ ├── variants.rb+│ │ ├── option_types.rb+│ │ ├── option_values.rb+│ │ ├── images/+│ │ └── ...+│ └── seeds.rb+└── lib/+ ├── spree_sample.rb+ └── tasks/+ └── sample.rake+```++## Dependencies++- **FFaker** - Used for generating realistic fake data++## Development Use Cases++- **Local Development** - Quick store setup for testing features+- **Demos** - Showcase Spree capabilities to stakeholders+- **CI/CD** - Consistent test data for automated testing+- **Training** - Learning environment with realistic data++## Clearing Sample Data++To reset and reload sample data:++```ruby+# Clear existing data (be careful in production!)+Spree::Product.destroy_all+Spree::Taxon.destroy_all++# Reload samples+bin/rails spree_sample:load+```++## Testing++```bash+cd sample+bundle exec rake test_app # First time only+bundle exec rspec+```++## Documentation++- [Installation Guide](https://docs.spreecommerce.org/developer/getting-started/installation)+- [Sample Data Reference](https://docs.spreecommerce.org/developer/getting-started/sample-data)\ No newline at end of filediff --git a/storefront/README.md b/storefront/README.mdnew file mode 100644index 0000000000..af69ab7bb8--- /dev/null+++ b/storefront/README.md@@ -0,0 +1,188 @@+# Spree Storefront++[](https://badge.fury.io/rb/spree_storefront)++Spree Storefront provides a modern, fully-featured Rails-based storefront for Spree Commerce with a responsive design and optimized shopping experience.++## Overview++This gem includes:++- **Product Catalog** - Browsing, filtering, and search+- **Shopping Cart** - Full cart management with guest and authenticated checkout+- **Checkout Flow** - Multi-step checkout with address, shipping, and payment+- **Customer Accounts** - Registration, login, order history, wishlists+- **Page Builder Integration** - Custom landing pages and content+- **SEO Optimization** - Meta tags, structured data, and sitemap support++## Installation++```bash+bundle add spree_storefront+bin/rails g spree:storefront:install+```++## Features++### Product Catalog++- Product listing with pagination+- Category and taxonomy navigation+- Faceted search and filtering+- Product variants and options+- Image galleries+- Related products++### Shopping Cart++- Add/remove items+- Update quantities+- Apply coupon codes+- Guest cart persistence+- Cart merge on login++### Checkout++- Address management (billing/shipping)+- Shipping method selection+- Payment processing+- Order review and confirmation+- Guest checkout support++### Customer Accounts++- Registration and authentication+- Order history+- Address book+- Wishlists+- Account settings++## Technology Stack++- **Tailwind CSS** - Responsive, mobile-first design+- **Turbo/Hotwire** - Fast, SPA-like navigation+- **Stimulus** - JavaScript controllers for interactivity+- **Heroicons** - Icon library++## Customization++### Overriding Views++Copy views to customize the storefront appearance:++```bash+# Copy all storefront views+cp -r $(bundle show spree_storefront)/app/views/spree app/views/++# Or copy specific templates+cp $(bundle show spree_storefront)/app/views/spree/products/show.html.erb \+ app/views/spree/products/+```++### Styling++Customize Tailwind configuration:++```javascript+// tailwind.config.js+module.exports = {+ content: [+ // Include Spree Storefront views+ `${process.env.GEM_HOME}/gems/spree_storefront-*/app/views/**/*.erb`,+ './app/views/**/*.erb',+ './app/helpers/**/*.rb',+ './app/javascript/**/*.js'+ ],+ theme: {+ extend: {+ colors: {+ primary: '#your-brand-color'+ }+ }+ }+}+```++### Controllers++Extend storefront controllers for custom behavior:++```ruby+# app/controllers/spree/products_controller_decorator.rb+module Spree+ module ProductsControllerDecorator+ def show+ super+ @related_products = @product.related_products.limit(4)+ end+ end+end++Spree::ProductsController.prepend(Spree::ProductsControllerDecorator)+```++### Helpers++Add custom helpers for view logic:++```ruby+# app/helpers/spree/products_helper_decorator.rb+module Spree+ module ProductsHelperDecorator+ def product_badge(product)+ return unless product.on_sale?+ content_tag(:span, 'Sale', class: 'badge badge-sale')+ end+ end+end++Spree::ProductsHelper.prepend(Spree::ProductsHelperDecorator)+```++## Routes++Storefront routes are mounted automatically. Customize in your routes file:++```ruby+# config/routes.rb+Rails.application.routes.draw do+ # Custom routes before Spree+ get '/shop', to: redirect('/products')++ # Spree routes+ mount Spree::Core::Engine, at: '/'+end+```++## Testing++```bash+cd storefront+bundle exec rake test_app # First time only+bundle exec rspec+```++## Page Builder Integration++The storefront integrates with Spree Page Builder for custom pages:++```ruby+# Custom page sections are automatically rendered+# Configure in admin under Content > Pages+```++## Documentation++- [Storefront Customization](https://docs.spreecommerce.org/developer/customization/storefront)+- [Theming Guide](https://docs.spreecommerce.org/developer/customization/theming)+- [Page Builder](https://docs.spreecommerce.org/developer/page-builder)++## Headless Alternative++For custom frontends (React, Vue, Next.js), use `spree_api` without `spree_storefront`:++```ruby+# Headless setup+gem 'spree' # Core + API+gem 'spree_admin' # Admin dashboard only+```\ No newline at end of file