Major/New Features

Bootstrap Backend & Frontend

The most visible change will be the use of Bootstrap to replace the previous Skeleton framework. We’ve redesigned the frontend, and backend while keeping much of the previous structure to the site. We hope this will make upgrades slightly easier to port to the new Bootstrap markup. Now that we’ve updated the default css/js framework we’re hoping to begin implementing usability improvements & improved mobile support.

Rails 4.2 Support

We’ve added Rails 4.2 support laying the groundwork for further improvements. Rails 4.2 comes with ActiveJob a background job API, which we will leverage in the future to send long running tasks to Sidekiq, DelayedJob or Resque if you set them up. We’ve also already updated mailers to use the deliver later functionality so your confirmation emails will be sent in the background.

Google Analytics Enhanced Ecommerce

With the change to enhanced ecommerce tracking you should make sure to upgrade your Google Analytics account to Universal Analytics. If you use Spree’s default google analytics implementation you should be fine, but if you’ve customized these make sure to update to Universal Analytics.

Upgrade Tips

First Read Rails 4.2 Release Notes & Upgrade Guide

Release Notes

Upgrade Guide

Spree Upgrade

If you have extensions that your store depends on, you will need to manually verify that each of those extensions work within your 3.0.x store once this upgrade is complete. Typically, extensions that are compatible with this version of Spree will have a 3-0-stable branch.

For this Spree release, you will need to upgrade your Rails version to at least 4.2.0.

gem 'rails', '~> 4.2.0'

For best results, use the 3-0-stable branch from GitHub:

gem 'spree', github: 'spree/spree', branch: '3-0-stable'

Run bundle update spree.

Copy over the migrations from Spree (and any other engine) and run them using these commands:

rake railties:install:migrations
rake db:migrate

Verify that everything is OK. Manually test your store, and make sure it’s performing as normal. Fix any deprecation warnings you see.

Other Gotchas


SSLRequirement controller concern was removed in favor of using Rails built in ForceSSL.

It is recommended that you enable config.force_ssl = true within your production.rb file which will enforce SSL on every page.

If you were previously using ssl_required in any controllers you should now use force_ssl at the controller level if you’re not going to use force_ssl at the application level. This includes if you were previously relying on Spree’s built in use of ssl_required so make sure your checkout process properly handles SSL connections.

PaymentMethods and Trackers are no longer based on environment.

Previously payment methods and google analytics trackers could be assigned an environment, such as, production/staging/development etc.. This is no longer the case. If you previously relied on importing data from production to a development or staging environment you should ensure to sanitize and/or update these credentials to prevent submitting payments or analytics information to your production account credentials.

We recommend that you begin to manage your credentials with environment variables instead.

Noteable Changes

Also please review each of the noteable changes, and ensure your customizations or extensions are not effected. If you are affected by a change, and have any of your own tips please submit a PR to help the next person!

Full Changelog

You can view the full changes using Github Compare.

Noteable Changes

  • Switched to Bootstrap.

    Jeff Dutil & Other Contributors

  • Moved Core’s helpers into Frontend.

    Jeff Dutil

  • Use Google Analytics Enhanced ecommerce.

  • PaymentMethod’s and Tracker’s are no longer based on environment.

    Clarke Brunsdon

  • Removed promo code field from cart page. This prevents issues with promos attempting to be used before the order is ready. e.g. Free Shipping before shipments.

    Jeff Dutil

  • Removed order token usage during guest checkout.

  • Replace outdated Spree::Config[:mails_from] with Spree::Store.current.mail_from_address

  • Moved current_currency helper from Spree::Core::ControllerHelpers::Order to Spree::Core::ControllerHelpers::Store.

  • The line items order population endpoint used to accept a hash, it now accepts an array. When submitting a Post request to /api/line_items you will receive this deprecation warning:

    Ben A. Morgan

    ```text Passing a hash is now deprecated and will be removed in Spree 3.1. It is recommended that you pass it as an array instead.

    New Syntax:

    { “order”: { “line_items”: [ { “variant_id”: 123, “quantity”: 1 }, { “variant_id”: 456, “quantity”: 1 } ] } }

    Old Syntax:

    { “order”: { “line_items”: { “1”: { “variant_id”: 123, “quantity”: 1 }, “2”: { “variant_id”: 123, “quantity”: 1 } } } } ```

  • Enable configuration of Carmen.i18n_backend.locale at seeds.rb

    You can localize the Country and State seed data by adding Carmen configuration to your seeds.rb.
    See example below:

    ```ruby # add Carmen counfiguration with the following 2 lines require ‘carmen’ Carmen.i18n_backend.locale = :ja

    Spree::Core::Engine.load_seed if defined?(Spree::Core) Spree::Auth::Engine.load_seed if defined?(Spree::Auth) ```

    Tomoki Odaka