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

​
Upgrade steps

​
Update gems

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: 
bundle add propshaft

​
Install and run missing migrations

bin/rake spree:install:migrations && bin/rails db:migrate

​
Migrate to Metafields or keep using Product Properties

Spree 5.2 introduces 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: 
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: 
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 --request GET \
      --url 'https://demo.spreecommerce.org/api/v2/storefront/products/1?include=metafields' \
      --header 'Accept: application/vnd.api+json'
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: 
bin/rake db:migrate_policies
This will migrate your current data to the new format.
If you’re using a custom theme, you will need to adjust 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.

​
Migrate Product Details pages to PDP 2.0 with blocks and metafields (Optional)

Only applicable if you’re using spree_storefront gem.
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: 
bin/rake db:migrate_product_details_pages

​
Update Storefront to Tailwind v4 or stay on v3 (Optional)

Only applicable if you’re using spree_storefront gem.
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 
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: 
gem "tailwindcss-rails", "~> 3.3.1" # which transitively pins tailwindcss-ruby to v3
and run: 
bundle update tailwindcss-rails
This will install Tailwind v3 instead of Tailwind v4.