Upgrading to Spree 5.0

Before proceeding to upgrade, please ensure you’re at Spree 4.10

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, you’re in more control of the authentication now)
Completely new Admin Dashboard (old customizations unfortunately won’t work)
Completely new native Stripe extension
Spree 5.1 includes native Gift Cards, Admin Staff Management & Invitations
Spree 5.2 includes Metafields, CSV Importer, Store Policies & Newsletter Subscribers
Spree 5.3 includes new highly flexible Pricing Engine for B2B, Wholesale and Volume discounts, Events & Subscribers Engine, Webhooks, Customer Groups
Spree 5.4 includes new API v3 and Next.js Storefront

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

bundle update spree

3. Install and run missing migrations

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

4. Add new Spree gems

bundle add spree_admin spree_stripe

And run the following generators:

bin/rails g spree:admin:install
bin/rails g spree_stripe:install

5. 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 log in to the admin panel and storefront using your existing users.

6. Migrate data to the new format

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.

Deployment

Upgrading

Contributing

Security

Prerequisites

Upgrade steps

1. Remove old frontend/backend Spree gems

2. Update main Spree gem

3. Install and run missing migrations

4. Add new Spree gems

5. Migrate from Spree Auth Devise gem

6. Migrate data to the new format

Taxons

Read the release notes

​Prerequisites

​Upgrade steps

​1. Remove old frontend/backend Spree gems

​2. Update main Spree gem

​3. Install and run missing migrations

​4. Add new Spree gems

​5. Migrate from Spree Auth Devise gem

​6. Migrate data to the new format

​Taxons

​Read the release notes

Prerequisites

Upgrade steps

1. Remove old frontend/backend Spree gems

2. Update main Spree gem

3. Install and run missing migrations

4. Add new Spree gems

5. Migrate from Spree Auth Devise gem

6. Migrate data to the new format

Taxons

Read the release notes