Spree Upgrades

Before writing code

Fetch live docs:

1. Fetch https://spreecommerce.org/docs/developer/upgrades/quickstart for the canonical upgrade flow.
2. Read the release notes for every minor between your current and target versions at https://github.com/spree/spree/releases.
3. Cross-reference the announcement posts for each major (v5.0, v5.2, v5.4).
4. Check the deprecated-gems list — spree_auth_devise, deface, spree_backend are all archived.
5. Inspect your Gemfile + gemfile.lock against the target Spree version's spree.gemspec.

Conceptual Architecture

The Two Upgrade Shapes

What Changed v4 → v5

The biggest single jump in Spree's history:

• Admin rewritten in Tailwind + Hotwire (was Bootstrap + jQuery). All v4 admin customizations break.
• Legacy ERB frontend removed. Sites on spree_frontend need to migrate to the Next.js storefront or spree-rails-storefront.
• Engines consolidated. spree_backend, spree_frontend, spree_storefront_api_v2, spree_platform_api merged into the spree umbrella gem.
• spree_auth_devise deprecated. v5 ships Devise auth in-core; old gem archived Feb 2026.
• Deface deprecated. It only worked on the v4 ERB frontend.
• Metafields, Themes, Page Builder, CSV import/export added as new features.
• API v2 (JSON:API) is still available in v5.0–5.3 in core; extracted to spree_legacy_api_v2 in v5.4+.

What Changed v5.0 → v5.4

Gemfile Pinning Strategy

# Pin per minor for predictability
gem 'spree', '~> 5.4'   # accepts 5.4.0–5.4.99 patches
# Avoid
gem 'spree'             # any 5.x — surprise breakage
gem 'spree', '5.4.2'    # locks you to a patch; misses bug fixes

For extensions:

spec.add_dependency 'spree', '>= 5.4', '< 6.0'

Run bundle update spree to take patch releases.

Decorator Brittleness

Decorators (*_decorator.rb with prepend) are upgrade-fragile. When upgrading:

1. Audit every decorator — does the decorated method still exist? Same signature?
2. Run the test suite after the version bump
3. Watch for NoMethodError in super — the underlying method was renamed
4. Watch for new validations — your decorator may conflict with new core rules

Reduce risk by preferring events and dependencies over decorators (see spree-extensions skill).

Deprecated Gems to Remove

API v2 → v3 Migration

Side-by-side strategy:

1. v5.4+ project includes both /api/v3/ (built-in) and /api/v2/ (via spree_legacy_api_v2)
2. Build new clients on v3
3. Migrate existing clients one surface at a time
4. Monitor v2 traffic; sunset after N weeks of zero usage
5. Eventually remove spree_legacy_api_v2 from Gemfile

Admin Customization Migration

• Deface overrides → translate to partial injection slots OR opt out (often the slot system is sufficient)
• Bootstrap CSS → translate to Tailwind classes (use the Spree v5 admin views as reference)
• Custom admin layouts → re-implement against v5's Tailwind/Hotwire base layout
• jQuery code → port to Stimulus controllers

Storefront Migration

• Legacy ERB frontend → either:
  • Fork spree/storefront (Next.js) and migrate over weeks
  • Use spree-rails-storefront (Tailwind page-builder ERB storefront) for minimal change

Plan as a separate project, not a Gemfile bump.

Implementation Guidance

Pre-Upgrade Audit

Before changing the Gemfile:

1. Inventory decorators — grep -r '_decorator.rb' app/ and grep -r '.prepend(' app/
2. Inventory Deface overrides — grep -r 'Deface::Override' app/
3. Inventory custom admin views — find app/views/spree/admin -name '*.erb'
4. Inventory custom controllers — find app/controllers/spree -name '*.rb'
5. Inventory subscribers — find app/subscribers -name '*.rb'
6. Inventory custom payment methods, calculators, services
7. Map all current Gemfile entries to their v5 fate (kept / removed / replaced)
8. List all third-party Spree extensions — verify each has v5 support

Upgrade Workflow (v5.x to v5.y)

# 1. Branch
git checkout -b upgrade-spree-5.x

# 2. Bump
bundle update spree spree_admin spree_emails

# 3. Run migrations
bin/rails db:migrate

# 4. Run specs
bundle exec rspec

# 5. Smoke test admin + storefront
bin/rails server
# manually browse, place a test order

# 6. Deploy to staging
# run a fuller regression suite

# 7. Deploy to prod

Upgrade Workflow (v4 → v5) — Project-Sized

1. Stand up a parallel v5 environment with same data (use db/structure.sql import + data export)
2. Migrate decorators one model at a time
3. Migrate admin customizations to partial slots / new conventions
4. Choose storefront path — Next.js (highest-fidelity for modern UX) or spree-rails-storefront (least change)
5. Migrate frontend — this is often 50%+ of the project
6. Migrate payment integrations — install v5-compatible gateway gems
7. Cutover plan — data migration, DNS switch, monitoring

Rolling Back

• Always tag the release before deploying
• Database migrations: design backward-compatible (additive only; drops in a later release)
• Rolling deploy with multiple pods lets you halt mid-deploy if alerts fire
• DB rollback is a last resort — bin/rails db:rollback only works if migrations are reversible

Test Coverage as Upgrade Insurance

Before upgrading:

• System specs covering: cart → checkout → order placement
• API specs for every consumer-facing v3 endpoint
• Subscriber specs for each event you handle
• Decorator specs for each model decoration

If coverage is thin, write tests first, then upgrade. The cost of bad coverage during an upgrade is far higher than the cost of writing tests.

Common Upgrade Pitfalls

• Skipping minors — v5.0 → v5.4 in one jump misses the v5.2 generator changes that interact with v5.3 PriceList. Step through.
• Decorator super calls a method that no longer exists — manifests as NoMethodError at runtime, not boot.
• Removed admin views referenced by Deface — Deface silently no-ops; visual regression.
• API v2 client breakage when removing the legacy gem — confirm zero v2 traffic for weeks before removal.
• Payment gateway gem behind on Spree compatibility — verify each gem supports the target Spree before bumping.
• Sidekiq queue names changed — webhook delivery queue renamed in some minor; check release notes.
• **Migratio