Releases: spree/spree
Version 4.5.1
Add compatibility for Ruby 3.1 and 3.2
Version 4.5.0
Major features
Spree 4.5 is a technology update that lets you use Spree with the latest version of Ruby and Rails. It also comes with a new set of tools to make it easy to work with Spree as a part of complex projects - Spree CLI and Spree Platform API SDK.
Read our 4.4 to 4.5 Upgrade Doc for how to upgrade your app to the latest version.
Ruby 3 and Rails 7 support
- If using Rails 7 with Spree 4.5, you will need to install libvips on your machine, as Rails 7 uses vips as its default variant processor. You can still use imagemagick, but you’ll need to manually set it in your Rails config.
- Rails 6.0 is no longer supported - if you haven’t already, you’ll need to upgrade to Rails 6.1 or 7.0. The effort to upgrade to Rails 6.1 is relatively low, but brings a lot of improvements around ActiveStorage and handling of CDNs.
V1 API is now extracted into a standalone gem
V1 API is now deprecated and won't be maintained. For new projects, please use V2 Platform API.
If you need the V1 API for existing integrations, it's still available as a standalone gem. Just add the following to your Gemfile:
gem 'spree_api_v1'
Updated admin look and feel
The admin panel got a clean look and minor usability improvements.
New Spree CLI
To help you easily create and manage projects based on Spree and one of the available storefront options, we built a new CLI to guide you through the process. To get started, simply run:
npx @spree/cli new app
Vue Storefront has feature-parity with Rails frontend
While Rails storefront (spree_frontend gem) is still available, we went one step ahead to give you an option to easily get started with a modern PWA storefront. It offers the same features as the Rails storefront, but is based on a modern Vue/Nuxt.js stack which gives a lot of performance benefits. Check out Vue Storefront here.
Related 4.5 Release Docs
For details on changes made to other Spree gems as part of the 4.5.0 release, see the following:
Version 4.3.2
Backport fix for CSRF issue from Spree 4.4.1: https://github.com/spree/spree_backend/releases/tag/v4.4.1
Version 4.2.6
Backport fix for CSRF issue: https://github.com/spree/spree_backend/releases/tag/v4.4.1
Version 4.4.0
In this latest release, following the low-code and no-code trends, Spree becomes even more composable by introducing Webhooks and Platform API as well as more customizable with Metadata. That translates into easier integration opportunities and shorter delivery timelines. On the business front, this latest Spree version introduces downloadable Digital Product sales (documents, ebooks, images, audio tracks, video files) and Wishlists making it an even more universally useful open-source eCommerce platform.
Digital Product downloads
With the new Digital Products downloads functionality you may use Spree to sell the following example product and file types:
- E-BOOK file types: mobi, epub, pdf
- POSTER file types: jpg, png
- IMAGE file types: png in 3 resolutions
- DOCUMENT TEMPLATE file type: PDF, Word
- LARGER DOCUMENTS file type: ZIP
- DATASETS file type: CSV, TXT
You may also sell any variations of the above download types such as e-tickets, e-courses, music and videos files, and just about anything else that comes in a digital format.
This feature also allows you to attach files to physical products, such as users manuals, vouchers, or exclusive digital artworks associated with the product.
Digital products are created the same way as physical products (for the most part), with the only difference being that when a customer has only digital products in their cart, the delivery step of the checkout will be skipped entirely. After purchase, the customer will be able to download their files.
As with any Spree feature, Digital Products may be managed through the admin panel and are fully supported with API endpoints in Storefront and Platform API collections.
Wishlists for upselling
A Wishlist allows registered users to create personalized collections of products they want to buy and then save them for future reference in their user account. Wishlists represent your customers’ interest in the product without an immediate intent to purchase or if the product is currently out of stock.
Wishlists provide you with a wide range of marketing opportunities, from identifying user trends and tracking marketing campaign effectiveness to planning new email or PPC campaigns centered around the items commonly included within users’ wishlists.
As with any Spree feature, Wishlists are fully supported with API endpoints in Storefront and Platform API collections.
Webhooks for no-code integrations
Anyone may use Webhooks as a no-code way to connect Spree with 3rd party solutions. For instance, an order webhook may send an updated, up-to-date list of orders every time someone makes a purchase. Getting this information using API would require sending periodic API requests to the “Return a list of Orders” endpoint. On the other hand, a properly set up webhook would feed the relevant order information only when the order list changes triggered by a new purchase.
Webhooks are one of the many ways that apps can communicate with one another by sending automated messages or information. A webhook delivers data to other applications as it happens, meaning you get data immediately and without asking for it.
So the main upside of using webhooks is that applications don’t have to make periodic calls to APIs while waiting for changes. Instead, webhooks will notify your application on a specific endpoint informing them that something interesting has happened.
There are many integration platforms as a service (iPaaS), such as Zapier, Celigo, Workato, Mulesoft Anypoint, Automate.io, which allow for no-code system integrations and composing event-triggered workflows.
With Webhooks you may use these platforms to easily configure tens of connections between systems and compose software solutions yourself without doing any development work whatsoever. Pretty great, huh?
For example, Zapier allows you to create automated workflows by connecting over 3000 applications without any coding involved:
- when a new order is placed, notify me with Slack, send it to Hubspot and Quickbooks,
- when a new user signs up for an account, add their email to Mailchimp and send a welcome email from the CEO,
- when a new payment is made in Stripe, generate a receipt in Quickbooks and send it to the customer by email,
- when a new shipment is delivered, ask this user for a review,
Metadata for low-code platform customization
Every eCommerce platform is a bit different but customizing it with code changes and database schema adjustments not only requires engineering know-how and skills but also introduces complexity and possibly bugs, complicates future upgrade paths, and generally is not recommended.
With Spree 4.4 you may leverage the Metadata functionality to easily add custom attributes on the fly for Products, Variants, Taxons, Orders, Carts, or Users without any code or database changes. Meta fields may be either public or private and all are easily accessible using Spree APIs.
For example:
- an eCommerce platform combining content and commerce may store related blog post identifiers for each product
- a B2B store may need to distinguish user types
- any store may need to allow for additional information for orders for analytics purposes
Platform API for app to app integrations
If the low-code Metadata method is not sufficient to customize your Spree platform, you may need to consider using Platform API to create an external app talking to Spree Platform API.
Platform API also comes in handy when connecting Spree with 3rd party systems which may consume its API responses.
Platform API is useful for application to application integrations based on oAuth 2.0 authentication and permissions.
Platform API is built on the same foundations and technology as Storefront API, which means JSON API format, Swagger (Open API) documentation, and oAuth 2.0 authentication.
Platform API is the biggest and most robust API for Spree with the largest number of API endpoints to cover all features available in the Admin Panel plus much more.
This API completely replaces API v1 which will be extracted from Spree in 5.0.
Admin dashboard experience improvements
Spree 4.4 comes equipped with a much smoother dashboard user experience thanks to Hotwire (Turbo and Stimulus).
With Turbo you get the speed of a single-page web application without having to write any JavaScript. Stimulus pairs beautifully with Turbo to provide a complete solution for fast, compelling applications with a minimal amount of effort.
As DHH has said: “This is how we’re building Basecamp 4. This is how we built HEY. Now it’s going to be the default answer to JavaScript in Rails 7 together with the new import-map approach. All the missing pages are being printed.”
That being said, we’re excited to present you with this huge Spree 4.4 release and are already working on Spree 5.0 running on Rails 7 with all its goodies included.
Full changelog
https://github.com/spree/spree/blob/main/CHANGELOG.md
Upgrade guide
Version 4.4.0 RC2
Full Changelog: v4.4.0.rc1...v4.4.0.rc2
Version 4.3.1
This patch release contains bug fixes backported from the main branch. We'd like to thank all the contributors who made this happen 👍
- Fix for null values error when running migrations @mdavo6 759a342
- Fix created_at null error running CreateSpreeProductsStores migration @albertoalmagro 446bbe8
Version 4.4.0 RC1
What's Changed
- [SD-1358] As a Admin I should not be able to permanently delete Store by @damianlegawiec in #11315
- [SD-1429] Rename Spree CMD to Spree CLI and make it a dependency of spree gem by @pmilewski in #11307
- [SD-1388] Add specs for MenuItemSerializer and CmsSectionSerializer by @v10110 in #11278
- Start v4.4 development 🚀 by @damianlegawiec in #11341
- SD-1465 - 500 error on re-using identical data as a soft deleted store by @kgorazd in #11343
- Move storefront serializer specs to one location. by @MatthewKennedy in #11340
- Move Spree Seeds into their own services to allow easier customization by @damianlegawiec in #11344
- [SD-1438] Remove API -> API v1 redirect by @pmilewski in #11306
- Remove APIs' magic 404 logic by @damianlegawiec in #11345
- Use bang methods in seeds to avoid silently failing by @damianlegawiec in #11347
- Introduce
NumberIdentifier
concern by @damianlegawiec in #11346 - Introduce
Base#spree_base_uniqueness_scope
andUniqueName
concern by @damianlegawiec in #11348 - Introduce
Spree::Oauth
models by @damianlegawiec in #11349 - Enable polymoprhic resource owners for OAuth Access Tokens by @damianlegawiec in #11350
- Simplify and fix handling polymorphic Oauth Token's resource owners by @damianlegawiec in #11351
- Utilize
ActiveRecord#insert_all
to cut seed loading time by @damianlegawiec in #11352 - Squash all Spree 4.3 migrations into one by @damianlegawiec in #11353
- [SD-1413] - Move Wishlist into Spree Core by @MatthewKennedy in #11308
- Move frontend preferences out of spree core by @damianlegawiec in #11354
- Extract
spree_frontend
into a separate repo by @damianlegawiec in #11358 - Move backend configuration to spree_backend gem by @damianlegawiec in #11359
- Extract backend into a separate repo by @damianlegawiec in #11360
- [SD-1467] - Add Platform API For Wishlists by @MatthewKennedy in #11355
- [SD-1468] Fix payment example json in API docs by @v10110 in #11357
- Add missing brackets in API docs by @v10110 in #11361
- Fixes in Storefront API Docs. by @MatthewKennedy in #11366
- [SD-1455] OpenAPI docs for Cart attributes are missing example values and response example by @pmilewski in #11321
- Add missing brackets in API docs by @v10110 in #11368
- Improve StoreFront API Docs by @MatthewKennedy in #11367
- [SD-1478] - Remove duplication of User object living under the Account model. by @MatthewKennedy in #11370
- [SD-1476] - Add OpenAPI documentation to Platform API for CMS Pages and CMS Sections by @MatthewKennedy in #11364
- [SD-1461] fix money_methods for ruby version < 2.7 by @KacperMekarski in #11373
- Fix/spree sample load task by @damianlegawiec in #11374
- Platform API - Orders by @damianlegawiec in #11376
- Set Circle CI parallelism to 3 by @damianlegawiec in #11378
- Platform - Line Items API by @damianlegawiec in #11380
- Platform - Adjustments API by @damianlegawiec in #11381
- Platform API - Shipping Categories by @damianlegawiec in #11382
- Improve Platform API Orders documentation by @damianlegawiec in #11383
- fix build.sh: 28: cd: can't cd to api by @letseeqiji in #11384
- Introduce Spree.admin_user_class by @damianlegawiec in #11385
- JSON:API Spec Compliance Fixes For Platform API by @MatthewKennedy in #11388
- Added Platform API Orders Approve and Cancel endpoints by @damianlegawiec in #11386
- More Flexible Auto Gen Swagger Docs by @MatthewKennedy in #11390
- Improve Documentation Storefront. by @MatthewKennedy in #11389
- Remove eslint/stylelint leftovers by @damianlegawiec in #11391
- Simplify permission checks for Platform API by @damianlegawiec in #11394
- Improve checking user performance in Platform API by @damianlegawiec in #11396
- [SD-1422] - Migrate Spree Digital into Spree Core by @MatthewKennedy in #11369
- Set Platform API request schemas to internal. by @MatthewKennedy in #11397
- Fix for Digital Downloads by @MatthewKennedy in #11401
- FIX: digital_link update cache after authorized download. by @MatthewKennedy in #11402
- Use i18n-tasks to manage translations in API by @MatthewKennedy in #11403
- Fix Failing Specs For Missing i18n-tasks Gem by @MatthewKennedy in #11404
- Rails 7 preparation work by @damianlegawiec in #11406
- Add scope examples to Authorisation API Docs. by @MatthewKennedy in #11365
- Add client_credentials to authentication docs. by @MatthewKennedy in #11409
- Stop using currency/checkout zone/default country preferences by @damianlegawiec in #11408
- Added Platform Variants API for fetching Variants by @damianlegawiec in #11413
- Added Platform Payments API for fetching Payments by @damianlegawiec in #11414
- Replace rspec-activemodel-mocks in specs with FactoryBot by @KacperMekarski in #11407
- SD-1445 feature implement Spree Webhooks by @sebastian-palma in #11399
- Change Image content type validation to use
Active Storage Validations
gem by @KacperMekarski in #11419 - Add promotion_categories to Platform API v2 by @MatthewKennedy in #11423
- Add Webhooks::Subscriber check_uri_path validation by @sebastian-palma in #11418
- Remove ActiveSupport#run_load_hooks calls by @damianlegawiec in #11424
- SD-1446 use pg_search for full text search of porduct names when pg_search is available. by @KacperMekarski in #11416
- Use JSON coder for typed_store in Spree::Store.settings by @MatthewKennedy in #11425
- Remove integer casting for IDs by @damianlegawiec in #11426
- Fixed filtering of Line Items in Platform API by @damianlegawiec in #11429
- Added tests for Variants filtering in Platform API by @damianlegawiec in #11430
- fix migration with stock_item_by_loc_var_id_deleted_at index by @KacperMekarski in #11431
- Use past tense for Webhook event names by @damianlegawiec in #11432
- Add create/index/show webhooks subscribers endpoints by @sebastian-palma in #11428
- Update swagger_helper.rb by @patrykwielgosz in #11427
- Platform API - Shipments pt 1 by @damianlegawiec in #11393
- [SD-1505] - Add Shipping Methods To Platform API v2 by @MatthewKennedy in #11433
- Use Rails way of managing has_many association through API requests. by @MatthewKennedy in #11435
- Track and record Webhook Events by @sebastian-palma in #11434
- Fix/shipping method serializer attributes by @MatthewKennedy in #11441
- [SD-1501] - Fix 500 Error on Adjustments Serializer. by @MatthewKennedy in #11440
- Add Webhooks Events list endpoint by @sebastian-palma in #11438
- [SD-1474] - Fix User Create & Update actions on Platform API by @MatthewKennedy in #11442
- [SD-1517] Emit order.shipped when all order shipments were shipped. by @sebastian-palma in #11443
- Improve Swagger Docs Generation by @MatthewKennedy in #11445
- Clean Up Platform API Controllers by @MatthewKennedy in #11448
- Add placeholder Serializers for Webhooks. by @MatthewKennedy in #11449
- Add Codespell Github Workflow by @MatthewKennedy in #11450
...
Version 4.3.0
Major new features
Modular API-first architecture
We've completely decoupled Storefront (spree_frontend
), Admin Panel (spree_backend
) and extracted transactional Emails into their own gem (spree_emails
). Thanks to this you can:
- Easily replace Storefront and Admin Panel with your own
- Use the version of Storefront and Admin you like, so you can update the Spree Core and API without the need to upgrade these two
- Easily replace standard transactional emails with Klaviyo, Mailchimp, and other 3rd parties
We're also making Spree less dependent on the Rails framework while supporting Rails 5.2, 6.0, and 6.1 on Ruby 2 and 3.
Next.js Commerce integration
Next.js Commerce is an all-in-one React starter kit for high-performance eCommerce sites. With the new API-first architecture it was very easy to connect Spree APIs via Spree SDK to the new blazing fast react storefront.
BTW we have more storefront integrations news lined up in the coming weeks!
Pages & Navigation CMS
This release gives Spree users a powerful content management system that goes beyond creating basic text pages.
Spree Content Management System allows you to create:
Home Pages
- Create many home pages per store.
- Each home page is unique by language.
- Add multiple sections to each home page.
Standard Pages
- Standard pages consist of WYSIWYG text editor content.
- Each standard page has a slug that is unique to the store.
- Each page is assigned a language.
Feature pages
- Feature pages use page sections.
- Each feature page has a slug that is unique to the store.
- Feature pages are assigned a language.
Menus
Users can create navigation menus for their Spree stores.
Each menu is unique by language and location within the store and has the following features:
- Menus contain many menu items. Each menu item can link to a product, taxon, URLs, home page, or CMS page.
- Menu items can be nested inside other menu items creating nested links.
- Menus can have container items used to organize links within the menu.
- Menu items can have images allowing you to create promotions within the main menu.
Platform API Developer Preview
A new set of fast and modern APIs for application to application integrations based on oAuth 2.0 authentication and permissions.
This API completely replaces API v1 which will be extracted from Spree core in 5.0. Platform API is built on the same foundations and technology as Storefront API which means JSON API format, Swagger (Open API) documentation, and oAuth 2.0 authentication.
Platform API is the biggest and most robust API for Spree with the biggest number of API endpoints to cover all features
available in Admin Panel plus more.
Advanced Product Filters
We've greatly expanded the product filters feature. Now you can:
- Filter by Properties - you can set which Properties should be filterable and the ones you choose will be visible and supported in the Storefront and API
- Filter by Option Types - you can set which Option Types should be filterable and the ones you choose will be visible and supported in the Storefront and API
- Storefront API will also return available filters for products in the Product API endpoint
This way you can create new custom filters in the Admin UI from Option Types or Properties and the system will do the rest work for you.
Installation
Upgrade
Follow 4.2 to 4.3 upgrade guide
Noteworthy changes
Please review each of the noteworthy changes to ensure your customizations or extensions are not affected. If you are affected by a change and have any suggestions, please submit a PR to help the next person!
API
-
Added caching to API v2 serialized increasing API responsiveness 3-5 times Damian Legawiec
This also includes new confirmation option
Spree::Api::Config[:api_v2_cache_ttl]
for the cache expiration TTL. Default value is3600
(1 hour). Cache also auto-expires when cachd record is updated, more on this topic: https://github.com/jsonapi-serializer/jsonapi-serializer#caching -
Added universal collection caching for Platform/Storefront API responses #11245
-
Increased API v2 per page limit to 500 #11257
-
Multi-Store Storefront Products API returns Products from the current Store Damian Legawiec
-
Multi-Store Storefront Account Orders API returns Orders from the current Store Damian Legawiec
-
Multi-Store Storefront Order Status API returns Order from the current Store Damian Legawiec
-
Multi-Store Return only Store resources in Storefront API, Platform API, and Storefront UI #11126 (damianlegawiec)
-
Fix API V2 Platform products by price sorting #11276 (szymoniwacz)
-
Platform API Classifications endpoints #11195 (damianlegawiec)
-
Platform API - Products endpoints #11194 (damianlegawiec)
-
Added API endpoint for changing cart currency #11331 (rafalcymerys)
-
Storefront API Products endpoint returns filter options with products #11318 (rafalcymerys)
-
Storefront API Adresses endpoint - display addresses from countries supported in the current store #11271 (v10110)
-
Add public preferences to payment methods in Storefront API Checkout endpoints #11301 (damianlegawiec)
-
Storefront Countries API returns all countries on a single page #11289 (damianlegawiec)
-
Fix API V2 Platform products by price sorting #11276 (szymoniwacz)
-
Storefront API / Platform API - allow to dynamically specify image dimensions/quality in API URLs to get the transformed image #11264 (damianlegawiec)
Core
-
Multi-Store
Order#available_payment_methods
by default will return only Payment Methods available in Order's Store Damian LegawiecPassing
store
argument to that method will result in deprecation warning -
Multi-Store Deprecated
Store.current
in favour ofStores::FindCurrent
Damian LegawiecAlso, this finder class can be replaced by custom one by setting
Spree::Dependencies.current_store_finder = YourCustomStoreFinder
in
config/initializers/spree.rb
(please check documentation) -
Multi-Store
Product
,Promotion
andPaymentMethod
models require at least oneStore
associated Damian Legawiec -
Multi-Store
Promotion
is now associated to multipleStore
records viaStorePromotion
model Damian LegawiecYou can disable this behaviour by setting:
Spree::Config[:disable_store_presence_validation] = true
in your
config/initializers/spree.rb
file -
Multi-Store
Store Credit
model is now associated withStore
Szymon Iwacz -
Taxon
model now requiresTaxonomy
presence and thatTaxonymy
needs to match Taxon's Parent (if present) Damian Legawiec -
Transactional emails were extracted into a separate gem called
spree_emails
Damian Legawiec -
Replaced
twitter_cldr
gem with much smallervalidates_zipcode
Damian Kaczmarczyk -
Removed
premailer-rails
gem dependency Damian Legawiec -
Removed
rails
dependency - only require Rails gems that we really use Damian Legawiec -
Removed
responders
dependency Damian Legawiec -
Removed
sprockets
dependency Damian Legawiec -
Moved
spree.js
file to frontend/backend Damian Legawiec -
Moved
polyfill.min.js
andfetch.umd.js
files to frontend Damian Legawiec -
Moved
cleave.js
file to frontend/backend Damian Legawiec -
Moved
jquery.payment.js
file to frontend [Damian Legawiec](3605d67...
Vesion 4.3.0.rc2
- Fix API V2 Platform products by price sorting #11276 (szymoniwacz)
- Fix api v2 products available on specs #11273 (szymoniwacz)
- Updated Extension Generator for Spree 4.3 #11272 (damianlegawiec)
- Add CMS Pages to Storefront API docs #11268 (MatthewKennedy)
- Add primary variant to storefront product serializer #11267 (szymoniwacz)
- Storefront product sort #11266 (szymoniwacz)
- Add product scopes #11265 (szymoniwacz)
- [SD-1414] Update api platform specs and swagger #11263 (szymoniwacz)
- Allow frontend flash alert to span full width of screen. #11262 (MatthewKennedy)
- Move #ensure_current_store to core based controller helper #11261 (MatthewKennedy)
- Update Seed Data. #11260 (MatthewKennedy)
- Allow footer columns to stack neatly if more than 4 used. #11259 (MatthewKennedy)
- [SD-1400] Search properties by filterable status #11258 (v10110)
- Increased API v2 per page limit to 500 #11257 (damianlegawiec)
- Fix typo - (parent) in location_after_destroy. #11256 (MatthewKennedy)
- Use dash (-) for id target elements on sliders, not backslash (/) #11255 (MatthewKennedy)
- Fix typos #11254 (vfonic)
- Extracted gatsby guides to https://github.com/spree/spree-guides-gatsby #11253 (damianlegawiec)
- Redirect developer documentation to the new dev-docs site #11252 (damianlegawiec)
- Replace links to guides.spreecommerce.org to dev-docs.spreecommerce.org #11250 (damianlegawiec)
- Rescue load error on dummy app generation #11247 (szymoniwacz)
- Added universal collection caching for Platform/Storefront API #11245 (damianlegawiec)
- [SD-1339] - Change the taxon autocomplete to use Platform API. #11244 (MatthewKennedy)
- Fix create StoreProducts migration #11241 (damianlegawiec)
- Fixed: do not call OrderMailer directly and use Order#deliver_order_c… #11239 (damianlegawiec)
- Add locale for model cms_pages and cms_sections #11238 (MatthewKennedy)
- Add text foreground and background color options to WYSIWYG editor. #11237 (MatthewKennedy)
- Tidy up serializer -name serializer for polymorphic associations. #11235 (MatthewKennedy)
- Fix Polymorphic Association to Linked Resources via STI Page Types #11234 (MatthewKennedy)
- Fix validation errors for Swagger Open API #11228 (MatthewKennedy)
- [SD-1266] Fix lifetime stats display #11208 (szymoniwacz)
- Migrate User Roles code from Spree Auth Devise to Spree Core #11108 (damianlegawiec)