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.

11.1 KB
Raw Blame

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-dashboard and ai keep their current behaviour; any other name is looked up in the extension catalog. A separate spree install or spree extension add was 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 paypal never guesses spree_paypal; the real gem is spree_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 explicit spree 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_development database, so the command explains that and asks. --yes answers for non-interactive use, and a non-interactive run without --yes stops 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 during bundle 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 runs db:migrate, which does nothing when there is nothing to migrate.
  • Safe to run twice. A gem already in the Gemfile skips bundle add but still runs the generator and migrations, so re-running repairs a half-finished install. If any step after bundle add fails, the command restores the Gemfile, Gemfile.lock and config/ 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 --skip to 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_easypost and spree_opentelemetry, and the prebuilt image contains them. On a project that has not been ejected, spree add stripe checks the image's own Gemfile.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 as gem '<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 stable spree_stripe is the 5.x line's 1.8.2. Each of these gems depends on the exact spree_core, so bundle update spree moves 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 dashboard field and the --npm flag are built in this release, though none of the nine extensions has a plugin yet, so third-party plugins installed with spree 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

  1. Resolve the name against the catalog, or take --gem / --npm.
  2. Eject if the project still runs the prebuilt image (isEjectedProject), after consent. Reuses the spree eject code.
  3. Add the gem with the same path spree bundle uses (exec into web, or a one-off container when it is down). Bundler prints the gem's post-install message here.
  4. Run the install generator when bin/rails generate --help lists <gem>:install.
  5. Migrate with db:migrate.
  6. Install the dashboard plugin into apps/dashboard/ (and apps/seller-dashboard/ when the entry says it has a seller half), when that app exists, with the project's package manager.
  7. 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

  1. Add the catalog, the resolver and the steps to spree add, with Vitest coverage for resolution, consent and rollback.
  2. Add the nine catalog entries above, with the paypal and avatax aliases.
  3. Replace the manual four-step recipe in the server template's AGENTS.md ("Extensions") and in the CLI docs with spree add <extension>.
  4. Have spree plugin new print the matching spree 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 in add.ts for 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 layout
  • packages/cli/src/commands/add.ts, bundle.ts, eject.ts, restart.ts
  • spree/providers/stripe/lib/generators/spree_stripe/install/install_generator.rb — an install generator that does nothing, which the step skipping must tolerate