Skip to content

armgit / spree

Public Imported from GitHub
0

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.

[skip CI] Added README files for all gems

Damian Legawiec32e549f04bfc
diff --git a/admin/README.md b/admin/README.md
index 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.
+[![Gem Version](https://badge.fury.io/rb/spree_admin.svg)](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
```bash
bundle 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 file
diff --git a/api/README.md b/api/README.md
new file mode 100644
index 0000000000..e2269924d0
--- /dev/null
+++ b/api/README.md
@@ -0,0 +1,99 @@
+# Spree API
+
+[![Gem Version](https://badge.fury.io/rb/spree_api.svg)](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 file
diff --git a/cli/README.md b/cli/README.md
index 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
+[![Gem Version](https://badge.fury.io/rb/spree_cli.svg)](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:
+
+```bash
spree 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 file
diff --git a/core/README.md b/core/README.md
new file mode 100644
index 0000000000..e5f31baa96
--- /dev/null
+++ b/core/README.md
@@ -0,0 +1,116 @@
+# Spree Core
+
+[![Gem Version](https://badge.fury.io/rb/spree_core.svg)](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 file
diff --git a/emails/README.md b/emails/README.md
new file mode 100644
index 0000000000..ad877c9b4c
--- /dev/null
+++ b/emails/README.md
@@ -0,0 +1,210 @@
+# Spree Emails
+
+[![Gem Version](https://badge.fury.io/rb/spree_emails.svg)](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 file
diff --git a/sample/README.md b/sample/README.md
new file mode 100644
index 0000000000..ad216fe8fe
--- /dev/null
+++ b/sample/README.md
@@ -0,0 +1,155 @@
+# Spree Sample
+
+[![Gem Version](https://badge.fury.io/rb/spree_sample.svg)](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 file
diff --git a/storefront/README.md b/storefront/README.md
new file mode 100644
index 0000000000..af69ab7bb8
--- /dev/null
+++ b/storefront/README.md
@@ -0,0 +1,188 @@
+# Spree Storefront
+
+[![Gem Version](https://badge.fury.io/rb/spree_storefront.svg)](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