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 CLI: add extensions with one command
Status: In Progress — building the catalog, the install steps and the documentation updates
Target: Spree 6.0
Depends on: 5.6-project-layout-and-dashboard.md (spree add, project layout, spree eject)
Author: Damian Legawiec ([email protected])
Last updated: 2026-10-19
Tracking: Linear V-3753 · GitHub spree/spree#14924
Summary
Installing a Spree extension today takes four commands and some Docker background: eject the project if it still runs the prebuilt image, spree bundle add <gem>, spree generate <gem>:install, spree migrate, then restart the server. Skip the eject and the gem silently does nothing. Extend spree add so spree add paypal does all of it, and also installs the extension's dashboard plugin when it has one. The CLI looks up what paypal means in a catalog of extensions shipped inside the CLI package, so the command never needs to know where an extension's code comes from. That keeps the planned move of extensions from RubyGems to npm a catalog change, not a command change.
Key Decisions (do not deviate without discussion)
- One command,
spree add, for components and extensions.dashboard,seller-dashboardandaikeep their current behaviour; any other name is looked up in the extension catalog. A separatespree installorspree extension addwas rejected: users should not have to know whether the thing they want is an app, a file set or a gem. - Names resolve only through the catalog.
spree add paypalnever guessesspree_paypal; the real gem isspree_paypal_checkout, and a guessed name turns a typo into installing whatever gem happens to carry it, which is a known supply-chain attack. Extensions outside the catalog are installed with an explicitspree add --gem <name>(and--npm <package>for a dashboard plugin), which prints what it is about to install and asks first. - The catalog is a JSON file shipped inside
@spree/cli. Its source lives in the monorepo; each CLI release bundles the current copy. No network call. That means the command works offline, stays fast, and a compromised remote file cannot change what gets installed. New first-party extensions show up with the next CLI release, and the CLI already releases often. Fetching the catalog from GitHub at runtime was rejected for now: it adds a failure mode and an attack surface to save a few days of lag. - Ejecting needs the developer's consent. Gems added to the prebuilt image are lost when the container is recreated, so a non-ejected project must eject first. Ejecting moves the app to a fresh
spree_developmentdatabase, so the command explains that and asks.--yesanswers for non-interactive use, and a non-interactive run without--yesstops with an explanation. - Setup messages belong to the gem. Anything the merchant must do after installing (set an environment variable, create a payment method in the dashboard) goes in the gemspec's
post_install_message, which Bundler prints duringbundle add. Most gems need none. The catalog carries no per-extension help text. - The install generator is optional; migrations always run. An extension may ship
<gem>:install. The command runs it when it exists and skips it otherwise. It then always runsdb:migrate, which does nothing when there is nothing to migrate. - Safe to run twice. A gem already in the Gemfile skips
bundle addbut still runs the generator and migrations, so re-running repairs a half-finished install. If any step afterbundle addfails, the command restores the Gemfile, Gemfile.lock andconfig/it started with, so a half-installed gem's initializer cannot stop the app from booting. Copied migrations are kept: one that already ran would otherwise run again on the next attempt. A repair run passes--skipto the install generator, keeping files the first run wrote. - A gem the project already lists is reported as installed (decided 2026-10-19). New projects already carry
spree_stripe,spree_meilisearch,spree_easypostandspree_opentelemetry, and the prebuilt image contains them. On a project that has not been ejected,spree add stripechecks the image's ownGemfile.lock(not the one on disk, which may list gems added by hand since), says the gem is already part of the project and stops: no eject, no new database. On an ejected project it re-runs the install generator and migrations, to repair a half-finished install. Ejecting and repairing every time was rejected as costing the developer a fresh database for nothing. - Gems released with Spree are pinned to at least the project's Spree version (decided 2026-10-19). Catalog entries marked
"release": "spree"(mcp, opentelemetry, stripe, meilisearch, easypost) are added asgem '<name>', '>= <locked spree version>', the same shape the project Gemfile already uses for the other Spree gems. Without the pin Bundler picks an old release: RubyGems' newest stablespree_stripeis the 5.x line's 1.8.2. Each of these gems depends on the exactspree_core, sobundle update spreemoves them together. An exact pin was rejected because every Spree upgrade would then have to edit the line by hand. - The dashboard plugin step ships now (decided 2026-10-19). The catalog's
dashboardfield and the--npmflag are built in this release, though none of the nine extensions has a plugin yet, so third-party plugins installed withspree add --gem … --npm …work today and the first first-party plugin needs only a catalog line. Accepted trade-off: the step has no first-party user yet and is covered by unit tests only. - The server restarts in place (decided 2026-10-19). When web is running, the command restarts the app containers, which starts a fresh Rails process that loads the new gem from the shared gem volume. A full stop and start was rejected as slower for no gain.
- Projects booted from the monorepo are out of scope. That setup (
SPREE_PATH) is internal Spree development only, and the command does not special-case it.
Design Details
Command surface
spree add paypal # catalog extension: gem + dashboard plugin if any
spree add paypal --yes # also consent to ejecting, for CI and scripts
spree add --gem acme_loyalty # an extension outside the catalog (asks first)
spree add --gem acme_loyalty --npm @acme/loyalty-dashboard
spree add dashboard | seller-dashboard | ai # unchanged
Steps
- Resolve the name against the catalog, or take
--gem/--npm. - Eject if the project still runs the prebuilt image (
isEjectedProject), after consent. Reuses thespree ejectcode. - Add the gem with the same path
spree bundleuses (exec intoweb, or a one-off container when it is down). Bundler prints the gem's post-install message here. - Run the install generator when
bin/rails generate --helplists<gem>:install. - Migrate with
db:migrate. - Install the dashboard plugin into
apps/dashboard/(andapps/seller-dashboard/when the entry says it has a seller half), when that app exists, with the project's package manager. - Restart web and worker, only if they are running.
Catalog
packages/cli/src/extensions.json, imported at build time. The first release supports exactly these gems:
{
"extensions": {
"mcp": { "label": "MCP server", "gem": "spree_mcp", "release": "spree" },
"opentelemetry": { "label": "OpenTelemetry", "gem": "spree_opentelemetry", "release": "spree" },
"stripe": { "label": "Stripe", "gem": "spree_stripe", "release": "spree" },
"paypal_checkout": { "label": "PayPal", "gem": "spree_paypal_checkout", "aliases": ["paypal"] },
"adyen": { "label": "Adyen", "gem": "spree_adyen" },
"klaviyo": { "label": "Klaviyo", "gem": "spree_klaviyo" },
"avatax_official": { "label": "Avalara AvaTax", "gem": "spree_avatax_official", "aliases": ["avatax"] },
"meilisearch": { "label": "Meilisearch", "gem": "spree_meilisearch", "release": "spree" },
"easypost": { "label": "EasyPost", "gem": "spree_easypost", "release": "spree" }
}
}
Three spellings resolve to an entry: its key (the gem name without spree_), any of its aliases, and the full gem name. So spree add paypal, spree add paypal_checkout and spree add spree_paypal_checkout all install the same gem. An alias may not repeat another entry's key, alias or gem name, or the name of a built-in component (dashboard, seller-dashboard, ai); a Vitest spec enforces this. An unknown name lists the supported extensions and points at --gem.
"release": "spree" marks a gem released together with Spree, which is pinned to at least the project's Spree version. An optional dashboard names the npm package of the extension's dashboard plugin (and sellerDashboard its seller panel plugin). An entry without dashboard installs only the gem; none of the first nine ships a dashboard plugin yet. An entry names where each part comes from and nothing about how to install it; the generator and migrations are discovered, not declared. When extensions move to npm, an entry changes from "gem": "spree_paypal_checkout" to an npm source, and only the step that adds the gem learns the new source.
spree add mcp installs the store's own MCP server (spree_mcp). It is unrelated to spree add ai, which connects coding agents to the Spree documentation MCP server; the closing message of each says which one it set up.
Extension author contract
Documented in docs/developer/contributing/creating-an-extension.mdx:
- Optionally ship
<gem_name>:install; never require it for the gem to work. - Ship migrations in the engine. The generator copies them, or the engine adds its migration path.
- Put any manual setup in
post_install_message, and keep it short.
Migration Path
- Add the catalog, the resolver and the steps to
spree add, with Vitest coverage for resolution, consent and rollback. - Add the nine catalog entries above, with the
paypalandavataxaliases. - Replace the manual four-step recipe in the server template's
AGENTS.md("Extensions") and in the CLI docs withspree add <extension>. - Have
spree plugin newprint the matchingspree add --gem … --npm …line, so plugin authors see how their users will install the plugin.
Constraints on Current Work
- New first-party extension gems must work without running an install generator, and must put manual setup steps in
post_install_message. - Don't add new
spree add <name>special cases inadd.tsfor gems. Extensions go in the catalog.
Open Questions
spree remove <extension>: wanted eventually; the catalog makes it straightforward, but rolling back migrations safely needs its own design.
References
docs/plans/5.6-project-layout-and-dashboard.md—spree add,spree eject, project layoutpackages/cli/src/commands/add.ts,bundle.ts,eject.ts,restart.tsspree/providers/stripe/lib/generators/spree_stripe/install/install_generator.rb— an install generator that does nothing, which the step skipping must tolerate