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.
Spree 6.0 Beta Release
Status: Released — 6.0.0 (stable) prepared 2026-10-27
Target: Spree 6.0
Depends on: 5.6-project-layout-and-dashboard.md (dashboard packaging, embedded starter)
Author: Damian
Last updated: 2026-10-27
Tracking: Linear — · GitHub —
Summary
Ship the first public beta of Spree 6.0: prerelease Ruby gems on RubyGems, the
TypeScript packages on npm, and create-spree-app / spree add scaffolding a
6.0 project by default. The npm side is the delicate half — @spree/[email protected]
currently sits on latest and is the 5.x Store API, and every storefront (both
branches) depends on ^1.2.1. A 6.0 SDK published as 1.x would silently
upgrade every 5.x storefront onto an API that no longer exists. The release is
therefore built around one rule: the beta is reachable by opt-in tag or
explicit range, and latest keeps meaning 5.x until 6.0 is final.
Key Decisions (do not deviate without discussion)
Gems ship as
6.0.0.beta1. RubyGems treats it as a prerelease, sogem install spreeand an unpinnedgem 'spree'keep resolving to 5.x — only--preor an explicit6.0.0.beta1pin reaches it. The version string lives in one place (spree/core/lib/spree/core/version.rb), andrake gem:releasereads it for all nine gems. Usebeta1, notbeta.1: both are valid prereleases and both sort correctly, andbeta1matches the existing5.6.0.rc1convention.@spree/sdkgoes to2.0.0-beta.1, published under thebetatag. (Superseded from the release candidate afterrc6by Decision 3: the SDK moves to the Spree version. The reasoning about tags still holds.) This is the load-bearing decision. The major bump states the Store API break, and the prerelease + non-latesttag means^1.2.1in both storefront branches cannot resolve to it — semver ranges exclude prereleases unless the range itself is a prerelease.lateststays on1.2.1for 5.x users. Therelease-sdkjob must gain the tag logic the admin-sdk job already has — today it runs a barenpm publish, which would push the beta straight tolatestand break every 5.x storefront. This is the single highest-risk item in the release.The packages that talk to the Spree API carry the Spree version. (Revised 2026-10-26; the beta and the first six release candidates shipped them as
1.0.0-rc.x, and@spree/sdkas2.0.0-rc.x.)@spree/sdk,@spree/admin-sdk,@spree/seller-sdk,@spree/core, the dashboard trio and@spree/seller-dashboardare one Changesetsfixedgroup, versioned fromSpree::VERSION: gems6.0.0.rc7ship as6.0.0-rc.7, and6.0.0is6.0.0everywhere. Their types come from the serializers and their request shapes from the OpenAPI files, so a version number that maps to nothing on the backend only made people consult a compatibility table nobody maintained, and the numbering had already drifted (the seller panel atrc.7, everything else atrc.6).@spree/cliandcreate-spree-appkeep their own versions: they manage Docker and scaffolding, not the API, and need patch releases of their own.- Released by
pnpm version:packages(scripts/version-packages.mjs), which runschangeset versionand then moves the group to the Spree version. Changesets still writes the changelogs, but for the group a changeset's bump type only decides the changelog heading. A Spree release with no TypeScript changes still publishes the group with an entry saying so, as the nine gems already do. - The cost accepted: a breaking change in the TypeScript code alone waits for the next Spree major, the same promise the Store API makes.
- Switched at the release candidate after
rc6, not at GA. Every existing range misses the jump wherever it happens, so the question is only whether the migration path first runs on release day. GA stays a plain promotion of the last candidate. - Existing projects are moved by
spree upgrade, which rewrites any range for a package in the group that is still on an older line (^1.0.0-rc.7,>=0.13.1 <2.0.0) to the Spree version before updating. The CLI only knows the group from its build, so a project updates@spree/clifirst, then upgrades. Until the group shares one version, the CLI rewrites nothing. The storefront stays the merchant's: the CLI names the exact@spree/sdkrange to move to. - Never publish a stable
1.0.0or2.0.0of a package in the group: either would satisfy the old ranges and look like a supported line. Deprecate the old lines on npm after the first aligned release (npm deprecate "@spree/[email protected]" "Moved to 6.x with Spree. Run: spree upgrade", likewise@spree/[email protected]). - Peer ranges inside the group are literal, from the release to the end of
its major (
>=6.0.1-rc.1 <7.0.0-0), set by the script on every release. The floor is the full version: a patch release candidate does not satisfy>=6.0.0-0. - Released from tags, in one workflow (2026-10-26).
release.ymlpublishes the gems and the group on the Spree tag (v6.0.0.rc7), and each tool on its own tag (@spree/[email protected],[email protected]), after checking the tag against the versions in the repository.packages.ymlonly runs checks. The templates the CLI embeds (the dashboard and seller starters, the plugin peers) accept the whole major (^6.0.0-0), so a CLI tag pushed before the Spree tag never points at packages not yet on npm.
Use
rc.7, neverrc7, on npm: semver compares dot-separated prerelease identifiers numerically but bare strings alphabetically, so1.0.0-beta9sorts ABOVE1.0.0-beta10and a release would ship backwards. The gems keep6.0.0.rc7; the script converts.Accepted break: the dashboard trio currently publishes to
nextat0.13.1. At1.0.0-beta.1the release jobs route it tobetainstead (any version containing-), so anyone installing@spree/dashboard@nextstops receiving updates and must move to@beta. Call this out in the release notes — the Developer Preview audience is small and reachable.- Released by
6-0-devmerges intomainon both scaffolding repos before the release.create-spree-appclonesspree/spree-starterandspree/storefrontwith no--branch, so it follows whatevermainholds — which is why merging is what makes 6.0 the default for new projects. No--branchflag is added here, and nothing needs revising again at GA. The merge lands after the gems and SDK are published, because the branches being merged must pin released versions — and the momentmainmoves, every new project gets it. So the order is: publish → pin → merge. See Migration Path.The starter must pin released gems, not a git branch — and this is a merge blocker.
starter/6-0-devpinsgithub: 'spree/spree', branch: 'main'. That is right for development and wrong the instant it becomesmain: every new project would build against whatever landed that morning, with no reproducible version in a bug report, andbundle installwould clone this whole monorepo. Flip it to'6.0.0.beta1'and regenerate the committedGemfile.lock(currently resolved against6.0.0.alphafrom the git source) as part of the merge, not after it.Every gem in the monorepo publishes from the 6.0 line — providers and opentelemetry included. All nine gemspecs already read
Spree.version, so they version in lockstep; the only gap wasspree_stripe, absent fromSPREE_PROVIDER_GEMSinspree/Rakefile(fixed — see Migration Path step 0). That gap was a hard release blocker: the starter's Gemfile requiresspree_stripe, sobundle installwould have fallen back to the standalone1.8.1line, which targets 5.x.spree_opentelemetryalready ships viaSPREE_OPTIONAL_GEMSand needs no change. The published set is now:spree,spree_core,spree_api,spree_emails,spree_dashboard,spree_opentelemetry,spree_easypost,spree_meilisearch,spree_stripe.Jumping
spree_stripefrom its standalone1.8.1to6.0.0.beta1is safe: the beta is a prerelease, sogem 'spree_stripe'and~> 1.8on 5.x keep resolving to the 1.x line. A provider gem's version continuity is deliberately subordinate to the monorepo's — that is whatSpree.versionin every gemspec already encodes.Clear the changeset backlog in one release train. 30 unreleased changesets have accumulated since ~July. Run
pnpm changeset version(notversion:preview) so@spree/sdkis included — this is the release where it must be.
Design Details
Current state
| Package | Local | npm latest |
npm next |
Consumers to protect |
|---|---|---|---|---|
| gems | 6.0.0.alpha |
5.6.x |
— | unpinned gem 'spree' |
@spree/sdk |
1.2.1 | 1.2.1 | — | storefront ^1.2.1, both branches |
@spree/admin-sdk |
0.8.1 | 0.1.0 | 0.8.1 | none |
@spree/dashboard{,-core,-ui} |
0.13.1 | 0.2.1 | 0.13.1 | none |
@spree/cli |
2.4.9 | 2.4.9 | — | 5.x users running spree |
create-spree-app |
1.2.1 | 1.2.1 | — | new projects |
Why the SDK needs a major, not a 0.x or a 1.3.0
The storefront depends on @spree/sdk: "^1.2.1". Under that range:
1.3.0→ resolves. Every 5.x storefront silently moves to the 6.0 SDK on its nextpnpm install. Unacceptable.2.0.0→ does not resolve, but occupieslatestand becomes the default for anyone runningnpm install @spree/sdk. Premature for a beta.2.0.0-beta.1under thebetatag → does not resolve into^1.2.1, does not touchlatest, and is reachable as@spree/sdk@betaor by exact pin. This is the choice.
Verified: semver.satisfies("2.0.0-beta.1", "^1.2.1") === false, and likewise
for the embedded-template range below.
The CLI / create-spree-app pairing
@spree/cli and create-spree-app are the user-facing front door and are
not prerelease-tagged, because a user running the documented
npx create-spree-app must land on 6.0 once we flip the default. Two options,
and the choice determines how loud the beta is:
- (a) Ship them as normal
latestreleases once the starter branches flip. New projects get 6.0 beta; existing 5.x projects are unaffected (the CLI operates on an already-generated project). This is the "6.0 is the default for new projects" outcome you asked for. - (b) Ship them as
beta-tagged prereleases (3.0.0-beta.1), so 6.0 is opt-in vianpx create-spree-app@beta. Safer, but then 6.0 is not the default and the goal isn't met.
Recommend (a), gated on the starter branches being flipped and a scaffold
smoke test passing — the release chain (admin-sdk → dashboard → cli → create-spree-app) already encodes the ordering, and the embedded-template
range >=0.13.1 <2.0.0 floats scaffolds onto future dashboard releases
without a CLI republish.
What already works and needs no change
rake gem:releasebuilds and pushes all nine gems from the singleVERSIONconstant; theReleaseworkflow fires on anyv*tag with Trusted Publishing. Taggingv6.0.0.beta1is the whole gem release.- The npm release chain is correctly ordered and gated
(
admin-sdk → dashboard → cli → create-spree-app), each job idempotent via a published-version check, so a re-run is safe. sync-dashboard-starter.mjsfloors the embedded template at the released dashboard version with>=x.y.z <2.0.0, which correctly excludes prereleases — scaffolds will not accidentally pick up a1.0.0-beta.
Migration Path
Ordered; each step is independently verifiable. Steps 0-1 are repo hygiene that must land before any version bump, because both change what a publish does.
Publish every gem. Add
spree_stripetoSPREE_PROVIDER_GEMSinspree/Rakefile(done). Verify the full set builds — all nine gemspecs readSpree.version, andspree_stripe,spree_easypost,spree_meilisearchandspree_opentelemetrywere each confirmed to build cleanly.Fix the SDK release job. Add the
Determine npm tagstep torelease-sdkin.github/workflows/packages.yml, copied fromrelease-admin-sdk, extended so a version containing-publishes underbeta. Do this before any version bump lands on main — otherwise the first push after the bump publishes the 6.0 SDK tolatestand every 5.x storefront breaks on its next install. Single highest-risk item.Prepare
spree-starterfor the merge. On6-0-dev, replace thegithub: 'spree/spree', branch: 'main'block with'6.0.0.beta1'for all six required gems, and regenerateGemfile.lock(committed, currently resolved against6.0.0.alphafrom the git source). Leave theSPREE_PATHdevelopment branch untouched — worktrees depend on it. This cannot be done before step 3 publishes the gems, so the sequence is: publish gems → pin → merge.Bump and release the gems. Set
VERSION = '6.0.0.beta1'inspree/core/lib/spree/core/version.rb, tagv6.0.0.beta1, and let theReleaseworkflow push all nine gems. Confirm each appears on RubyGems before proceeding — the starter's pin depends on every one of them.Refresh the Developer-Preview notes in the package READMEs.
@spree/dashboardand@spree/dashboard-uiboth say APIs "may change between 0.x releases", which stops being true at1.0.0-beta.1; the seller packages' notes already name thebetatag. Reword them to the beta line (published underbeta, promoted tolatestat GA) in the same change as the version bump, so npm never shows install instructions that contradict the published tag.Version and publish the npm packages. Clear the changeset backlog with
pnpm changeset version(plain — notversion:preview, which carries--ignore @spree/sdk), then set the versions by hand:1.0.0-beta.1for@spree/admin-sdk, the dashboard trio,@spree/seller-sdkand@spree/seller-dashboard;2.0.0-beta.1for@spree/sdk. Changesets has no first-class prerelease-major path that plays well with these exceptions, so the edit is deliberate and reviewed. Merge to main and let the release chain publish —admin-sdkandsellerrun in parallel, both gatingrelease-cli, which gatescreate-spree-app.Merge
6-0-devintomainonspree/spree-starterandspree/storefront. With steps 2-4 done,mainon both repos resolves released gems and a published SDK the moment it becomes the default, socreate-spree-app— which clones without--branch— scaffolds 6.0 with no change to this repo. Point the storefront's@spree/sdkdependency at the published2.0.0-beta.1in the same merge.Seller panel distribution (done):
sync-dashboard-starter.mjsis generalized tosync-starter.mjs <target> [starter-package]and the CLI build renders both templates;spree addgained aseller-dashboardcomponent (addDashboard→ app-parameterizedaddApp, with the unit battery now running against both apps);create-spree-appscaffoldsapps/dashboardandapps/seller-dashboard; the starter's Dockerfile gained a mirroredseller-dashboardbuild stage (customapps/seller-dashboard/when present, stock template otherwise) that builds withVITE_BASE_PATH=/sellers/and setsSPREE_SELLER_PANEL_DIST_PATH; andpackages.ymlgained arelease-sellerjob publishing@spree/seller-sdkthen@spree/seller-dashboard, withrelease-cligated on it. The Dockerfile change lives in the starter repo and rides the same merge as step 2.Smoke test the real path —
npx create-spree-app@<candidate>into a temp dir, boot it, confirm the dashboard loads and the storefront talks to the API. The scaffold is the only test that exercises gem pins, npm ranges and branch defaults together, and it is the first thing a beta user runs.Announce as beta, naming the install commands explicitly: gems need
--preor an exact pin,@spree/sdkneeds@beta.
Stable release (6.0.0)
Decided 2026-10-27, when the release was prepared from rc7:
- Promotion of the last candidate.
Spree::VERSIONmoves to6.0.0andpnpm version:packagesmoves the group to6.0.0, whichdistTagpublishes underlatest. The peer ranges inside the group become>=6.0.0 <7.0.0-0. doorkeeperstays pinned at~> 6.0.0.rc2. No final6.0.0is on RubyGems yet, and the pin already accepts it when it lands, so no Spree release is needed then.gem buildwarns about the pre-release dependency; Bundler installs it without one.backend/layout support stays in the CLI for now. Removing it is a breaking CLI change and goes out later, after a warning release.- The Admin and Seller APIs now deprecate instead of removing — the same
procedure as the Store API (see
CLAUDE.md). - After the tag:
spree-startermoves from'>= 6.0.0.beta1'to'~> 6.0'(the open range would accept Spree 7), the storefront moves to@spree/sdk^6.0.0, and the old npm lines are deprecated as Decision 3 describes.
Constraints on Current Work
- Never publish
@spree/sdktolatestuntil 6.0 is final. Any 6.0-line SDK release is2.xprerelease under thebetatag. The 5.x storefront depends on^1.2.1andlatestis what an unpinned install resolves to. - Don't use
pnpm version:previewfor this release — it carries--ignore @spree/sdk, which is exactly the package that must move. - Gem version changes go in
spree/core/lib/spree/core/version.rbonly; every gem and the release task read it. - Don't hand-edit
packages/*/package.jsonversions — Changesets owns them. The single exception is the SDK prerelease string in step 3, which should be a deliberate, reviewed edit. - A dashboard release without a CLI release still reaches users (the embedded
template floats
>=x.y.z <2.0.0); don't add a CLI republish "to pick it up". - A new gem in the monorepo must be added to
spree/Rakefilein the same change that adds its gemspec. A gemspec readingSpree.versionlooks released but is invisible torake gem:release— exactly howspree_stripecame to be missing. Provider gems go inSPREE_PROVIDER_GEMSwith an explicit path; everything else inSPREE_CORE_GEMS/SPREE_OPTIONAL_GEMS. - Don't "restore version continuity" for a provider gem by giving it a version
of its own. All nine gemspecs read
Spree.versiondeliberately; a provider jumping from a standalone1.xto the monorepo line is expected.
Open Questions
- CLI and create-spree-app:
latest(option a, 6.0 becomes the default) orbeta-tagged (option b, opt-in)? Recommend (a); it's the stated goal.
References
.github/workflows/release.yml— every release, from its tagscripts/publish-packages.mjs— npm publishing, in dependency orderscripts/sync-starter.mjs— embedded template version flooringdocs/plans/5.6-project-layout-and-dashboard.md— dashboard packaging