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] fixed Cursor Rules file names

Damian Legawiec8ec1f118535e
diff --git a/.cursor/rules/spree.md b/.cursor/rules/spree.md
deleted file mode 100644
index c7b7da3c8e..0000000000
--- a/.cursor/rules/spree.md
+++ /dev/null
@@ -1,78 +0,0 @@
-# General Spree Commerce Rules
-
-## Framework & Architecture
-- Spree is built on Ruby on Rails and follows MVC architecture
-- All Spree code must be namespaced under `Spree::` module
-- Spree is distributed as Rails engines with separate gems (core, admin, api, storefront, emails, etc.)
-- Follow Rails conventions and the Rails Security Guide
-- Prefer Rails idioms and standard patterns over custom solutions
-
-## Core Naming Conventions
-- Do NOT call `Spree::User` directly, use `Spree.user_class` instead
-- Do NOT call `Spree::AdminUser` directly, use `Spree.admin_user_class` instead
-- Always inherit from `Spree.base_class` when creating models
-- Use consistent file naming: `spree/product.rb` for `Spree::Product` class
-
-## Model Standards
-- Use ActiveRecord associations with `class_name` and `dependent` options
-- For uniqueness validation, always use `scope: spree_base_uniqueness_scope`
-- Include `Spree::Metadata` concern for models that need metadata support
-- Use scopes for reusable query patterns
-
-```ruby
-# ✅ Correct model structure
-class Spree::Product < Spree.base_class
- include Spree::Metadata
-
- has_many :variants, class_name: 'Spree::Variant', dependent: :destroy
- has_many :product_properties, class_name: 'Spree::ProductProperty', dependent: :destroy
-
- scope :available, -> { where(available_on: ..Time.current) }
-
- validates :name, presence: true
- validates :slug, presence: true, uniqueness: { scope: spree_base_uniqueness_scope }
-end
-```
-
-## Database & Migration Standards
-- Follow Rails migration conventions
-- Use proper indexing for performance
-- Do NOT include foreign key constraints
-- Always add `null: false` to required columns
-- Add unique indexes to columns used for uniqueness validation
-- Add `deleted_at` column to tables with soft delete functionality (paranoia gem)
-
-## Security Standards
-- Follow Rails Security Guide principles
-- Use strong parameters consistently
-- Always use `Spree::PermittedAttributes` to define allowed parameters
-- Never permit mass assignment without validation
-- Use allowlists, not blocklists for parameters
-
-## Performance Guidelines
-- Use includes/preload to avoid N+1 queries
-- Implement proper database indexing
-- Use scopes for reusable query logic
-- Consider caching for expensive operations
-
-## Error Handling
-- Use Rails error reporter
-- Use appropriate exception classes
-- Provide meaningful error messages
-- Implement proper error recovery where possible
-
-## Internationalization
-- Use `Spree.t` for translations instead of `I18n.t`
-- Do NOT repeat translations in multiple files
-- Try to use existing translations as much as possible
-
-## Testing Standards
-- Use RSpec for testing
-- Use `create` for persisted objects in tests
-- Use `build` for non-persisted objects (faster)
-- Add new factories in `lib/spree/testing_support/factories/`
-
-## Documentation
-- Document complex business logic
-- Use YARD documentation format for public APIs
-- Keep comments up-to-date with code changes
diff --git a/.cursor/rules/spree.mdc b/.cursor/rules/spree.mdc
new file mode 100644
index 0000000000..47b76a7c6c
--- /dev/null
+++ b/.cursor/rules/spree.mdc
@@ -0,0 +1,160 @@
+---
+alwaysApply: true
+---
+
+# General Spree Commerce Rules
+
+## Framework & Architecture
+- Spree is built on Ruby on Rails and follows MVC architecture
+- All Spree code must be namespaced under `Spree::` module
+- Spree is distributed as Rails engines with separate gems (core, admin, api, storefront, emails, etc.)
+- Follow Rails conventions and the Rails Security Guide
+- Prefer Rails idioms and standard patterns over custom solutions
+
+## Core Naming Conventions
+- Do NOT call `Spree::User` directly, use `Spree.user_class` instead
+- Do NOT call `Spree::AdminUser` directly, use `Spree.admin_user_class` instead
+- Always inherit from `Spree.base_class` when creating models
+- Use consistent file naming: `spree/product.rb` for `Spree::Product` class
+
+## Model Standards
+- Use ActiveRecord associations with `class_name` and `dependent` options
+- For uniqueness validation, always use `scope: spree_base_uniqueness_scope`
+- Include `Spree::Metadata` concern for models that need metadata support
+- Use scopes for reusable query patterns
+
+```ruby
+# ✅ Correct model structure
+class Spree::Product < Spree.base_class
+ include Spree::Metadata
+
+ has_many :variants, class_name: 'Spree::Variant', dependent: :destroy
+ has_many :product_properties, class_name: 'Spree::ProductProperty', dependent: :destroy
+
+ scope :available, -> { where(available_on: ..Time.current) }
+
+ validates :name, presence: true
+ validates :slug, presence: true, uniqueness: { scope: spree_base_uniqueness_scope }
+end
+```
+
+## Database & Migration Standards
+- Follow Rails migration conventions
+- Use proper indexing for performance
+- Do NOT include foreign key constraints
+- Always add `null: false` to required columns
+- Add unique indexes to columns used for uniqueness validation
+- Add `deleted_at` column to tables with soft delete functionality (paranoia gem)
+
+## Security Standards
+- Follow Rails Security Guide principles
+- Use strong parameters consistently
+- Always use `Spree::PermittedAttributes` to define allowed parameters
+- Never permit mass assignment without validation
+- Use allowlists, not blocklists for parameters
+
+## Performance Guidelines
+- Use includes/preload to avoid N+1 queries
+- Implement proper database indexing
+- Use scopes for reusable query logic
+- Consider caching for expensive operations
+
+## Error Handling
+- Use Rails error reporter
+- Use appropriate exception classes
+- Provide meaningful error messages
+- Implement proper error recovery where possible
+
+## Internationalization
+- Use `Spree.t` for translations instead of `I18n.t`
+- Do NOT repeat translations in multiple files
+- Try to use existing translations as much as possible
+
+## Testing Standards
+- Use RSpec for testing
+- Use `create` for persisted objects in tests
+- Use `build` for non-persisted objects (faster)
+- Add new factories in `lib/spree/testing_support/factories/`
+
+## Documentation
+- Document complex business logic
+- Use YARD documentation format for public APIs
+- Keep comments up-to-date with code changes
+# General Spree Commerce Rules
+
+## Framework & Architecture
+- Spree is built on Ruby on Rails and follows MVC architecture
+- All Spree code must be namespaced under `Spree::` module
+- Spree is distributed as Rails engines with separate gems (core, admin, api, storefront, emails, etc.)
+- Follow Rails conventions and the Rails Security Guide
+- Prefer Rails idioms and standard patterns over custom solutions
+
+## Core Naming Conventions
+- Do NOT call `Spree::User` directly, use `Spree.user_class` instead
+- Do NOT call `Spree::AdminUser` directly, use `Spree.admin_user_class` instead
+- Always inherit from `Spree.base_class` when creating models
+- Use consistent file naming: `spree/product.rb` for `Spree::Product` class
+
+## Model Standards
+- Use ActiveRecord associations with `class_name` and `dependent` options
+- For uniqueness validation, always use `scope: spree_base_uniqueness_scope`
+- Include `Spree::Metadata` concern for models that need metadata support
+- Use scopes for reusable query patterns
+
+```ruby
+# ✅ Correct model structure
+class Spree::Product < Spree.base_class
+ include Spree::Metadata
+
+ has_many :variants, class_name: 'Spree::Variant', dependent: :destroy
+ has_many :product_properties, class_name: 'Spree::ProductProperty', dependent: :destroy
+
+ scope :available, -> { where(available_on: ..Time.current) }
+
+ validates :name, presence: true
+ validates :slug, presence: true, uniqueness: { scope: spree_base_uniqueness_scope }
+end
+```
+
+## Database & Migration Standards
+- Follow Rails migration conventions
+- Use proper indexing for performance
+- Do NOT include foreign key constraints
+- Always add `null: false` to required columns
+- Add unique indexes to columns used for uniqueness validation
+- Add `deleted_at` column to tables with soft delete functionality (paranoia gem)
+
+## Security Standards
+- Follow Rails Security Guide principles
+- Use strong parameters consistently
+- Always use `Spree::PermittedAttributes` to define allowed parameters
+- Never permit mass assignment without validation
+- Use allowlists, not blocklists for parameters
+
+## Performance Guidelines
+- Use includes/preload to avoid N+1 queries
+- Implement proper database indexing
+- Use scopes for reusable query logic
+- Consider caching for expensive operations
+
+## Error Handling
+- Use Rails error reporter
+- Use appropriate exception classes
+- Provide meaningful error messages
+- Implement proper error recovery where possible
+
+## Internationalization
+- Use `Spree.t` for translations instead of `I18n.t`
+- Do NOT repeat translations in multiple files
+- Try to use existing translations as much as possible
+
+## Testing Standards
+- Use RSpec for testing
+- Use `create` for persisted objects in tests
+- Use `build` for non-persisted objects (faster)
+- Add new factories in `lib/spree/testing_support/factories/`
+
+## Documentation
+- Document complex business logic
+- Use YARD documentation format for public APIs
+- Keep comments up-to-date with code changes
diff --git a/admin/.cursor/rules/admin.md b/admin/.cursor/rules/admin.md
deleted file mode 100644
index 10ce425e8f..0000000000
--- a/admin/.cursor/rules/admin.md
+++ /dev/null
@@ -1,112 +0,0 @@
-# Spree Admin Interface Rules
-
-## Controller Standards
-- Admin controllers inherit from `Spree::Admin::ResourceController`
-- ResourceController handles most CRUD operations automatically
-- Use `stub_authorization!` for controller spec authentication
-- Always add `render_views` to controller specs
-
-```ruby
-# ✅ Proper admin controller
-class Spree::Admin::ProductsController < Spree::Admin::ResourceController
- private
-
- def permitted_resource_params
- params.require(:product).permit(Spree::PermittedAttributes.product_attributes)
- end
-end
-```
-
-## Form Builder Standards
-- Use `Spree::Admin::FormBuilder` methods for all form fields
-- Always use the provided form field methods for consistency
-
-### Available Form Field Methods
-- `f.spree_text_field :name`
-- `f.spree_number_field :price`
-- `f.spree_email_field :email`
-- `f.spree_date_field :available_on`
-- `f.spree_datetime_field :discontinue_on`
-- `f.spree_text_area :description`
-- `f.spree_rich_text_area :description` (with Trix editor)
-- `f.spree_select :category_id, options`
-- `f.spree_collection_select :category_id, collection, :id, :name`
-- `f.spree_check_box :active`
-- `f.spree_radio_button :status, 'active'`
-
-### Form Structure Standards
-For new resource forms:
-```erb
-<%= render 'spree/admin/shared/new_resource' %>
-```
-
-For edit resource forms:
-```erb
-<%= render 'spree/admin/shared/edit_resource' %>
-```
-
-### Reusable Form Partial Pattern
-Create `_form.html.erb` with proper card structure:
-```erb
-<div class="card mb-4">
- <div class="card-header">
- <h5 class="card-title">
- <%= Spree.t(:general_settings) %>
- </h5>
- </div>
-
- <div class="card-body">
- <%= f.spree_text_field :name %>
- <%= f.spree_rich_text_area :description %>
- <%= f.spree_check_box :active %>
- </div>
-</div>
-```
-
-## View Standards
-- Use Turbo Rails features (Hotwire) as much as possible
-- Use Stimulus controllers for JavaScript interactions
-- Follow Bootstrap 4 styling conventions
-- Use `Spree.t` for all translations
-
-## JavaScript & Stimulus
-- Place Stimulus controllers in `app/javascript/controllers/spree/admin/`
-- Use data attributes for controller binding
-- Follow Stimulus naming conventions
-
-## Asset Organization
-- Stylesheets: `app/assets/stylesheets/spree/admin/`
-- JavaScript: `app/javascript/`
-- Images: `app/assets/images/spree/admin/`
-
-## Security
-- Admin controllers are automatically secured when inheriting from ResourceController
-- Use CanCanCan for authorization
-- Authentication handled by app developers (Devise installer provided)
-
-## Translation Files
-- Place admin translations in `admin/config/locales/en.yml`
-- Use namespace structure: `spree.admin.product.name`
-- Reuse existing translations when possible
-
-## Testing Standards
-- Place admin specs in `spec/controllers/spree/admin/`
-- Always use `render_views` in controller specs
-- Use `stub_authorization!` for authentication in specs
-
-```ruby
-# ✅ Proper admin controller spec
-require 'spec_helper'
-
-RSpec.describe Spree::Admin::ProductsController, type: :controller do
- stub_authorization!
- render_views
-
- describe '#index' do
- it 'renders the index template' do
- get :index
- expect(response).to render_template(:index)
- end
- end
-end
-```
diff --git a/admin/.cursor/rules/admin.mdc b/admin/.cursor/rules/admin.mdc
new file mode 100644
index 0000000000..a7f13ec868
--- /dev/null
+++ b/admin/.cursor/rules/admin.mdc
@@ -0,0 +1,228 @@
+---
+alwaysApply: true
+---
+
+# Spree Admin Interface Rules
+
+## Controller Standards
+- Admin controllers inherit from `Spree::Admin::ResourceController`
+- ResourceController handles most CRUD operations automatically
+- Use `stub_authorization!` for controller spec authentication
+- Always add `render_views` to controller specs
+
+```ruby
+# ✅ Proper admin controller
+class Spree::Admin::ProductsController < Spree::Admin::ResourceController
+ private
+
+ def permitted_resource_params
+ params.require(:product).permit(Spree::PermittedAttributes.product_attributes)
+ end
+end
+```
+
+## Form Builder Standards
+- Use `Spree::Admin::FormBuilder` methods for all form fields
+- Always use the provided form field methods for consistency
+
+### Available Form Field Methods
+- `f.spree_text_field :name`
+- `f.spree_number_field :price`
+- `f.spree_email_field :email`
+- `f.spree_date_field :available_on`
+- `f.spree_datetime_field :discontinue_on`
+- `f.spree_text_area :description`
+- `f.spree_rich_text_area :description` (with Trix editor)
+- `f.spree_select :category_id, options`
+- `f.spree_collection_select :category_id, collection, :id, :name`
+- `f.spree_check_box :active`
+- `f.spree_radio_button :status, 'active'`
+
+### Form Structure Standards
+For new resource forms:
+```erb
+<%= render 'spree/admin/shared/new_resource' %>
+```
+
+For edit resource forms:
+```erb
+<%= render 'spree/admin/shared/edit_resource' %>
+```
+
+### Reusable Form Partial Pattern
+Create `_form.html.erb` with proper card structure:
+```erb
+<div class="card mb-4">
+ <div class="card-header">
+ <h5 class="card-title">
+ <%= Spree.t(:general_settings) %>
+ </h5>
+ </div>
+
+ <div class="card-body">
+ <%= f.spree_text_field :name %>
+ <%= f.spree_rich_text_area :description %>
+ <%= f.spree_check_box :active %>
+ </div>
+</div>
+```
+
+## View Standards
+- Use Turbo Rails features (Hotwire) as much as possible
+- Use Stimulus controllers for JavaScript interactions
+- Follow Bootstrap 4 styling conventions
+- Use `Spree.t` for all translations
+
+## JavaScript & Stimulus
+- Place Stimulus controllers in `app/javascript/controllers/spree/admin/`
+- Use data attributes for controller binding
+- Follow Stimulus naming conventions
+
+## Asset Organization
+- Stylesheets: `app/assets/stylesheets/spree/admin/`
+- JavaScript: `app/javascript/`
+- Images: `app/assets/images/spree/admin/`
+
+## Security
+- Admin controllers are automatically secured when inheriting from ResourceController
+- Use CanCanCan for authorization
+- Authentication handled by app developers (Devise installer provided)
+
+## Translation Files
+- Place admin translations in `admin/config/locales/en.yml`
+- Use namespace structure: `spree.admin.product.name`
+- Reuse existing translations when possible
+
+## Testing Standards
+- Place admin specs in `spec/controllers/spree/admin/`
+- Always use `render_views` in controller specs
+- Use `stub_authorization!` for authentication in specs
+
+```ruby
+# ✅ Proper admin controller spec
+require 'spec_helper'
+
+RSpec.describe Spree::Admin::ProductsController, type: :controller do
+ stub_authorization!
+ render_views
+
+ describe '#index' do
+ it 'renders the index template' do
+ get :index
+ expect(response).to render_template(:index)
+ end
+ end
+end
+```
+# Spree Admin Interface Rules
+
+## Controller Standards
+- Admin controllers inherit from `Spree::Admin::ResourceController`
+- ResourceController handles most CRUD operations automatically
+- Use `stub_authorization!` for controller spec authentication
+- Always add `render_views` to controller specs
+
+```ruby
+# ✅ Proper admin controller
+class Spree::Admin::ProductsController < Spree::Admin::ResourceController
+ private
+
+ def permitted_resource_params
+ params.require(:product).permit(Spree::PermittedAttributes.product_attributes)
+ end
+end
+```
+
+## Form Builder Standards
+- Use `Spree::Admin::FormBuilder` methods for all form fields
+- Always use the provided form field methods for consistency
+
+### Available Form Field Methods
+- `f.spree_text_field :name`
+- `f.spree_number_field :price`
+- `f.spree_email_field :email`
+- `f.spree_date_field :available_on`
+- `f.spree_datetime_field :discontinue_on`
+- `f.spree_text_area :description`
+- `f.spree_rich_text_area :description` (with Trix editor)
+- `f.spree_select :category_id, options`
+- `f.spree_collection_select :category_id, collection, :id, :name`
+- `f.spree_check_box :active`
+- `f.spree_radio_button :status, 'active'`
+
+### Form Structure Standards
+For new resource forms:
+```erb
+<%= render 'spree/admin/shared/new_resource' %>
+```
+
+For edit resource forms:
+```erb
+<%= render 'spree/admin/shared/edit_resource' %>
+```
+
+### Reusable Form Partial Pattern
+Create `_form.html.erb` with proper card structure:
+```erb
+<div class="card mb-4">
+ <div class="card-header">
+ <h5 class="card-title">
+ <%= Spree.t(:general_settings) %>
+ </h5>
+ </div>
+
+ <div class="card-body">
+ <%= f.spree_text_field :name %>
+ <%= f.spree_rich_text_area :description %>
+ <%= f.spree_check_box :active %>
+ </div>
+</div>
+```
+
+## View Standards
+- Use Turbo Rails features (Hotwire) as much as possible
+- Use Stimulus controllers for JavaScript interactions
+- Follow Bootstrap 4 styling conventions
+- Use `Spree.t` for all translations
+
+## JavaScript & Stimulus
+- Place Stimulus controllers in `app/javascript/controllers/spree/admin/`
+- Use data attributes for controller binding
+- Follow Stimulus naming conventions
+
+## Asset Organization
+- Stylesheets: `app/assets/stylesheets/spree/admin/`
+- JavaScript: `app/javascript/`
+- Images: `app/assets/images/spree/admin/`
+
+## Security
+- Admin controllers are automatically secured when inheriting from ResourceController
+- Use CanCanCan for authorization
+- Authentication handled by app developers (Devise installer provided)
+
+## Translation Files
+- Place admin translations in `admin/config/locales/en.yml`
+- Use namespace structure: `spree.admin.product.name`
+- Reuse existing translations when possible
+
+## Testing Standards
+- Place admin specs in `spec/controllers/spree/admin/`
+- Always use `render_views` in controller specs
+- Use `stub_authorization!` for authentication in specs
+
+```ruby
+# ✅ Proper admin controller spec
+require 'spec_helper'
+
+RSpec.describe Spree::Admin::ProductsController, type: :controller do
+ stub_authorization!
+ render_views
+
+ describe '#index' do
+ it 'renders the index template' do
+ get :index
+ expect(response).to render_template(:index)
+ end
+ end
+end
+```
diff --git a/api/.cursor/rules/api.md b/api/.cursor/rules/api.mdc
similarity index 99%
rename from api/.cursor/rules/api.md
rename to api/.cursor/rules/api.mdc
index ce98ec3881..ac8cf48c4f 100644
--- a/api/.cursor/rules/api.md
+++ b/api/.cursor/rules/api.mdc
@@ -1,3 +1,7 @@
+---
+alwaysApply: true
+---
+
# Spree API Rules
## Controller Standards
diff --git a/core/.cursor/rules/core.md b/core/.cursor/rules/core.mdc
similarity index 99%
rename from core/.cursor/rules/core.md
rename to core/.cursor/rules/core.mdc
index 076cf019bf..10b182ee68 100644
--- a/core/.cursor/rules/core.md
+++ b/core/.cursor/rules/core.mdc
@@ -1,3 +1,7 @@
+---
+alwaysApply: true
+---
+
# Spree Core Rules
## Model Standards
diff --git a/core/lib/generators/spree/cursor_rules/cursor_rules_generator.rb b/core/lib/generators/spree/cursor_rules/cursor_rules_generator.rb
index d49860af9a..8351220171 100644
--- a/core/lib/generators/spree/cursor_rules/cursor_rules_generator.rb
+++ b/core/lib/generators/spree/cursor_rules/cursor_rules_generator.rb
@@ -13,7 +13,7 @@ module Spree
end
def copy_cursor_rules
- copy_file 'spree_rules.md', '.cursor/rules/spree_rules.md'
+ copy_file 'spree_rules.mdc', '.cursor/rules/spree_rules.mdc'
end
end
end
diff --git a/core/lib/generators/spree/cursor_rules/templates/spree_rules.md b/core/lib/generators/spree/cursor_rules/templates/spree_rules.mdc
similarity index 99%
rename from core/lib/generators/spree/cursor_rules/templates/spree_rules.md
rename to core/lib/generators/spree/cursor_rules/templates/spree_rules.mdc
index 0af9096b10..3828400b67 100644
--- a/core/lib/generators/spree/cursor_rules/templates/spree_rules.md
+++ b/core/lib/generators/spree/cursor_rules/templates/spree_rules.mdc
@@ -1,3 +1,7 @@
+---
+alwaysApply: true
+---
+
# Cursor Rules for Spree Commerce Development
## General Development Guidelines
diff --git a/emails/.cursor/rules/emails.md b/emails/.cursor/rules/emails.mdc
similarity index 99%
rename from emails/.cursor/rules/emails.md
rename to emails/.cursor/rules/emails.mdc
index 23eb2475ed..429a1b4e17 100644
--- a/emails/.cursor/rules/emails.md
+++ b/emails/.cursor/rules/emails.mdc
@@ -1,3 +1,7 @@
+---
+alwaysApply: true
+---
+
# Spree Emails Rules
## Mailer Standards
diff --git a/sample/.cursor/rules/sample.md b/sample/.cursor/rules/sample.mdc
similarity index 98%
rename from sample/.cursor/rules/sample.md
rename to sample/.cursor/rules/sample.mdc
index 399f9cb337..5b82c46a13 100644
--- a/sample/.cursor/rules/sample.md
+++ b/sample/.cursor/rules/sample.mdc
@@ -1,3 +1,7 @@
+---
+alwaysApply: true
+---
+
# Spree Sample Data Rules
## Sample Data Standards
diff --git a/storefront/.cursor/rules/storefront.md b/storefront/.cursor/rules/storefront.md
deleted file mode 100644
index c3ab61957e..0000000000
--- a/storefront/.cursor/rules/storefront.md
+++ /dev/null
@@ -1,209 +0,0 @@
-# Spree Storefront Rules
-
-## Controller Standards
-- Storefront controllers inherit from `Spree::StoreController`
-- Handle customer-facing functionality
-- Implement proper SEO and caching
-- Use secure session handling
-
-```ruby
-# ✅ Storefront controller structure
-class Spree::ProductsController < Spree::StoreController
- before_action :find_product, only: [:show]
-
- def index
- @products = current_store.products.available.includes(:images, :variants)
- @products = @products.ransack(params[:q]).result if params[:q].present?
- @products = @products.page(params[:page])
- end
-
- def show
- @variants = @product.variants.includes(:images, :option_values)
- @product_properties = @product.product_properties.includes(:property)
- end
-
- private
-
- def find_product
- @product = current_store.products.friendly.find(params[:id])
- rescue ActiveRecord::RecordNotFound
- redirect_to products_path, alert: Spree.t('product_not_found')
- end
-end
-```
-
-## View Standards
-- Use Tailwind CSS for styling
-- Follow responsive design principles
-- Implement proper semantic HTML
-- Include accessibility attributes
-
-```erb
-<!-- ✅ Proper storefront view structure -->
-<article class="product-details" itemscope itemtype="http://schema.org/Product">
- <header class="product-header">
- <h1 class="text-3xl font-bold text-gray-900" itemprop="name">
- <%= @product.name %>
- </h1>
-
- <div class="mt-2">
- <span class="text-2xl font-semibold text-gray-900" itemprop="price">
- <%= @product.display_price %>
- </span>
- </div>
- </header>
-
- <div class="product-description mt-6" itemprop="description">
- <%= simple_format(@product.description) %>
- </div>
-</article>
-```
-
-## JavaScript & Stimulus
-
-- Try to use Turbo for all AJAX requests
-- Use Stimulus for interactive components that cannot be handled by Turbo
-- Place Stimulus controllers in `app/javascript/controllers/spree/storefront/`
-- Follow progressive enhancement principles
-- Minimize JavaScript dependencies
-
-```javascript
-// ✅ Storefront Stimulus controller
-import { Controller } from "@hotwired/stimulus"
-import { post } from "@rails/request.js"
-
-export default class extends Controller {
- static targets = ["quantity", "addToCart"]
- static values = {
- productId: Number,
- variantId: Number
- }
-
- connect() {
- this.updateAddToCartState()
- }
-
- updateQuantity(event) {
- const quantity = parseInt(event.target.value)
- this.updateAddToCartState()
- }
-
- async addToCart(event) {
- event.preventDefault()
-
- const response = await post('/line_items', {
- body: {
- variant_id: this.variantIdValue,
- quantity: this.quantityTarget.value
- }
- })
-
- if (response.ok) {
- const data = await response.json
- this.handleAddToCartResponse(data)
- }
- }
-}
-
-## SEO Standards
-- Include proper meta tags
-- Use structured data markup
-- Implement canonical URLs
-- Optimize page titles and descriptions
-
-```erb
-<!-- ✅ SEO meta tags -->
-<% content_for :title, @product.meta_title.presence || @product.name %>
-<% content_for :description, @product.meta_description.presence || truncate(@product.description, length: 160) %>
-
-<%= content_tag :div, itemscope: true, itemtype: "http://schema.org/Product" do %>
- <meta itemprop="name" content="<%= @product.name %>" />
- <meta itemprop="description" content="<%= @product.description %>" />
- <meta itemprop="sku" content="<%= @product.sku %>" />
- <!-- Product content -->
-<% end %>
-```
-
-## Performance Standards
-- Implement fragment caching
-- For images please use `spree_image_tag`, `spree_image_url` and `spree_image_path` helpers which automatically serve optimized WEBP images
-- Minimize HTTP requests
-- Implement lazy loading
-
-## Form Standards
-- Use Rails form helpers
-- Implement CSRF protection
-- Add proper validation feedback
-- Handle errors gracefully
-
-## Helper Standards
-- Place helpers in `app/helpers/spree/`
-- Use helpers for view-specific logic
-- Keep helpers simple and testable
-
-## Navigation Standards
-- Implement responsive navigation
-- Use proper ARIA labels
-- Support keyboard navigation
-- Include search functionality
-
-## Cart & Checkout Standards
-- Use AJAX for cart updates
-- Implement guest checkout
-- Handle payment errors gracefully
-- Provide clear progress indicators
-
-## Mobile Standards
-- Mobile-first responsive design
-- Touch-friendly interface elements
-- Optimize for mobile performance
-- Test on multiple device sizes
-
-## Accessibility Standards
-- Include proper ARIA labels
-- Ensure keyboard navigation
-- Maintain color contrast ratios
-- Provide alternative text for images
-
-## Testing Standards
-- Test critical user journeys
-- Use feature specs for integration testing
-- Test responsive behavior
-- Include accessibility testing
-
-```ruby
-# ✅ Storefront feature spec
-require 'spec_helper'
-
-RSpec.feature 'Product browsing', type: :feature, js: true do
- let!(:product) { create(:product, name: 'Test Product') }
-
- scenario 'viewing product details' do
- visit spree.product_path(product)
-
- expect(page).to have_content('Test Product')
- expect(page).to have_button('Add to Cart')
- expect(page).to have_css('[itemtype="http://schema.org/Product"]')
- end
-
- scenario 'adding product to cart' do
- visit spree.product_path(product)
-
- click_button 'Add to Cart'
-
- expect(page).to have_content('Item added to cart')
- expect(page).to have_css('.cart-count', text: '1')
- end
-end
-```
-
-## Translation Files
-- Place storefront translations in `storefront/config/locales/en.yml`
-- Use customer-friendly language
-- Include error messages and validation text
-
-## Security Standards
-- Sanitize user inputs
-- Implement rate limiting for forms
-- Use HTTPS for sensitive operations
-- Validate all form submissions
diff --git a/storefront/.cursor/rules/storefront.mdc b/storefront/.cursor/rules/storefront.mdc
new file mode 100644
index 0000000000..05b259bdc9
--- /dev/null
+++ b/storefront/.cursor/rules/storefront.mdc
@@ -0,0 +1,423 @@
+---
+alwaysApply: true
+---
+
+# Spree Storefront Rules
+
+## Controller Standards
+- Storefront controllers inherit from `Spree::StoreController`
+- Handle customer-facing functionality
+- Implement proper SEO and caching
+- Use secure session handling
+
+```ruby
+# ✅ Storefront controller structure
+class Spree::ProductsController < Spree::StoreController
+ before_action :find_product, only: [:show]
+
+ def index
+ @products = current_store.products.available.includes(:images, :variants)
+ @products = @products.ransack(params[:q]).result if params[:q].present?
+ @products = @products.page(params[:page])
+ end
+
+ def show
+ @variants = @product.variants.includes(:images, :option_values)
+ @product_properties = @product.product_properties.includes(:property)
+ end
+
+ private
+
+ def find_product
+ @product = current_store.products.friendly.find(params[:id])
+ rescue ActiveRecord::RecordNotFound
+ redirect_to products_path, alert: Spree.t('product_not_found')
+ end
+end
+```
+
+## View Standards
+- Use Tailwind CSS for styling
+- Follow responsive design principles
+- Implement proper semantic HTML
+- Include accessibility attributes
+
+```erb
+<!-- ✅ Proper storefront view structure -->
+<article class="product-details" itemscope itemtype="http://schema.org/Product">
+ <header class="product-header">
+ <h1 class="text-3xl font-bold text-gray-900" itemprop="name">
+ <%= @product.name %>
+ </h1>
+
+ <div class="mt-2">
+ <span class="text-2xl font-semibold text-gray-900" itemprop="price">
+ <%= @product.display_price %>
+ </span>
+ </div>
+ </header>
+
+ <div class="product-description mt-6" itemprop="description">
+ <%= simple_format(@product.description) %>
+ </div>
+</article>
+```
+
+## JavaScript & Stimulus
+
+- Try to use Turbo for all AJAX requests
+- Use Stimulus for interactive components that cannot be handled by Turbo
+- Place Stimulus controllers in `app/javascript/controllers/spree/storefront/`
+- Follow progressive enhancement principles
+- Minimize JavaScript dependencies
+
+```javascript
+// ✅ Storefront Stimulus controller
+import { Controller } from "@hotwired/stimulus"
+import { post } from "@rails/request.js"
+
+export default class extends Controller {
+ static targets = ["quantity", "addToCart"]
+ static values = {
+ productId: Number,
+ variantId: Number
+ }
+
+ connect() {
+ this.updateAddToCartState()
+ }
+
+ updateQuantity(event) {
+ const quantity = parseInt(event.target.value)
+ this.updateAddToCartState()
+ }
+
+ async addToCart(event) {
+ event.preventDefault()
+
+ const response = await post('/line_items', {
+ body: {
+ variant_id: this.variantIdValue,
+ quantity: this.quantityTarget.value
+ }
+ })
+
+ if (response.ok) {
+ const data = await response.json
+ this.handleAddToCartResponse(data)
+ }
+ }
+}
+
+## SEO Standards
+- Include proper meta tags
+- Use structured data markup
+- Implement canonical URLs
+- Optimize page titles and descriptions
+
+```erb
+<!-- ✅ SEO meta tags -->
+<% content_for :title, @product.meta_title.presence || @product.name %>
+<% content_for :description, @product.meta_description.presence || truncate(@product.description, length: 160) %>
+
+<%= content_tag :div, itemscope: true, itemtype: "http://schema.org/Product" do %>
+ <meta itemprop="name" content="<%= @product.name %>" />
+ <meta itemprop="description" content="<%= @product.description %>" />
+ <meta itemprop="sku" content="<%= @product.sku %>" />
+ <!-- Product content -->
+<% end %>
+```
+
+## Performance Standards
+- Implement fragment caching
+- For images please use `spree_image_tag`, `spree_image_url` and `spree_image_path` helpers which automatically serve optimized WEBP images
+- Minimize HTTP requests
+- Implement lazy loading
+
+## Form Standards
+- Use Rails form helpers
+- Implement CSRF protection
+- Add proper validation feedback
+- Handle errors gracefully
+
+## Helper Standards
+- Place helpers in `app/helpers/spree/`
+- Use helpers for view-specific logic
+- Keep helpers simple and testable
+
+## Navigation Standards
+- Implement responsive navigation
+- Use proper ARIA labels
+- Support keyboard navigation
+- Include search functionality
+
+## Cart & Checkout Standards
+- Use AJAX for cart updates
+- Implement guest checkout
+- Handle payment errors gracefully
+- Provide clear progress indicators
+
+## Mobile Standards
+- Mobile-first responsive design
+- Touch-friendly interface elements
+- Optimize for mobile performance
+- Test on multiple device sizes
+
+## Accessibility Standards
+- Include proper ARIA labels
+- Ensure keyboard navigation
+- Maintain color contrast ratios
+- Provide alternative text for images
+
+## Testing Standards
+- Test critical user journeys
+- Use feature specs for integration testing
+- Test responsive behavior
+- Include accessibility testing
+
+```ruby
+# ✅ Storefront feature spec
+require 'spec_helper'
+
+RSpec.feature 'Product browsing', type: :feature, js: true do
+ let!(:product) { create(:product, name: 'Test Product') }
+
+ scenario 'viewing product details' do
+ visit spree.product_path(product)
+
+ expect(page).to have_content('Test Product')
+ expect(page).to have_button('Add to Cart')
+ expect(page).to have_css('[itemtype="http://schema.org/Product"]')
+ end
+
+ scenario 'adding product to cart' do
+ visit spree.product_path(product)
+
+ click_button 'Add to Cart'
+
+ expect(page).to have_content('Item added to cart')
+ expect(page).to have_css('.cart-count', text: '1')
+ end
+end
+```
+
+## Translation Files
+- Place storefront translations in `storefront/config/locales/en.yml`
+- Use customer-friendly language
+- Include error messages and validation text
+
+## Security Standards
+- Sanitize user inputs
+- Implement rate limiting for forms
+- Use HTTPS for sensitive operations
+- Validate all form submissions
+
+# Spree Storefront Rules
+
+## Controller Standards
+- Storefront controllers inherit from `Spree::StoreController`
+- Handle customer-facing functionality
+- Implement proper SEO and caching
+- Use secure session handling
+
+```ruby
+# ✅ Storefront controller structure
+class Spree::ProductsController < Spree::StoreController
+ before_action :find_product, only: [:show]
+
+ def index
+ @products = current_store.products.available.includes(:images, :variants)
+ @products = @products.ransack(params[:q]).result if params[:q].present?
+ @products = @products.page(params[:page])
+ end
+
+ def show
+ @variants = @product.variants.includes(:images, :option_values)
+ @product_properties = @product.product_properties.includes(:property)
+ end
+
+ private
+
+ def find_product
+ @product = current_store.products.friendly.find(params[:id])
+ rescue ActiveRecord::RecordNotFound
+ redirect_to products_path, alert: Spree.t('product_not_found')
+ end
+end
+```
+
+## View Standards
+- Use Tailwind CSS for styling
+- Follow responsive design principles
+- Implement proper semantic HTML
+- Include accessibility attributes
+
+```erb
+<!-- ✅ Proper storefront view structure -->
+<article class="product-details" itemscope itemtype="http://schema.org/Product">
+ <header class="product-header">
+ <h1 class="text-3xl font-bold text-gray-900" itemprop="name">
+ <%= @product.name %>
+ </h1>
+
+ <div class="mt-2">
+ <span class="text-2xl font-semibold text-gray-900" itemprop="price">
+ <%= @product.display_price %>
+ </span>
+ </div>
+ </header>
+
+ <div class="product-description mt-6" itemprop="description">
+ <%= simple_format(@product.description) %>
+ </div>
+</article>
+```
+
+## JavaScript & Stimulus
+
+- Try to use Turbo for all AJAX requests
+- Use Stimulus for interactive components that cannot be handled by Turbo
+- Place Stimulus controllers in `app/javascript/controllers/spree/storefront/`
+- Follow progressive enhancement principles
+- Minimize JavaScript dependencies
+
+```javascript
+// ✅ Storefront Stimulus controller
+import { Controller } from "@hotwired/stimulus"
+import { post } from "@rails/request.js"
+
+export default class extends Controller {
+ static targets = ["quantity", "addToCart"]
+ static values = {
+ productId: Number,
+ variantId: Number
+ }
+
+ connect() {
+ this.updateAddToCartState()
+ }
+
+ updateQuantity(event) {
+ const quantity = parseInt(event.target.value)
+ this.updateAddToCartState()
+ }
+
+ async addToCart(event) {
+ event.preventDefault()
+
+ const response = await post('/line_items', {
+ body: {
+ variant_id: this.variantIdValue,
+ quantity: this.quantityTarget.value
+ }
+ })
+
+ if (response.ok) {
+ const data = await response.json
+ this.handleAddToCartResponse(data)
+ }
+ }
+}
+
+## SEO Standards
+- Include proper meta tags
+- Use structured data markup
+- Implement canonical URLs
+- Optimize page titles and descriptions
+
+```erb
+<!-- ✅ SEO meta tags -->
+<% content_for :title, @product.meta_title.presence || @product.name %>
+<% content_for :description, @product.meta_description.presence || truncate(@product.description, length: 160) %>
+
+<%= content_tag :div, itemscope: true, itemtype: "http://schema.org/Product" do %>
+ <meta itemprop="name" content="<%= @product.name %>" />
+ <meta itemprop="description" content="<%= @product.description %>" />
+ <meta itemprop="sku" content="<%= @product.sku %>" />
+ <!-- Product content -->
+<% end %>
+```
+
+## Performance Standards
+- Implement fragment caching
+- For images please use `spree_image_tag`, `spree_image_url` and `spree_image_path` helpers which automatically serve optimized WEBP images
+- Minimize HTTP requests
+- Implement lazy loading
+
+## Form Standards
+- Use Rails form helpers
+- Implement CSRF protection
+- Add proper validation feedback
+- Handle errors gracefully
+
+## Helper Standards
+- Place helpers in `app/helpers/spree/`
+- Use helpers for view-specific logic
+- Keep helpers simple and testable
+
+## Navigation Standards
+- Implement responsive navigation
+- Use proper ARIA labels
+- Support keyboard navigation
+- Include search functionality
+
+## Cart & Checkout Standards
+- Use AJAX for cart updates
+- Implement guest checkout
+- Handle payment errors gracefully
+- Provide clear progress indicators
+
+## Mobile Standards
+- Mobile-first responsive design
+- Touch-friendly interface elements
+- Optimize for mobile performance
+- Test on multiple device sizes
+
+## Accessibility Standards
+- Include proper ARIA labels
+- Ensure keyboard navigation
+- Maintain color contrast ratios
+- Provide alternative text for images
+
+## Testing Standards
+- Test critical user journeys
+- Use feature specs for integration testing
+- Test responsive behavior
+- Include accessibility testing
+
+```ruby
+# ✅ Storefront feature spec
+require 'spec_helper'
+
+RSpec.feature 'Product browsing', type: :feature, js: true do
+ let!(:product) { create(:product, name: 'Test Product') }
+
+ scenario 'viewing product details' do
+ visit spree.product_path(product)
+
+ expect(page).to have_content('Test Product')
+ expect(page).to have_button('Add to Cart')
+ expect(page).to have_css('[itemtype="http://schema.org/Product"]')
+ end
+
+ scenario 'adding product to cart' do
+ visit spree.product_path(product)
+
+ click_button 'Add to Cart'
+
+ expect(page).to have_content('Item added to cart')
+ expect(page).to have_css('.cart-count', text: '1')
+ end
+end
+```
+
+## Translation Files
+- Place storefront translations in `storefront/config/locales/en.yml`
+- Use customer-friendly language
+- Include error messages and validation text
+
+## Security Standards
+- Sanitize user inputs
+- Implement rate limiting for forms
+- Use HTTPS for sensitive operations
+- Validate all form submissions