Skip to main content
Before proceeding to upgrade, please ensure you’re at Spree 5.2

​
Upgrade steps

​
Update gems

bundle update

​
Fetch and run missing migrations

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. 
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. 
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: 
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.
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: 
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.
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.

​
Update Storefront to Tailwind v4 (Optional)

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 
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)

This is optional if you’re not using the spree_storefront gem.
Spree 5.3 introduces pagy as the default pagination gem. Pagy is a faster and more memory efficient pagination gem than kaminari. This works automatically for 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 contents of your show_more_button.html.erb with the following code: 
<% 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 following files:
  • page_sections/_post_grid.html.erb
  • posts/_pagination.html.erb
replace this line: 
<%= paginate @posts, theme: 'storefront', outer_window: 1, inner_window: 2 %>
with this line: 
<%= 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: 
require 'spree/page_builder/testing_support/factories'