Upgrading to Spree 5.0
This guide covers upgrading a Spree 4.10 application 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
1. Remove old frontend/backend Spree gems
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. Update main Spree gem
2. Install and run missing migrations
2. Install and run missing migrations
3. Add new Spree gems
3. Add new Spree gems
And run the following generators:
4. Migrate from Spree Auth Devise gem
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:
Create Spree::User model:
Add the following code to your Spree::User model:
In you config/initializers/spree.rb file, add the following code:
Now run the new authentication generator to connect your Spree::User model to Spree:
And if you’re using the default spree storefront, please run the following generator:
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.
Read the release notes
For information about changes contained within this release, please read the Spree 5.0 Release Notes.