@spree/docs 0.1.0

package/dist/developer/upgrades/4.6-to-4.7.md

@@ -0,0 +1,39 @@
+---
+title: 4.6 to 4.7
+description: This guide covers upgrading a 4.6 Spree application to Spree 4.7.
+---
+
+> **WARNING:** We recommend [upgrading straight to 4.8](4.x-to-4.8), as we improved how we handle translations in 4.8.
+> This also means easier database migration, especially if you have a big product catalog.
+
+> **NOTE:** If you're on an older version than 4.6 please follow previous upgrade guides and perform those upgrades incrementally
+> 
+> 1. [upgrade 4.3 to 4.4](4.3-to-4.4)
+> 2. [upgrade 4.4 to 4.5](4.4-to-4.5)
+> 3. [upgrade 4.5 to 4.6](4.5-to-4.6)
+
+## Upgrade steps
+
+### 1. Update gems
+
+```bash
+bundle update
+```
+
+### 2. Install and run missing migrations
+
+```bash
+bin/rake spree:install:migrations && bin/rails db:migrate
+```
+
+### 3. (Optional) Re-Run Spree Frontend install
+
+If you're using [Spree Frontend gem](https://github.com/spree/spree_rails_frontend), run the following additional commands to get everything set up correctly with the updated gems:
+
+```bash
+bin/rails g spree:frontend:install
+```
+
+## Read the release notes
+
+For information about changes contained within this release, please read the [Spree 4.7.0 Release Notes.](https://github.com/spree/spree/releases/tag/v4.7.0)

package/dist/developer/upgrades/4.8-to-4.9.md

@@ -0,0 +1,24 @@
+---
+title: Upgrading to Spree 4.9
+description: This guide covers upgrading a Spree 4.8 application to Spree 4.9.
+---
+
+> **INFO:** Before proceeding to upgrade, please ensure you're at [Spree 4.8](/developer/upgrades/4.x-to-4.8)
+
+## Upgrade steps
+
+### 1. Update gems
+
+```bash
+bundle update
+```
+
+### 2. Install and run missing migrations
+
+```bash
+bin/rake spree:install:migrations && bin/rails db:migrate
+```
+
+## Read the release notes
+
+For information about changes contained within this release, please read the [Spree 4.9.0 Release Notes.](https://github.com/orgs/spree/discussions/12123)

package/dist/developer/upgrades/4.9-to-4.10.md

@@ -0,0 +1,24 @@
+---
+title: Upgrading to Spree 4.10
+description: This guide covers upgrading a Spree 4.9 application to Spree 4.10.
+---
+
+> **INFO:** Before proceeding to upgrade, please ensure you're at [Spree 4.9](/developer/upgrades/4.8-to-4.9)
+
+## Upgrade steps
+
+### 1. Update gems
+
+```bash
+bundle update
+```
+
+### 2. Install and run missing migrations
+
+```bash
+bin/rake spree:install:migrations && bin/rails db:migrate
+```
+
+## Read the release notes
+
+For information about changes contained within this release, please read the [Spree 4.10.0 Release Notes.](https://github.com/orgs/spree/discussions/12154)

package/dist/developer/upgrades/4.x-to-4.8.md

@@ -0,0 +1,52 @@
+---
+title: Upgrading to Spree 4.8
+description: This guide covers upgrading a Spree 4 application to Spree 4.8.
+---
+
+> **INFO:** Before proceeding to upgrade, please ensure you're at Spree 4.4 or later and Rails 6.1 or later.
+
+## Upgrade steps
+
+### 1. Update gems
+
+```bash
+bundle update
+```
+
+### 2. Install and run missing migrations
+
+```bash
+bin/rake spree:install:migrations && bin/rails db:migrate
+```
+
+### 3. (Optional) Install importmap-rails gem
+
+We've switched to using [importmap-rails](https://github.com/rails/importmap-rails) for asset management. If you're using the `spree_backend` or `spree_frontend` gem, you'll need to install the `importmap-rails` gem.
+
+```bash
+bundle add importmap-rails
+```
+
+and run generators:
+
+```bash
+bin/rails importmap:install && bin/rails turbo:install && bin/rails stimulus:install
+```
+
+You can also remove the `jsbundling-rails` gem from your `Gemfile`:
+
+```bash
+bundle remove jsbundling-rails
+```
+
+### 4. (Optional) Apply fix when upgrading from 4.5/4.6/4.7
+
+If you're upgrading from 4.5/4.6/4.7, you need to set this configuration in your `config/initializers/spree.rb`:
+
+```ruby
+Spree::RuntimeConfig.always_use_translations = true
+```
+
+## Read the release notes
+
+For information about changes contained within this release, please read the [Spree 4.8.0 Release Notes.](https://github.com/spree/spree/releases/tag/v4.8.0)

package/dist/developer/upgrades/5.0-to-5.1.md

@@ -0,0 +1,28 @@
+---
+title: Upgrading to Spree 5.1
+description: This guide covers upgrading a Spree 5.0 application to Spree 5.1.
+---
+
+> **INFO:** Before proceeding to upgrade, please ensure you're at [Spree 5.0](/developer/upgrades/4.10-to-5.0)
+
+## Upgrade steps
+
+### 1. Update gems
+
+```bash
+bundle update
+```
+
+### 2. Install and run missing migrations
+
+```bash
+bin/rake spree:install:migrations && bin/rails db:migrate
+```
+
+### 3. Migrate admin user accounts to the new system
+
+Spree 5.1 introduces a new better way of managing admin user accounts. To ensure your existing admin user accounts are migrated to the new system, run the following command:
+
+```bash
+bin/rake db:migrate_admin_users_to_role_users
+```

package/dist/developer/upgrades/5.1-to-5.2.md

@@ -0,0 +1,127 @@
+---
+title: Upgrading to Spree 5.2
+description: This guide covers upgrading a Spree 5.1 application to Spree 5.2.
+---
+
+> **INFO:** Before proceeding to upgrade, please ensure you're at [Spree 5.1](/developer/upgrades/5.0-to-5.1)
+
+## Upgrade steps
+
+### Update gems
+
+  ```bash
+  bundle update
+  ```
+
+### Install `propshaft` gem
+
+Spree 5.2 does not rely on `sprockets` gem anymore. You can either add `sprockets` to your `Gemfile` or move to `propshaft` gem (recommended).
+
+Propshaft is the new default asset pipeline for Rails 7+ applications. It's more performant and has better support for modern browsers.
+
+Please run the following command to install `propshaft` gem:
+
+  ```bash
+  bundle add propshaft
+  ```
+
+### Install and run missing migrations
+
+```bash
+bin/rake spree:install:migrations && bin/rails db:migrate
+```
+
+### Migrate to Metafields or keep using Product Properties
+
+Spree 5.2 introduces [Metafields](/developer/core-concepts/metafields), which are a new way to store additional information about an object. Previously, we used Product Properties to enrich products. Metafields are more powerful, more flexible and can be attached to any object not just products.
+
+However we now that properties were available in Spree since it's beginning. So we decided to keep them for backward compatibility until Spree 6.0 to give you time to migrate to metafields.
+
+To keep using Product Properties, you will need to set a configuration flag in your `config/initializers/spree.rb` file:
+
+  ```bash
+  Spree.config do |config|
+    config.product_properties_enabled = true
+  end
+  ```
+
+You can still use metafields, along side properties.
+
+To migrate to metafields, you will need to run the following command:
+
+  ```bash
+  bin/rake db:migrate_product_properties_to_metafields
+  ```
+
+This will migrate your current data to the new format.
+
+Remember that you will need to update your API calls to fetch metafields instead of properties, eg.
+
+  ```curl
+  curl --request GET \
+        --url 'https://demo.spreecommerce.org/api/v2/storefront/products/1?include=metafields' \
+        --header 'Accept: application/vnd.api+json'
+  ```
+
+### Migrate Product Details pages to PDP 2.0 with blocks and metafields
+
+Spree 5.2 greatly enhances the product details page management in page builder with block support and metafields. To ensure your existing product details pages are migrated to the new system, run the following command:
+
+  ```bash
+  bin/rake db:migrate_product_details_pages
+  ```
+
+This works great with our default storefront theme. If you're using a custom theme, you will need to adjust your templates.
+
+### Migrate store policies
+
+Spree 5.2 introduces more flexible way to manage store policies (eg. terms of service, privacy policy, returns policy, shipping policy).
+
+Previously they were just attributes (rich text fields) on the Store model. Now they are stored in the new Policy model.
+
+To migrate to the new system, you will need to run the following command:
+
+  ```bash
+  bin/rake db:migrate_policies
+  ```
+
+This will migrate your current data to the new format. 
+
+> **WARNING:** If you're using a custom theme, you will need to adjust [app/views/spree/checkout/_footer.html.erb](https://github.com/spree/spree/blob/main/storefront/app/views/spree/checkout/_footer.html.erb) template to be able to manage checkout footer links which was also expanded (now you can link to Pages, Policies, URLs and more).
+> 
+>   `current_store.policies` won't work anymore, you will need to use `current_store.links` instead.
+
+### Update Storefront to Tailwind v4 or stay on v3
+
+Spree 5.2 introduces Tailwind v4 support for the Storefront. Tailwind v4 is a major upgrade from Tailwind v3.
+
+#### Option A: Update to Tailwind v4
+
+Running `bundle update` previously installed Tailwind v4. You only need to run
+
+  ```bash
+  bin/rails g spree:storefront:install
+  ```
+
+This will:
+
+1. Overwrite `config/tailwind.config.js` file with the new Tailwind v4 configuration.
+2. Add `app/assets/tailwind/application.css` file with the new Tailwind v4 styles. If you modified `app/assets/stylesheets/application.tailwind.css` file, you will need to merge your changes with the new one.
+
+#### Option B: Stay on Tailwind v3
+
+You can stay on Tailwind v3 by running the following command:
+
+Add these line to your `Gemfile`:
+
+  ```ruby
+  gem "tailwindcss-rails", "~> 3.3.1" # which transitively pins tailwindcss-ruby to v3
+  ```
+
+and run:
+
+  ```bash
+  bundle update tailwindcss-rails
+  ```
+
+This will install Tailwind v3 instead of Tailwind v4.

package/dist/developer/upgrades/5.2-to-5.3.md

@@ -0,0 +1,338 @@
+---
+title: Upgrading to Spree 5.3
+description: This guide covers upgrading a Spree 5.2 application to Spree 5.3.
+---
+
+> **INFO:** Before proceeding to upgrade, please ensure you're at [Spree 5.2](/developer/upgrades/5.1-to-5.2)
+
+## Upgrade steps
+
+### Update gems
+
+  ```bash
+  bundle update
+  ```
+
+### Fetch and run missing migrations
+
+```bash
+bin/rake spree:install:migrations && bin/rails db:migrate
+```
+
+This will setup new database schema for the new features in Spree 5.3 like Price Lists and Customer Groups.
+
+### Re-run Admin Panel Install Generator
+
+Admin Panel was completely rewritten to use Tailwind v4 so you need to re-run the install generator to setup Tailwind and remove any Dart Sass related files.
+
+  ```bash
+  bin/rails g spree:admin:install
+  ```
+
+This will also modify your `Procfile.dev` file to include the new Tailwind CSS watch task instead of the old Dart Sass watch task.
+
+#### Add listen gem to Gemfile
+
+You also need to add `listen` gem to your Gemfile in the development group, unless you already have it.
+
+  ```ruby
+  group :development do
+    gem 'listen', '>= 3.0'
+  end
+  ```
+
+### Run counter cache rake tasks
+
+Spree 5.3 introduces counter caches for products, taxons and variants. You need to run the following rake tasks to populate the counter caches:
+
+  ```bash
+  bin/rake spree:products:reset_counter_caches
+  bin/rake spree:taxons:reset_counter_caches
+  bin/rake spree:variants:reset_counter_caches
+  ```
+
+This will greatly improve the performance of your application by avoiding N+1 queries.
+
+> **WARNING:** You will need to run this rake task locally and on your production environment to ensure that the counter caches are populated correctly.
+
+### Generate product metrics
+
+Spree 5.3 introduces product metrics for products. You need to run the following rake task to populate the product metrics:
+
+  ```bash
+  bin/rake spree:products:populate_metrics
+  ```
+
+This will populate the product metrics for all products in your database. Product metrics are used to sort products by best selling scope.
+
+> **WARNING:** You will need to run this rake task locally and on your production environment to ensure that the product metrics are populated correctly.
+
+This rake task will enqueue background jobs to populate the product metrics for all products in your database so you need to make sure that your background jobs are configured correctly.
+
+### Replace `auto_strip_attributes` gem usage
+
+`auto_strip_attributes` gem [was removed from Spree](https://github.com/spree/spree/pull/13462) due to bugs and conflicts with translations feature. Also it's not required anymore as built-in Rails `normalizes` provides the same feature without an additional depepdency. 
+
+If you used `auto_stripe_attributes` in your application, you will need to change it to `normalizez`, eg.
+
+Replace
+
+```ruby
+auto_strip_attributes :name
+```
+
+With:
+
+```ruby
+normalizes :name, with: ->(value) { value&.to_s&.squish&.presence }
+```
+
+### Update Storefront to Tailwind v4 (Optional)
+
+> **INFO:** This is optional if you're not using the `spree_storefront` gem.
+
+Spree 5.3 requires Tailwind v4 as it's also used now for the Admin panel so you need to update your Storefront to Tailwind v4 as well.
+
+If you didn't update your Storefront to Tailwind v4 in the previous upgrade guide, you need to do it now.
+
+Running `bundle update` previously installed Tailwind v4. You only need to run
+
+  ```bash
+  bin/rails g spree:storefront:install
+  ```
+
+This will:
+
+1. Overwrite `config/tailwind.config.js` file with the new Tailwind v4 configuration.
+2. Add `app/assets/tailwind/application.css` file with the new Tailwind v4 styles. If you modified `app/assets/stylesheets/application.tailwind.css` file, you will need to merge your changes with the new one.
+
+### Update Storefront to use `pagy` instead of `kaminari` (Optional)
+
+> **INFO:** This is optional if you're not using the `spree_storefront` gem.
+
+Spree 5.3 introduces [pagy](https://ddnexus.github.io/pagy/) as the default pagination gem. Pagy is a faster and more memory-efficient pagination gem than Kaminari. This works automatically for the API and Admin panel.
+
+For Storefront, you need to either update your theme (if you're not using the default theme) or set `use_kaminari_pagination` preference to `true` in your `config/initializers/spree.rb` file.
+
+#### Products infinite scroll fix
+
+Please replace the contents of your `show_more_button.html.erb` with the following code:
+
+```erb
+<% if storefront_pagy&.next %>
+  <%= turbo_frame_tag "next_page", src: url_for(params.to_unsafe_h.merge(page: storefront_pagy.next, format: :turbo_stream)), class: "block relative w-full", data: { controller: "infinite-scroll", infinite_scroll_offset_value: "1350px" }, loading: "lazy" do %>
+    <span class="flex justify-center gap-2 items-center py-4 left-0 w-full h-full">
+      <%= render 'spree/shared/icons/spinner' %>
+      <%= Spree.t(:loading) %>...
+    </span>
+  <% end %>
+<% end %>
+```
+
+#### Posts pagination
+
+In the following files:
+
+* `page_sections/_post_grid.html.erb`
+* `posts/_pagination.html.erb`
+
+Replace this line:
+
+```erb
+<%= paginate @posts, theme: 'storefront', outer_window: 1, inner_window: 2 %>
+```
+
+with this line:
+
+```erb
+<%= render 'spree/shared/pagination' %>
+```
+
+
+### Include Page Builder factories (Optional)
+
+Page Builder was extracted to a separate gem (`spree_page_builder`) so you need to include the Page Builder factories in your test suite if you were using them in your tests
+
+Add this line to your `spec_helper.rb` file:
+
+  ```ruby
+  require 'spree/page_builder/testing_support/factories'
+  ```
+
+## Updating Spree Extensions
+
+If you maintain a Spree extension, the following changes may be required to ensure compatibility with Spree 5.3.
+
+### Admin Controller Changes
+
+#### Use `prepend_before_action` for filters that modify `params[:q]`
+
+In Spree 5.3, the `ResourceController#load_resource` before_action calls `collection` which builds the search query using `search_params`. If your extension uses before_actions to load data needed for filtering (e.g., loading a vendor to filter products), you must use `prepend_before_action` to ensure your filter runs before `load_resource`.
+
+**Before (Spree 5.2):**
+
+```ruby
+module MyExtension
+  module Admin
+    module ProductsControllerDecorator
+      def self.prepended(base)
+        base.before_action :load_vendor, only: :index
+      end
+    end
+  end
+end
+```
+
+**After (Spree 5.3):**
+
+```ruby
+module MyExtension
+  module Admin
+    module ProductsControllerDecorator
+      def self.prepended(base)
+        base.prepend_before_action :load_vendor, only: :index
+      end
+    end
+  end
+end
+```
+
+#### Replace `assign_extra_collection_params` with `search_params` override
+
+The `assign_extra_collection_params` method is no longer used in Spree 5.3. Instead, override the `search_params` method to add custom Ransack filters.
+
+**Before (Spree 5.2):**
+
+```ruby
+def assign_extra_collection_params
+  params[:q][:vendor_id_eq] = @vendor.id if @vendor.present?
+end
+```
+
+**After (Spree 5.3):**
+
+```ruby
+def search_params
+  result = super
+  result[:vendor_id_eq] = @vendor.id if @vendor.present?
+  result
+end
+```
+
+#### Date range filtering changes
+
+The base `ResourceController#search_params` now processes date range params (`created_at_gt`, `created_at_lt`, etc.) and converts them to `beginning_of_day`. If you need `end_of_day` for `_lt` params, override `search_params` with custom handling:
+
+```ruby
+def search_params
+  params[:q] ||= {}
+  params[:q][:s] ||= collection_default_sort if collection_default_sort.present?
+
+  if params[:q][:created_at_gt].present?
+    params[:q][:created_at_gt] = parse_date_param(params[:q][:created_at_gt])
+  end
+
+  if params[:q][:created_at_lt].present?
+    params[:q][:created_at_lt] = parse_date_param(params[:q][:created_at_lt])&.end_of_day
+  end
+
+  params[:q]
+end
+```
+
+### Admin Tables API
+
+The old filter partial system (`Spree.admin.partials.*_filters`) has been replaced with built-in filtering in the Tables API. Remove any filter partials and configure filtering directly in table column definitions.
+
+**Before (Spree 5.2):**
+
+```ruby
+Spree.admin.partials.orders_filters << 'spree/admin/orders/vendor_filter'
+```
+
+**After (Spree 5.3):**
+
+```ruby
+Spree.admin.tables.orders.add :vendor,
+  label: :vendor,
+  type: :custom,
+  filterable: true,
+  filter_type: :select,
+  ransack_attribute: :vendor_id_eq,
+  value_options: -> { Spree::Vendor.pluck(:name, :id) },
+  partial: 'spree/admin/orders/table/vendor_column'
+```
+
+See the [Admin Tables documentation](/developer/admin/tables) for more details.
+
+### Tailwind CSS v4 Migration
+
+If your extension includes admin views with CSS classes, update Bootstrap utility classes to Tailwind v4:
+
+| Bootstrap | Tailwind v4 |
+|-----------|-------------|
+| `d-flex` | `flex` |
+| `d-none` | `hidden` |
+| `text-muted` | `text-gray-500` |
+| `ml-2`, `mr-2` | `ms-2`, `me-2` |
+| `pl-2`, `pr-2` | `ps-2`, `pe-2` |
+| `font-weight-bold` | `font-bold` |
+
+### Stimulus Tabs Controller
+
+If your extension uses Bootstrap tabs, migrate to the Stimulus tabs controller:
+
+**Before (Bootstrap):**
+
+```erb
+<ul class="nav nav-tabs">
+  <li class="nav-item">
+    <a class="nav-link active" data-toggle="tab" href="#tab1">Tab 1</a>
+  </li>
+</ul>
+<div class="tab-content">
+  <div class="tab-pane active" id="tab1">Content</div>
+</div>
+```
+
+**After (Stimulus):**
+
+```erb
+<div data-controller="tabs">
+  <ul class="nav nav-pills mb-4" role="tablist">
+    <li class="nav-item" role="presentation">
+      <a class="nav-link active" data-tabs-target="tab" data-action="click->tabs#select" role="tab">Tab 1</a>
+    </li>
+  </ul>
+  <div data-tabs-target="panel" role="tabpanel" class="animate-fade-in">Content</div>
+</div>
+```
+
+### Progress Bar Component
+
+The `progress_bar_component` signature has changed:
+
+**Before (Spree 5.2):**
+
+```erb
+<%= progress_bar_component(value, 0, 100) %>
+```
+
+**After (Spree 5.3):**
+
+```erb
+<%= progress_bar_component(value, min: 0, max: 100) %>
+```
+
+### Table Column Visibility
+
+All table columns now require `default: true` to be visible by default:
+
+```ruby
+Spree.admin.tables.vendors.add :name,
+  label: :name,
+  type: :string,
+  sortable: true,
+  default: true,  # Required for column to be visible
+  position: 10
+```