Skip to content

armgit / spree

Public Imported from GitHub
0

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.

CLI: Merged spree update into spree upgrade (#14828)

Damian Legawiecf61ff68db21d
diff --git a/.changeset/unified-spree-upgrade.md b/.changeset/unified-spree-upgrade.md
new file mode 100644
index 0000000000..0596e39d11
--- /dev/null
+++ b/.changeset/unified-spree-upgrade.md
@@ -0,0 +1,6 @@
+---
+"@spree/cli": minor
+"create-spree-app": patch
+---
+
+Merged `spree update` into `spree upgrade`, which now upgrades both prebuilt-image and ejected projects and also updates the `@spree/*` packages of the project root and the dashboard apps. `spree update` keeps working for one release with a deprecation warning. New projects get an `upgrade` script instead of `update`.
diff --git a/docs/developer/cli/quickstart.mdx b/docs/developer/cli/quickstart.mdx
index 94dfb5dd70..20d8123a0d 100644
--- a/docs/developer/cli/quickstart.mdx
+++ b/docs/developer/cli/quickstart.mdx
@@ -76,14 +76,6 @@ spree restart
Not appropriate for Gemfile changes (use `spree bundle install`, then Ctrl+C and re-run `spree dev`), Dockerfile / `.ruby-version` changes (use `spree build`), or compose file changes (Ctrl+C and re-run `spree dev`).
-### `spree update`
-
-Pull the latest Spree Docker image and recreate containers. Migrations run automatically on startup.
-
-```bash
-spree update
-```
-
### `spree build`
Rebuild the dev image after Dockerfile or `.ruby-version` changes. Only relevant after `spree eject`.
@@ -100,17 +92,29 @@ spree build --yes # Skip confirmation prompts (for CI)
### `spree upgrade`
-Walk a Spree version upgrade end-to-end inside the dev stack. Runs `bundle update`, applies pending migrations, then walks the version-specific data backfills from the upgrade manifest.
+Upgrade your project to the latest Spree release in one go. It works for both kinds of project:
+
+1. **Update the server**
+ - On a project that runs the prebuilt image, it pulls the latest Spree image and recreates the containers. Database migrations run as the containers start.
+ - On an [ejected](#spree-eject) project, it updates the Spree gems with `bundle update`, applies pending migrations, and restarts the app so it loads the new gems.
+2. **Run data backfills** — the version-specific steps from the upgrade manifest that convert existing records.
+3. **Update the `@spree/*` packages** — `@spree/cli` in the project root, and the dashboard packages and Admin SDK in `apps/dashboard` and `apps/seller-dashboard`. Each package moves to the newest release its declared range in `package.json` allows, the same way `bundle update` respects your `Gemfile`. To move to a new major version, change the range in `package.json` first.
```bash
-spree upgrade # Detect target, run the full sequence interactively
-spree upgrade --plan # Print the plan without executing (DRY_RUN=1)
-spree upgrade --to 5.5 # Cap the walk at a specific target version
-spree upgrade --step <id> # Re-run a single step idempotently (skips bundle + migrate)
-spree upgrade --yes # Skip the per-step prompts
+spree upgrade # Run every step, asking before each one
+spree upgrade --plan # List the data backfills without running anything
+spree upgrade --to 6.1 # Set the target version for the data backfills
+spree upgrade --step <id> # Re-run a single data backfill (runs nothing else)
+spree upgrade --yes # Skip the prompts
```
-Production upgrades only need the third stage — `bundle install` and `db:migrate` happen in your deploy pipeline. The CLI runs all three for local development. See [Upgrades](/developer/upgrades) for the manual production path.
+Your storefront is your own code, so `spree upgrade` does not change it — it tells you which `@spree/sdk` version to move to.
+
+Production upgrades only need the data backfills — installing gems and migrating happen in your deploy pipeline. See [Upgrades](/developer/upgrades) for the manual production path.
+
+<Note>
+`spree update` is the old name for this command. It still works, prints a deprecation warning, and will be removed in a future release.
+</Note>
### `spree eject`
@@ -204,7 +208,7 @@ spree encryption init # Add ACTIVE_RECORD_ENCRYPTION_* keys to the pr
spree encryption init --print # Print a fresh set without writing anything (e.g. for your hosting provider)
```
-It never overwrites keys `.env` already sets, and there is no `--force`: changing the keys makes data encrypted with them unreadable. Afterwards, recreate the containers so they load the new `.env` (`spree update`, or `spree dev` for an ejected project — `spree restart` keeps the old environment), and back the keys up in your secret manager.
+It never overwrites keys `.env` already sets, and there is no `--force`: changing the keys makes data encrypted with them unreadable. Afterwards, recreate the containers so they load the new `.env` (`spree dev` — `spree restart` keeps the old environment), and back the keys up in your secret manager.
### `spree api`
diff --git a/docs/developer/create-spree-app/quickstart.mdx b/docs/developer/create-spree-app/quickstart.mdx
index 77411f809d..e2d5e9af48 100644
--- a/docs/developer/create-spree-app/quickstart.mdx
+++ b/docs/developer/create-spree-app/quickstart.mdx
@@ -115,7 +115,7 @@ The project includes [@spree/cli](/developer/cli/quickstart) for managing your S
|---------|-------------|
| `spree dev` | Run the app in the foreground — streams logs, Ctrl+C stops it. First run completes setup automatically; co-runs the Admin Dashboard dev server when `apps/dashboard` exists |
| `spree stop` | Stop backend services |
-| `spree update` | Pull latest Spree image and restart (runs migrations automatically) |
+| `spree upgrade` | Upgrade Spree — the server, database and `@spree/*` packages |
| `spree eject` | Switch from prebuilt image to building from `server/` |
| `spree add dashboard` | Add the Admin Dashboard to an existing project, to customize it |
| `spree add seller-dashboard` | Add the marketplace seller panel to an existing project |
@@ -152,10 +152,10 @@ Open [http://localhost:3001](http://localhost:3001) to see your store.
To update to the latest Spree version:
```bash
-spree update
+spree upgrade
```
-This pulls the latest Docker image and recreates the containers. The entrypoint automatically runs database migrations.
+This updates the server (the Docker image, or the Spree gems on an ejected project), runs database migrations and data backfills, and updates the `@spree/*` packages of the project and its dashboard apps. See [`spree upgrade`](/developer/cli/quickstart#spree-upgrade) for details.
To pin a specific version, edit `SPREE_VERSION_TAG` in `.env`:
diff --git a/docs/developer/upgrades/5.6-to-6.0.mdx b/docs/developer/upgrades/5.6-to-6.0.mdx
index 3c66163858..cd9e92a151 100644
--- a/docs/developer/upgrades/5.6-to-6.0.mdx
+++ b/docs/developer/upgrades/5.6-to-6.0.mdx
@@ -236,7 +236,7 @@ bin/rails db:encryption:init # prints a set; put it in env vars or encrypted
</CodeGroup>
-Recreate the containers so they pick up the new `.env` (`spree update`, or `spree dev` for an ejected project — `spree restart` keeps the old environment). Set the keys on your production host **before** deploying, and store them in your secret manager.
+Recreate the containers so they pick up the new `.env` (`spree dev` — `spree restart` keeps the old environment). Set the keys on your production host **before** deploying, and store them in your secret manager.
<Warning>
Never change or lose the keys once data is encrypted — the encrypted records become unreadable.
diff --git a/docs/developer/upgrades/quickstart.mdx b/docs/developer/upgrades/quickstart.mdx
index f009294403..15730bc69c 100644
--- a/docs/developer/upgrades/quickstart.mdx
+++ b/docs/developer/upgrades/quickstart.mdx
@@ -9,6 +9,38 @@ The upgrade process is fairly easy and well described. Of course, it all boils d
We strongly advise upgrading Spree incrementally, rather than in one big go.
+## How to upgrade
+
+An upgrade updates the server, migrates the database, runs the version's data backfills, and updates the `@spree/*` packages of your dashboard apps. Always read the guide for the version you're moving to first — it lists the behavior changes to review.
+
+<Tabs>
+ <Tab title="Spree CLI">
+ ```bash
+ spree upgrade
+ ```
+
+ One command for every project: it pulls the new image, or updates the Spree gems on an [ejected](/developer/cli/quickstart#spree-eject) project, then runs migrations, data backfills and the package updates. See [`spree upgrade`](/developer/cli/quickstart#spree-upgrade) for its options.
+ </Tab>
+ <Tab title="Without CLI">
+ Run from the project root:
+
+ ```bash
+ cd server
+ bundle update $(bundle list --name-only | grep ^spree)
+ bin/rails spree:install:migrations db:migrate
+ bin/rails spree:upgrade
+ cd ..
+
+ # The project root and each dashboard app have their own package.json
+ pnpm update "@spree/*"
+ (cd apps/dashboard && pnpm update "@spree/*")
+ (cd apps/seller-dashboard && pnpm update "@spree/*")
+ ```
+
+ On npm or Yarn, run `npm update` or `yarn upgrade` instead, naming each `@spree/*` package from that `package.json` (they do not accept the `"@spree/*"` pattern).
+ </Tab>
+</Tabs>
+
## Support
If you're stuck and would want to get some professional help, you can [contact us directly](https://spreecommerce.org/contact/) and request a quote for our consulting services.
diff --git a/packages/cli/README.md b/packages/cli/README.md
index a21c5fa426..1e0bb4cef8 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -17,7 +17,7 @@ Run from your Spree project directory:
|---------|-------------|
| `spree dev` | Run the app in the foreground — streams logs, Ctrl+C stops it. First run completes setup automatically; co-runs the Admin Dashboard dev server when `apps/dashboard` exists |
| `spree stop` | Stop backend services |
-| `spree update` | Pull the latest Spree image and restart (runs migrations automatically) |
+| `spree upgrade` | Upgrade Spree — the server (image or gems), migrations, data backfills and `@spree/*` packages |
| `spree eject` | Switch from the prebuilt image to building from `backend/` |
| `spree add dashboard` | Add the Admin Dashboard to an existing project, to customize it |
| `spree add seller-dashboard` | Add the marketplace seller panel to an existing project |
diff --git a/packages/cli/src/commands/add.ts b/packages/cli/src/commands/add.ts
index dee9c255e4..24e3f62342 100644
--- a/packages/cli/src/commands/add.ts
+++ b/packages/cli/src/commands/add.ts
@@ -204,7 +204,7 @@ function resolveBundledTemplate(app: AppSpec): string {
* Vite config runs the same generator, with the same extensions, without
* starting a server, so that first start finds nothing to change.
*/
-async function generateRouteTree(appDir: string): Promise<void> {
+export async function generateRouteTree(appDir: string): Promise<void> {
// Best effort: the dev server generates the file on start regardless.
await execa(
'node',
diff --git a/packages/cli/src/commands/encryption.ts b/packages/cli/src/commands/encryption.ts
index 8168f35aa7..23fee879eb 100644
--- a/packages/cli/src/commands/encryption.ts
+++ b/packages/cli/src/commands/encryption.ts
@@ -86,7 +86,7 @@ export function initEncryption(projectDir: string): void {
p.note(
[
- `1. Recreate the containers to load the new .env: ${pc.cyan(ejected ? 'spree dev' : 'spree update')}`,
+ `1. Recreate the containers to load the new .env: ${pc.cyan('spree dev')}`,
` (${pc.cyan('spree restart')} keeps the old environment).`,
'2. Back up the three values in your secret manager —',
' losing them makes encrypted data unreadable.',
diff --git a/packages/cli/src/commands/update.ts b/packages/cli/src/commands/update.ts
deleted file mode 100644
index cbc21ac21f..0000000000
--- a/packages/cli/src/commands/update.ts
+++ /dev/null
@@ -1,27 +0,0 @@
-import * as p from '@clack/prompts'
-import type { Command } from 'commander'
-import { detectProject } from '../context.js'
-import { dockerCompose, primeBundleVolume } from '../docker.js'
-
-export function registerUpdateCommand(program: Command): void {
- program
- .command('update')
- .description('Pull latest image and recreate containers')
- .action(async () => {
- const ctx = detectProject()
-
- p.log.step('Pulling latest images...')
- await dockerCompose(['pull'], ctx.projectDir, { stdio: 'inherit' })
-
- const s = p.spinner()
- s.start('Recreating containers...')
- // Prime the shared bundle_cache volume with web alone first so the up
- // below doesn't race the copy-up if this follows a `down -v` (cold volume).
- await primeBundleVolume(ctx.projectDir, { stdio: 'ignore' })
- await dockerCompose(['up', '-d'], ctx.projectDir)
- s.stop('Containers recreated.')
-
- p.log.success('Update complete! Migrations will run automatically on startup.')
- p.log.info('Run `spree logs` to follow the startup progress.')
- })
-}
diff --git a/packages/cli/src/commands/upgrade.ts b/packages/cli/src/commands/upgrade.ts
index 630febc929..d7724daeb7 100644
--- a/packages/cli/src/commands/upgrade.ts
+++ b/packages/cli/src/commands/upgrade.ts
@@ -2,42 +2,130 @@ 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'
import pc from 'picocolors'
-import { detectProject, hasMonorepoSpreePath } from '../context.js'
-import { dockerComposeCapture, dockerComposeExecOrRun, isServiceRunning } from '../docker.js'
+import { detectProject, hasMonorepoSpreePath, isEjectedProject } from '../context.js'
+import {
+ appServices,
+ dockerCompose,
+ dockerComposeCapture,
+ dockerComposeExecOrRun,
+ isServiceRunning,
+ primeBundleVolume,
+} from '../docker.js'
+import { APP_DIRS, detectPackageManager, generateRouteTree } from './add.js'
-// Sequences bundle update + db:migrate + spree:upgrade rake. Flags map
-// to env vars on the inner rake task: --plan → DRY_RUN, --step → STEP,
-// --to → TO. --plan and --step skip the bundle + migrate pre-steps.
+interface UpgradeFlags {
+ plan?: boolean
+ step?: string
+ to?: string
+ yes?: boolean
+}
+
+// One command for both project shapes. The server half depends on where the
+// Rails app comes from: a prebuilt-image project pulls the new image (its
+// entrypoint migrates on boot), an ejected project bumps the Spree gems and
+// migrates itself. Both then run the spree:upgrade rake backfills and bump the
+// @spree/* packages of the root and the admin apps. Flags map to env vars on
+// the rake task: --plan → DRY_RUN, --step → STEP, --to → TO. --plan and --step
+// run the rake task alone.
export function registerUpgradeCommand(program: Command): void {
- program
- .command('upgrade')
- .description('Walk through a Spree version upgrade (bundle + migrate + spree:upgrade)')
+ withUpgradeOptions(
+ program
+ .command('upgrade')
+ .description(
+ 'Upgrade Spree: the server (image or gems), migrations, data backfills and @spree/* packages',
+ ),
+ ).action(upgrade)
+
+ // `update` predates the merge and only pulled the image. Kept one release
+ // so existing projects' `update` package scripts keep working.
+ withUpgradeOptions(program.command('update', { hidden: true })).action(
+ async (flags: UpgradeFlags) => {
+ p.log.warn(
+ `${pc.bold('spree update')} is deprecated and will be removed in a future release — use ${pc.bold('spree upgrade')}.`,
+ )
+ await upgrade(flags)
+ },
+ )
+}
+
+function withUpgradeOptions(command: Command): Command {
+ return command
.option(
'--plan',
- 'list the data backfills a run would execute — for the installed Spree version, or the --to version (DRY_RUN=1); skip bundle + migrate',
+ 'list the data backfills a run would execute — for the installed Spree version, or the --to version (DRY_RUN=1); runs nothing else',
)
- .option('--step <id>', 'run a single rake step by id (skips bundle + migrate)')
+ .option('--step <id>', 'run a single rake step by id (runs nothing else)')
.option(
'--to <version>',
'explicit target version (auto-detected from installed gem otherwise)',
)
.option('--yes', 'skip prompts on automated steps')
- .action(async (flags: { plan?: boolean; step?: string; to?: string; yes?: boolean }) => {
- const ctx = detectProject()
- await assertUpgradeable(ctx.projectDir)
+}
+
+async function upgrade(flags: UpgradeFlags): Promise<void> {
+ const ctx = detectProject()
+ await assertUpgradeable(ctx.projectDir)
+
+ if (flags.plan || flags.step) {
+ await runRakeUpgrade(ctx.projectDir, flags)
+ if (!flags.plan) printPostUpgradeReminder(ctx.projectDir)
+ return
+ }
+
+ if (isEjectedProject(ctx.projectDir)) {
+ const gemsUpdated = await runBundleUpdate(ctx.projectDir, flags)
+ await runMigrate(ctx.projectDir, flags)
+ await runRakeUpgrade(ctx.projectDir, flags)
+ if (gemsUpdated) await restartAppServices(ctx.projectDir)
+ } else {
+ await pullImage(ctx.projectDir, flags)
+ await runRakeUpgrade(ctx.projectDir, flags)
+ }
+
+ await updateSpreePackages(ctx.projectDir, flags)
- const skipUniversal = Boolean(flags.plan || flags.step)
+ printPostUpgradeReminder(ctx.projectDir)
+}
- if (!skipUniversal) {
- await runBundleUpdate(ctx.projectDir, flags)
- await runMigrate(ctx.projectDir, flags)
- }
+async function confirmStep(message: string, flags: UpgradeFlags): Promise<boolean> {
+ if (flags.yes) return true
+ const confirmed = await p.confirm({ message, initialValue: true })
+ if (p.isCancel(confirmed)) {
+ p.cancel('Upgrade aborted.')
+ process.exit(0)
+ }
+ return confirmed
+}
- await runRakeUpgrade(ctx.projectDir, flags)
+// The image's entrypoint runs db:prepare before Puma starts, and web's
+// healthcheck only passes once Puma answers — so `--wait` returns with the
+// migrations applied and the container ready for the rake step.
+async function pullImage(projectDir: string, flags: UpgradeFlags): Promise<void> {
+ if (!(await confirmStep('Pull the latest Spree image and recreate the containers?', flags))) {
+ p.log.info('Skipping the image pull.')
+ return
+ }
- if (!flags.plan) printPostUpgradeReminder(ctx.projectDir)
- })
+ p.log.step(pc.bold('docker compose pull'))
+ await dockerCompose(['pull'], projectDir, { stdio: 'inherit' })
+
+ p.log.step(pc.bold('Recreating containers and running migrations'))
+ // Prime the shared bundle_cache volume with web alone first so the up
+ // below doesn't race the copy-up if this follows a `down -v` (cold volume).
+ await primeBundleVolume(projectDir)
+ await dockerCompose(['up', '-d', '--wait'], projectDir, { stdio: 'inherit' })
+}
+
+// Puma loaded the old gems at boot; the rake steps ran in fresh processes,
+// but the server itself only picks up the bumped gems on restart.
+async function restartAppServices(projectDir: string): Promise<void> {
+ if (!(await isServiceRunning('web', projectDir))) return
+ p.log.step(pc.bold('Restarting the app to load the updated gems'))
+ await dockerCompose(['restart', ...(await appServices(projectDir))], projectDir, {
+ stdio: 'inherit',
+ })
}
// Upgrade migrates the DB and runs spree:upgrade rake against the project's
@@ -75,20 +163,10 @@ async function assertUpgradeable(projectDir: string): Promise<void> {
}
}
-async function runBundleUpdate(projectDir: string, flags: { yes?: boolean }): Promise<void> {
- if (!flags.yes) {
- const confirmed = await p.confirm({
- message: 'Run `bundle update` to bump Spree gems?',
- initialValue: true,
- })
- if (p.isCancel(confirmed)) {
- p.cancel('Upgrade aborted.')
- process.exit(0)
- }
- if (!confirmed) {
- p.log.info('Skipping `bundle update`.')
- return
- }
+async function runBundleUpdate(projectDir: string, flags: UpgradeFlags): Promise<boolean> {
+ if (!(await confirmStep('Run `bundle update` to bump Spree gems?', flags))) {
+ p.log.info('Skipping `bundle update`.')
+ return false
}
// Scope to spree* gems to avoid surprise major bumps on unrelated deps.
@@ -102,6 +180,7 @@ async function runBundleUpdate(projectDir: string, flags: { yes?: boolean }): Pr
p.log.step(pc.bold(`bundle update ${spreeGems.join(' ')}`))
await dockerComposeExecOrRun(['bundle', 'update', ...spreeGems], projectDir)
+ return true
}
export async function detectSpreeGems(projectDir: string): Promise<string[]> {
@@ -127,29 +206,16 @@ export async function detectSpreeGems(projectDir: string): Promise<string[]> {
}
}
-async function runMigrate(projectDir: string, flags: { yes?: boolean }): Promise<void> {
- if (!flags.yes) {
- const confirmed = await p.confirm({
- message: 'Install + run pending migrations?',
- initialValue: true,
- })
- if (p.isCancel(confirmed)) {
- p.cancel('Upgrade aborted.')
- process.exit(0)
- }
- if (!confirmed) {
- p.log.info('Skipping migrations.')
- return
- }
+async function runMigrate(projectDir: string, flags: UpgradeFlags): Promise<void> {
+ if (!(await confirmStep('Install + run pending migrations?', flags))) {
+ p.log.info('Skipping migrations.')
+ return
}
p.log.step(pc.bold('spree:install:migrations + db:migrate'))
await dockerComposeExecOrRun(['bin/rails', 'spree:install:migrations', 'db:migrate'], projectDir)
}
-async function runRakeUpgrade(
- projectDir: string,
- flags: { plan?: boolean; step?: string; to?: string },
-): Promise<void> {
+async function runRakeUpgrade(projectDir: string, flags: UpgradeFlags): Promise<void> {
// Flags map to env vars so prod (`STEP=channels rake spree:upgrade`) and dev share the same path.
const env: Record<string, string> = {}
if (flags.plan) env.DRY_RUN = '1'
@@ -160,9 +226,75 @@ async function runRakeUpgrade(
await dockerComposeExecOrRun(['bin/rake', 'spree:upgrade'], projectDir, { env })
}
-// The server 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.
+// A Spree package the project resolves from the registry. Local specs
+// (workspace:, file:, link:, git URLs) point at code the operator manages.
+const REGISTRY_SPEC = /^[\^~<>=\d*]|^latest$|^next$/
+
+/**
+ * The @spree/* packages a package.json depends on through the registry —
+ * what `spree upgrade` bumps there. Returns [] for a missing or unreadable file.
+ */
+export function detectSpreePackages(dir: string): string[] {
+ try {
+ const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8')) as {
+ dependencies?: Record<string, string>
+ devDependencies?: Record<string, string>
+ }
+ return Object.entries({ ...pkg.dependencies, ...pkg.devDependencies })
+ .filter(([name, spec]) => name.startsWith('@spree/') && REGISTRY_SPEC.test(spec))
+ .map(([name]) => name)
+ } catch {
+ return []
+ }
+}
+
+/**
+ * The package-manager arguments that move the given packages to the newest
+ * release their declared range allows, without rewriting that range — the
+ * same promise `bundle update` makes against the Gemfile. Yarn Berry's `up`
+ * rewrites ranges unless it re-resolves (`-R`); Classic spells it `upgrade`.
+ */
+export function packageUpdateArgs(
+ pm: string,
+ packages: string[],
+ projectDir: string,
+ dir: string,
+): string[] {
+ if (pm !== 'yarn') return ['update', ...packages]
+ const berry = [dir, projectDir].some((candidate) =>
+ fs.existsSync(path.join(candidate, '.yarnrc.yml')),
+ )
+ return berry ? ['up', '-R', ...packages] : ['upgrade', ...packages]
+}
+
+// The project root carries @spree/cli; each admin app carries the dashboard
+// packages and the Admin SDK. The storefront is the merchant's own fork, so
+// its SDK bump stays theirs (see sdkAdvisory).
+async function updateSpreePackages(projectDir: string, flags: UpgradeFlags): Promise<void> {
+ const targets = ['.', ...APP_DIRS.map((dir) => path.join('apps', dir))]
+ .map((relative) => ({ relative, dir: path.join(projectDir, relative) }))
+ .map((target) => ({ ...target, packages: detectSpreePackages(target.dir) }))
+ .filter((target) => target.packages.length > 0)
+ if (targets.length === 0) return
+
+ if (!(await confirmStep('Update the @spree/* packages of the project and admin apps?', flags))) {
+ p.log.info('Skipping the @spree/* packages.')
+ return
+ }
+
+ for (const target of targets) {
+ const pm = detectPackageManager(projectDir, target.dir)
+ const args = packageUpdateArgs(pm, target.packages, projectDir, target.dir)
+ p.log.step(`${pc.bold(`${pm} ${args.join(' ')}`)} ${pc.dim(`in ${target.relative}`)}`)
+ await execa(pm, args, { cwd: target.dir, stdio: 'inherit' })
+ // An updated dashboard can ship new routes; regenerate now so the next
+ // dev start doesn't rewrite the file and reload the open page.
+ if (target.relative !== '.') await generateRouteTree(target.dir)
+ }
+}
+
+// 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')
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 9abcc6fb67..6350128489 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -29,7 +29,6 @@ import { registerSeedCommand } from './commands/seed.js'
import { registerShellCommand } from './commands/shell.js'
import { registerStopCommand } from './commands/stop.js'
import { registerTaskCommand } from './commands/task.js'
-import { registerUpdateCommand } from './commands/update.js'
import { registerUpgradeCommand } from './commands/upgrade.js'
import { registerUserCommand } from './commands/user.js'
import { VERSION } from './version.js'
@@ -68,7 +67,6 @@ registerAddCommand(program)
registerDevCommand(program)
registerStopCommand(program)
registerRestartCommand(program)
-registerUpdateCommand(program)
registerLogsCommand(program)
registerEjectCommand(program)
registerBuildCommand(program)
diff --git a/packages/cli/tests/upgrade.test.ts b/packages/cli/tests/upgrade.test.ts
index 224b91264d..e7efa647a8 100644
--- a/packages/cli/tests/upgrade.test.ts
+++ b/packages/cli/tests/upgrade.test.ts
@@ -6,7 +6,12 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
vi.mock('execa', () => ({ execa: vi.fn() }))
import { execa } from 'execa'
-import { detectSpreeGems, sdkAdvisory } from '../src/commands/upgrade'
+import {
+ detectSpreeGems,
+ detectSpreePackages,
+ packageUpdateArgs,
+ sdkAdvisory,
+} from '../src/commands/upgrade'
describe('sdkAdvisory', () => {
const tempDirs: string[] = []
@@ -116,3 +121,78 @@ describe('detectSpreeGems', () => {
)
})
})
+
+describe('detectSpreePackages', () => {
+ const dirs: string[] = []
+ afterEach(() => {
+ for (const dir of dirs) fs.rmSync(dir, { recursive: true, force: true })
+ dirs.length = 0
+ })
+
+ function withPackageJson(pkg: object | string): string {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'spree-cli-packages-test-'))
+ dirs.push(dir)
+ fs.writeFileSync(
+ path.join(dir, 'package.json'),
+ typeof pkg === 'string' ? pkg : JSON.stringify(pkg),
+ )
+ return dir
+ }
+
+ it('lists registry-resolved @spree/* packages from both dependency groups', () => {
+ const dir = withPackageJson({
+ dependencies: { '@spree/dashboard': '^1.0.0-beta.8', react: '^19.2.6' },
+ devDependencies: { '@spree/cli': '~3.1.0', '@spree/docs': 'latest' },
+ })
+ expect(detectSpreePackages(dir)).toEqual(['@spree/dashboard', '@spree/cli', '@spree/docs'])
+ })
+
+ it('leaves local and git specs alone', () => {
+ const dir = withPackageJson({
+ dependencies: {
+ '@spree/dashboard': 'workspace:^',
+ '@spree/dashboard-core': 'file:../dashboard-core',
+ '@spree/admin-sdk': 'github:spree/spree#main',
+ },
+ })
+ expect(detectSpreePackages(dir)).toEqual([])
+ })
+
+ it('returns [] without a readable package.json', () => {
+ expect(detectSpreePackages(withPackageJson('{ not json'))).toEqual([])
+ expect(detectSpreePackages('/nonexistent')).toEqual([])
+ })
+})
+
+describe('packageUpdateArgs', () => {
+ it('uses update for pnpm and npm', () => {
+ expect(packageUpdateArgs('pnpm', ['@spree/cli'], '/proj', '/proj')).toEqual([
+ 'update',
+ '@spree/cli',
+ ])
+ expect(packageUpdateArgs('npm', ['@spree/cli'], '/proj', '/proj')).toEqual([
+ 'update',
+ '@spree/cli',
+ ])
+ })
+
+ it('keeps declared ranges on Yarn Classic and Yarn Berry', () => {
+ const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'spree-cli-yarn-test-'))
+ const appDir = path.join(projectDir, 'apps', 'dashboard')
+ fs.mkdirSync(appDir, { recursive: true })
+ try {
+ expect(packageUpdateArgs('yarn', ['@spree/dashboard'], projectDir, appDir)).toEqual([
+ 'upgrade',
+ '@spree/dashboard',
+ ])
+ fs.writeFileSync(path.join(projectDir, '.yarnrc.yml'), 'nodeLinker: node-modules\n')
+ expect(packageUpdateArgs('yarn', ['@spree/dashboard'], projectDir, appDir)).toEqual([
+ 'up',
+ '-R',
+ '@spree/dashboard',
+ ])
+ } finally {
+ fs.rmSync(projectDir, { recursive: true, force: true })
+ }
+ })
+})
diff --git a/packages/create-spree-app/src/templates/package-json.ts b/packages/create-spree-app/src/templates/package-json.ts
index ac8664fd56..41bd0313be 100644
--- a/packages/create-spree-app/src/templates/package-json.ts
+++ b/packages/create-spree-app/src/templates/package-json.ts
@@ -19,7 +19,7 @@ export function rootPackageJsonContent(name: string, pm: PackageManager = 'pnpm'
dev: 'spree dev',
stop: 'spree stop',
down: 'docker compose down',
- update: 'spree update',
+ upgrade: 'spree upgrade',
eject: 'spree eject',
logs: 'spree logs',
'logs:worker': 'spree logs worker',
diff --git a/packages/create-spree-app/src/templates/readme.ts b/packages/create-spree-app/src/templates/readme.ts
index 788127e682..62a806dfc4 100644
--- a/packages/create-spree-app/src/templates/readme.ts
+++ b/packages/create-spree-app/src/templates/readme.ts
@@ -117,7 +117,7 @@ This project uses [\`@spree/cli\`](https://spreecommerce.org/docs/developer/cli/
|---------|-------------|
| \`spree dev\` | Run the app in the foreground — streams logs, Ctrl+C stops it. First run completes setup automatically |
| \`spree stop\` | Stop the API services |
-| \`spree update\` | Pull latest Spree image and restart (runs migrations automatically) |
+| \`spree upgrade\` | Upgrade Spree — the server, database and \`@spree/*\` packages |
| \`spree eject\` | Switch from prebuilt image to building from \`server/\` |
| \`spree build --production\` | Build the production image — includes \`apps/dashboard\` when present |
| \`spree logs\` | View web server logs |
diff --git a/packages/create-spree-app/tests/templates.test.ts b/packages/create-spree-app/tests/templates.test.ts
index ebd692c419..da5b6f288a 100644
--- a/packages/create-spree-app/tests/templates.test.ts
+++ b/packages/create-spree-app/tests/templates.test.ts
@@ -96,7 +96,7 @@ describe('rootPackageJsonContent', () => {
it('includes convenience scripts using spree cli', () => {
const pkg = JSON.parse(rootPackageJsonContent('my-store'))
expect(pkg.scripts.dev).toBe('spree dev')
- expect(pkg.scripts.update).toBe('spree update')
+ expect(pkg.scripts.upgrade).toBe('spree upgrade')
expect(pkg.scripts.eject).toBe('spree eject')
expect(pkg.scripts.logs).toBe('spree logs')
expect(pkg.scripts.console).toBe('spree console')
@@ -168,7 +168,7 @@ describe('readmeContent', () => {
expect(content).toContain('`spree eject`')
expect(content).toContain('`spree logs`')
expect(content).toContain('`spree console`')
- expect(content).toContain('`spree update`')
+ expect(content).toContain('`spree upgrade`')
expect(content).toContain('`spree user create`')
expect(content).toContain('`spree api-key create`')
})