Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Improve upgrading experience
Damian Legawieca96ffad0843b
diff --git a/docs/developer/upgrades/5.4-to-5.5.mdx b/docs/developer/upgrades/5.4-to-5.5.mdxindex 16d22f87c6..3d7231fa58 100644--- a/docs/developer/upgrades/5.4-to-5.5.mdx+++ b/docs/developer/upgrades/5.4-to-5.5.mdx@@ -12,12 +12,11 @@ The upgrade is usually completed in five steps:1. **Update the Ruby gems** which power Spree API2. **Run database migrations** — to migrate your existing schema to the new version3. **Run data backfills** — to move your existing data into the new schema and power new features-4. **Update Spree SDK NPM package** - to use new API features and avoid breaking changes-5. Apply optional configuration and review behavior changes — to take advantage of new features and avoid surprises+4. Apply optional configuration and review behavior changes — to take advantage of new features and avoid surprises## How to upgrade-For applications created via `create-spree-app` command we greatly recommend using the Spree CLI to perform the upgrade. It provides a guided experience with prompts and handles all three steps for you. If you prefer to run the commands manually or not using docker for local development, you can follow the "Without Spree CLI" path.+For applications created via `create-spree-app` command we greatly recommend using the Spree CLI to perform the upgrade. It provides a guided experience with prompts and handles the first three steps for you. If you prefer to run the commands manually or not using docker for local development, you can follow the "Without Spree CLI" path.<CodeGroup>@@ -95,6 +94,16 @@ The task is fully idempotent — safe to re-run if it fails partway, and a no-opUntil `spree:channels:upgrade` runs, every product has `store_id IS NULL` and is invisible to `Product.for_store(store)`. The admin product list, storefront catalog, and search indexer all return empty. Run the task immediately after `db:migrate`.</Warning>+### Reindex products++The last step rebuilds the search index against the configured [search provider](/developer/core-concepts/search-filtering):++```bash+bin/rake spree:search:reindex+```++This is a no-op on the default Database provider (there is no external index to maintain). For Meilisearch — or any other external search provider — it is required, and it must run **after** the Channels upgrade: products only become visible to `Product.for_store` once they have a `store_id`, so reindexing before the channels step would index zero products. The manifest orders the steps accordingly.+#### Multi-store catalogsIf you have products attached to multiple stores via the legacy `spree_products_stores` join, the `populate_publications` task picks **one** "home" store per product and creates publications on every store's default channel. The `spree_products_stores` table is **kept** as legacy compat surface — the upcoming `spree_multi_store` extension restores the full `Product has_many :stores` association on top of it.@@ -110,6 +119,25 @@ For single-store deployments this is invisible; you can move on without touchingOrders modified after the upgrade auto-set `channel_id` via the model's `before_validation :ensure_channel_presence` callback, so `backfill_order_channel_ids` is only strictly required for orders that aren't touched again post-upgrade — but running it at upgrade time avoids surprises later. The legacy `channel` string column is **kept** on `spree_orders` and ignored by ActiveRecord (`Spree::Order` declares it in `ignored_columns`). It will be dropped in a later Spree release once everyone has had a chance to run the backfill.+## Update the Spree SDK++Spree 5.5 ships alongside `@spree/sdk` 1.1. The backend upgrade never touches your frontend source — bump the SDK in every JavaScript consumer of the Store API and take it through your normal PR/CI cycle:++```bash+# create-spree-app projects: the Next.js storefront+cd apps/storefront+npm install @spree/sdk@^1.1+```++If you maintain a separate storefront repo or other integrations, repeat there. The `spree upgrade` command detects the conventional `apps/storefront` and reminds you with the currently-declared version in its "Next steps" panel.++| Spree backend | `@spree/sdk` |+|---|---|+| 5.4 | 1.0.x |+| 5.5 | 1.1+ |++The SDK bump pairs with one storefront code change in this release: the [payment method `type` shorthand](#payment-method-type-on-the-wire-is-now-a-shorthand-not-a-rails-class-name) — update your gateway map when you bump.+## Required post-upgrade configuration`bin/rake spree:upgrade` doesn't touch your job-runner config — every app uses a different scheduler, so this one is on you.diff --git a/packages/cli/src/commands/upgrade.ts b/packages/cli/src/commands/upgrade.tsindex 58dec8c417..b62f461616 100644--- a/packages/cli/src/commands/upgrade.ts+++ b/packages/cli/src/commands/upgrade.ts@@ -1,3 +1,5 @@+import fs from 'node:fs'+import path from 'node:path'import * as p from '@clack/prompts'import type { Command } from 'commander'import { execa } from 'execa'@@ -31,7 +33,7 @@ export function registerUpgradeCommand(program: Command): void {await runRakeUpgrade(ctx.projectDir, flags)- if (!flags.plan) printPostUpgradeReminder()+ if (!flags.plan) printPostUpgradeReminder(ctx.projectDir)})}@@ -119,13 +121,34 @@ async function runRakeUpgrade(await dockerComposeExec(['bin/rake', 'spree:upgrade'], projectDir, { env })}-function printPostUpgradeReminder(): void {+// The backend upgrade never touches frontend source — SDK bumps go through+// the consumer's own PR/CI cycle. But we can detect the conventional+// create-spree-app storefront and tell the operator exactly what to bump.+export function sdkAdvisory(projectDir: string): string {+ const generic = 'Update @spree/sdk in any storefront or integration consuming the API'+ const pkgPath = path.join(projectDir, 'apps', 'storefront', 'package.json')+ if (!fs.existsSync(pkgPath)) return generic+ try {+ const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')) as {+ dependencies?: Record<string, string>+ devDependencies?: Record<string, string>+ }+ const declared = pkg.dependencies?.['@spree/sdk'] ?? pkg.devDependencies?.['@spree/sdk']+ if (!declared) return generic+ return `Update @spree/sdk in apps/storefront (currently ${declared}) to the release matching the new Spree version`+ } catch {+ return generic+ }+}++function printPostUpgradeReminder(projectDir: string): void {p.note([`The manifest only ran ${pc.bold('rake-automatable')} steps.`,'',"Don't forget the manual parts from the upgrade doc:",` ${pc.dim('- Schedule Spree::StockReservations::ExpireJob (cron)')}`,+ ` ${pc.dim(`- ${sdkAdvisory(projectDir)}`)}`,` ${pc.dim('- Review behavior changes (cart, availability, payment-method types)')}`,` ${pc.dim('- Audit custom decorators against renamed APIs')}`,'',diff --git a/packages/cli/tests/upgrade.test.ts b/packages/cli/tests/upgrade.test.tsnew file mode 100644index 0000000000..58ab8789ef--- /dev/null+++ b/packages/cli/tests/upgrade.test.ts@@ -0,0 +1,68 @@+import fs from 'node:fs'+import os from 'node:os'+import path from 'node:path'+import { afterEach, describe, expect, it } from 'vitest'+import { sdkAdvisory } from '../src/commands/upgrade'++describe('sdkAdvisory', () => {+ const tempDirs: string[] = []++ function makeTempDir(): string {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'spree-cli-upgrade-test-'))+ tempDirs.push(dir)+ return dir+ }++ afterEach(() => {+ for (const dir of tempDirs) {+ fs.rmSync(dir, { recursive: true, force: true })+ }+ tempDirs.length = 0+ })++ function writeStorefrontPackageJson(dir: string, pkg: object): void {+ const storefrontDir = path.join(dir, 'apps', 'storefront')+ fs.mkdirSync(storefrontDir, { recursive: true })+ fs.writeFileSync(path.join(storefrontDir, 'package.json'), JSON.stringify(pkg))+ }++ it('names the declared @spree/sdk version when the storefront uses it', () => {+ const dir = makeTempDir()+ writeStorefrontPackageJson(dir, { dependencies: { '@spree/sdk': '^1.0.3' } })++ expect(sdkAdvisory(dir)).toBe(+ 'Update @spree/sdk in apps/storefront (currently ^1.0.3) to the release matching the new Spree version',+ )+ })++ it('finds @spree/sdk in devDependencies too', () => {+ const dir = makeTempDir()+ writeStorefrontPackageJson(dir, { devDependencies: { '@spree/sdk': '1.1.0' } })++ expect(sdkAdvisory(dir)).toContain('currently 1.1.0')+ })++ it('falls back to generic advice without a storefront', () => {+ const dir = makeTempDir()++ expect(sdkAdvisory(dir)).toBe(+ 'Update @spree/sdk in any storefront or integration consuming the API',+ )+ })++ it('falls back to generic advice when the storefront does not use the SDK', () => {+ const dir = makeTempDir()+ writeStorefrontPackageJson(dir, { dependencies: { next: '^15.0.0' } })++ expect(sdkAdvisory(dir)).toContain('any storefront or integration')+ })++ it('falls back to generic advice on unparseable package.json', () => {+ const dir = makeTempDir()+ const storefrontDir = path.join(dir, 'apps', 'storefront')+ fs.mkdirSync(storefrontDir, { recursive: true })+ fs.writeFileSync(path.join(storefrontDir, 'package.json'), '{ not json')++ expect(sdkAdvisory(dir)).toContain('any storefront or integration')+ })+})