Spree Project

Spree Commerce Project

A Rails application powered by Spree Commerce.

Project flavors — detect FIRST, it changes every command

Not every Spree app is a create-spree-app project. Check these signals in order before running anything:

Command mapping — Spree CLI form → classic-app native form:

Other flavor differences:

• Rails root: backend/ in create-spree-app projects, . in classic apps. Paths written as backend/app/… in these skills mean app/… on a classic app.
• Local docs (node_modules/@spree/docs/dist/) exist only when the project installs @spree/docs. On classic apps, use https://spreecommerce.org/docs/llms.txt instead.
• The rake tasks themselves (spree:install:migrations, spree:upgrade, the spree:model/spree:api_resource generators) ship inside the spree gems and work identically in both flavors — only the invocation wrapper differs. Note spree:upgrade and the generators ship in spree_core 5.5+: a pre-5.5 app gains them after the bundle update step of the upgrade, so on old apps run the gem bump first.

create-spree-app project layout

All Spree-specific code (models, decorators, subscribers) lives under backend/app/.

Where to find Spree documentation

When you need Spree-specific guidance — how a model works, what events are available, how the cart pipeline runs — read the local docs first:

node_modules/@spree/docs/dist/
├── developer/
│   ├── core-concepts/       Products, orders, payments, inventory
│   ├── customization/       Decorators, extensions, dependencies, events
│   ├── admin/               Admin panel customization
│   ├── storefront/          Storefront building guides
│   ├── sdk/                 TypeScript SDK documentation
│   └── tutorial/            Step-by-step guides
├── api-reference/
│   ├── store-api/           Store API v3 guides
│   └── store.yaml           OpenAPI spec — every Store API endpoint
└── integrations/            Stripe, Meilisearch, etc.

Reach for these before guessing from training data. The local docs are the authoritative source for the installed Spree version.

Customization patterns

90% of work on a Spree project is customization: wiring in external services, adding custom models, tweaking behavior. Spree exposes a layered set of extension points for this — settings, configuration, events, dependency injection, admin extension APIs, the resource generator, decorators, gems. Picking the right one matters because each layer has different upgrade-safety characteristics.

For routing a specific customization to the right pattern, use the spree-customization skill. It has the full decision table (subscribers vs decorators vs Spree.dependencies vs admin APIs vs Spree.ransack) with worked examples. Reach for it whenever the right approach isn't obvious.

Quick summary of the priority order:

1. Settings / Spree::Config — for runtime behavior toggles.
2. Events + subscribers — for side effects ("sync to ERP when order completes").
3. Dependency injection (Spree.dependencies) — for swapping how a core service computes. See spree-dependencies skill.
4. Admin extension APIs (Spree.admin.navigation, Spree.admin.partials, Spree.admin.tables, Spree.ransack) — for admin UI and search.
5. Generators (spree:api_resource, spree:model) — for brand-new models / resources.
6. Decorators (spree:model_decorator, spree:controller_decorator) — for structural changes to existing Spree classes.
7. Extensions (gems) — only when sharing customization across multiple apps.

Conventions you should always follow

• Namespace under Spree:: — all Spree-related Ruby classes live in app/models/spree/, app/controllers/spree/, etc.
• Spree.user_class / Spree.admin_user_class — never reference Spree::User directly. The user class is configurable.
• Spree::Current.store / .currency / .locale — per-request context, available in models, controllers, services.
• Prefixed IDs in the API — every v3 API response returns Stripe-style prefixed IDs (prod_86Rf07xd4z, or_m3Rp9wXz). Never expose raw integer IDs. Same on writes — the API accepts prefixed IDs.
• Spree.base_class — inherit from this, not ActiveRecord::Base. It applies Spree's base configuration.

Common commands

@spree/cli (installed by create-spree-app) wraps the Docker-based dev workflow:

spree dev                          # run the stack in the foreground (streams logs; Ctrl+C stops web + worker, DBs stay up)
spree stop                         # tear down
spree console                      # Rails console
spree logs                         # follow web container logs
spree restart                      # restart the Rails process

spree migrate                      # install engine migrations from gems + db:migrate
spree generate <name> [args]       # any Spree generator
spree bundle add <gem>             # add a gem (persists in bundle_cache volume)
spree rake <task>                  # any rake task
spree exec <cmd>                   # universal escape hatch
spree rails <cmd>                  # any bin/rails command
spree routes                       # show Rails routes
spree seed                         # seed the database
spree sample-data                  # load sample products/categories/images
spree user create                  # create an admin user
spree api-key create               # create an API key (also: list, revoke)
spree db:reset                     # drop + recreate + migrate + seed (destructive)

spree upgrade                      # version upgrade

If you don't have spree on your PATH, prefix with the package runner: npx spree …, pnpm exec spree …, or bunx spree ….

When in doubt

• Not sure which customization pattern fits? See the spree-customization skill — it routes the decision.
• Need to add a new model + API endpoint? See the spree-resource skill.
• Need to extend an existing Spree model/controller? See the spree-decorators skill.
• Need to upgrade Spree? See the spree-upgrade skill.
• Need details on a specific Spree concept? Read node_modules/@spree/docs/dist/developer/ first.