Skip to main content
Before proceeding to upgrade, please ensure you’re at Spree 4.10
This guide is a work in progress. If you find any issues, please report them. If you want to contribute to this guide, please click “Suggest edits” at the bottom of this page. Thank you!
Spree 5.0 is a major upgrade that introduces many breaking changes. The major changes are:
  • Dropped support for Rails < 7.2
  • Dropped support for Spree Auth Devise gem (now using Devise gem directly via generator)
  • Completely new modern mobile-friendly Storefront (old customizations won’t work)
  • Completely new Admin Dashboard (old customizations won’t work)
  • Completely new native Stripe extension

​
Prerequisites

Before upgrading, please ensure you have the following prerequisites:

​
Upgrade steps

bundle remove spree_auth_devise spree_backend spree_frontend
Remove any code referencing Spree::Backend, Spree::Fronted or Spree::Auth from your application, especially from config/initializers/spree.rb.
bundle update spree

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

bundle add spree_storefront spree_admin spree_stripe
And run the following generators:
bin/rails g spree:storefront:install
bin/rails g spree:admin:install
bin/rails g spree_stripe:install
If you previously used the spree_auth_devise gem, you will need to run some commands to create User and connect it to Spree. We don’t use the spree_auth_devise gem anymore to allow you more control over the authentication and access to all Devise options directly in your application.First, install Devise and run the Devise generator:
bundle add devise
bin/rails g devise:install
Create Spree::User model:
mkdir -p app/models/spree && touch app/models/spree/user.rb
Add the following code to your Spree::User model:
module Spree
  class User < ApplicationRecord
    devise :database_authenticatable # if you want to use the database_authenticatable feature
    devise :recoverable # if you want to use the recoverable feature
    devise :registerable # if you want to use the registerable feature
    devise :confirmable # if you want to use the confirmable feature
    devise :validatable # if you want to use the validatable feature

    devise :rememberable, :trackable, :encryptable, encryptor: 'authlogic_sha512'

    acts_as_paranoid
  end
end
In you config/initializers/spree.rb file, add the following code:
Spree.user_class = "Spree::User"
Now run the new authentication generator to connect your Spree::User model to Spree:
bin/rails g spree:authentication:devise
And if you’re using the default spree storefront, please run the following generator:
bin/rails g spree:storefront:devise
This will add devise routes and create controllers for the storefront.And that’s it! You can now login to the admin panel and storefront using your existing users.
In Spree 5 we changed a bit of the data in some models so you will need to run these commands to fix it:

​
Taxons

Spree::Taxon.all.each { |t| t.set_pretty_name; t.save }

​
Read the release notes

For information about changes contained within this release, please read the Spree 5.0 Release Notes.
⌘I