Upgrading to Spree 5.0

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:

Ruby 3.2 or later
Rails 7.2 - Upgrade guide for Rails 7.2

Upgrade steps

1. Remove old frontend/backend Spree gems

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.

2. Update main Spree gem

2. Install and run missing migrations

3. Add new Spree gems

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

4. Migrate from Spree Auth Devise gem

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.

5. Migrate data to the new format

Read the release notes

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

Getting started

Customizing Spree

Use Cases

Deployment

Upgrading

Contributing

Security

Advanced

Prerequisites

Upgrade steps

Taxons

Read the release notes

Getting started

Customizing Spree

Use Cases

Deployment

Upgrading

Contributing

Security

Advanced

​Prerequisites

​Upgrade steps

​Read the release notes

Prerequisites

Upgrade steps

Read the release notes