Spree Commerce Project (Spree 6)

Spree is a headless commerce engine: a Rails app (the

spree

gems) that serves the Store, Admin and Seller REST APIs, plus TypeScript apps you own (a React admin dashboard and a Next.js storefront). Customization happens around the engine — configuration, hooks, events, providers — not by forking it.

Coming from Spree 5.x? Read the
spree-upgrade-5-to-6
skill first — cart/order split, no state machines, React dashboard, API v2 and
spree_admin
removed.

Detect the project flavor FIRST — it changes every command

Signal	Flavor	How commands run
`server/Gemfile` (or legacy `backend/Gemfile` ) + `docker-compose.yml` + `package.json` with `@spree/cli`	create-spree-app project	`spree <cmd>` — the CLI routes into the Docker `web` container
Rails app at the repo root ( `config/application.rb` , `Gemfile` with `spree` gems), no `server/`	classic Rails app	Native from the app root: `bin/rails …` , `bundle exec rake …`

spree

isn't on PATH, use

npx spree …

pnpm exec spree …

. The CLI accepts both

server/

and the older

backend/

directory name.

Task	Spree CLI	Classic Rails app
Run the stack	`spree dev`	`bin/dev` or `bin/rails server`
Rails console	`spree console`	`bin/rails console`
Shell in the container	`spree shell`	(you're already in one)
Install + run migrations	`spree migrate`	`bin/rails spree:install:migrations && bin/rails db:migrate`
Generator	`spree generate api_resource Brand …` (bare names auto-prefix `spree:` )	`bin/rails g spree:api_resource Brand …`
Run specs	`spree test spec/models/…` (RAILS_ENV=test)	`bundle exec rspec spec/models/…`
Rake task	`spree task <name>` for Spree tasks (the CLI adds `spree:` , so leave it off); `spree exec bin/rake <task>` for any other	`bundle exec rake <task>`
Sample data	`spree sample-data` (default store; another store: `spree task load_sample_data STORE_CODE=eu` )	`bin/rails spree:load_sample_data` ( `STORE_ID=store_…` or `STORE_CODE=…` to target a non-default store)
Version upgrade	`spree upgrade`	`bundle update spree…` , migrate, `bin/rails spree:upgrade`
Anything else	`spree exec <cmd>`	`<cmd>`

Paths written

server/app/...

in these skills mean

app/...

in a classic app.

Project layout (create-spree-app)

text

my-store/
├── server/                 # The Spree API — a full Rails 8.1 app (spree-starter). Your Ruby code lives here.
│   ├── app/{models,services,workflows,subscribers,controllers,serializers}/
│   ├── config/initializers/spree.rb   # hooks, registries, dependencies, subscribers
│   ├── Dockerfile          # builds the production image (API + dashboard)
│   └── Gemfile
├── apps/
│   ├── dashboard/          # React admin (@spree/dashboard) — plugins in src/plugins.ts
│   ├── seller-dashboard/   # Marketplace seller panel (optional)
│   └── storefront/         # Next.js storefront on @spree/sdk (optional)
├── docker-compose.yml      # prebuilt ghcr.io/spree/spree image + Postgres (Meilisearch optional, commented out)
├── .env                    # SECRET_KEY_BASE, ACTIVE_RECORD_ENCRYPTION_* keys, SPREE_PORT, SPREE_VERSION_TAG… (mode 0600)
├── AGENTS.md / CLAUDE.md   # generated agent instructions
└── package.json            # pins @spree/cli

server/
is the only part that is Spree's. The apps are ordinary Vite/Next.js projects you own.
By default the stack runs the prebuilt image. To change Ruby code, run
```
spree eject
```
once — compose then builds from
```
server/
```
. If eject fails on a fresh stack with
```
service "web" is not running
```
, the dev server exited because its database didn't exist yet.
```
@spree/cli
```
3.1.0 has this bug. Releases after it build the dev image, start and wait for Postgres, and prepare the database in a one-off container before starting the stack (also on
```
spree init
```
of an ejected project), and they switch older dev compose files to a
```
pg_isready -h 127.0.0.1
```
health check. Bump
```
@spree/cli
```
in
```
package.json
```
and re-run.
Stack: Rails 8.1, Ruby ≥ 3.2; PostgreSQL, MySQL or SQLite. Background jobs run in-process via Solid Queue (Mission Control at
```
/jobs
```
), Solid Cache; Sidekiq/Redis is optional. The dashboard is served at
```
/dashboard
```
by the
```
spree_dashboard
```
gem in production (one image, same origin).
APIs: Store
```
/api/v3/store
```
(publishable key
```
pk_…
```
), Admin
```
/api/v3/admin
```
(secret key
```
sk_…
```
or staff JWT), Seller
```
/api/v3/seller
```
(seller JWT +
```
X-Spree-Seller-Id
```
). See
```
spree-api-v3
```
.

Conventions you should always follow

Namespace under
Spree::
, files under
```
server/app/models/spree/…
```
etc. Your own non-Spree classes can use your app namespace (
```
MyApp::…
```
).
Inherit from
Spree.base_class
(defaults to
```
Spree::Base
```
), not
```
ApplicationRecord
```
. It brings preferences, prefixed IDs, ransack allowlists, document numbers,
```
additional_permitted_attributes
```
.

Users are two classes:

Spree.customer_class

(default

Spree::Customer

, table

spree_customers

cust_…

) and

Spree.admin_user_class

(

Spree::AdminUser

adm_…

). Never hardcode either.

Spree.user_class

is a deprecated alias.

Scope every query through the store:
```
current_store.products
```
,
```
store.orders
```
— never
```
Spree::Order.all
```
in request code. In dev/test
```
SPREE_STORE_SCOPE_GUARD=log|raise|off
```
flags unscoped queries.
Spree::Current
carries per-request
```
store
```
,
```
channel
```
,
```
market
```
,
```
currency
```
,
```
locale
```
.
```
Spree::Current.store
```
falls back to
```
Spree::Store.default
```
, which can be nil (no store flagged default) — set
```
Spree::Current.store = store
```
explicitly in jobs, rake tasks and specs. Assigning it also arms the dev/test
```
StoreScopeGuard
```
for the rest of that job/script, so unscoped queries there get flagged too (wrap deliberately global lookups in
```
Spree::StoreScopeGuard.skip { … }
```
). An installation-wide job (a nightly sweep over every store's records) must run each record in its own store, or its emails, events and store settings come from the default store. Use
```
Spree::Current.with_store(store) { … }
```
, which starts from a clean context and restores the previous one afterwards. Jobs subclassing
```
Spree::BaseJob
```
can call the private
```
each_store_of(relation) { |store_records| … }
```
, which core's own sweeps (stale drafts, expired carts, time-based collections, payouts) use.
No state machines, no enums for lifecycles. Statuses are string
```
status
```
columns declared with
```
has_status
```
(
```
Spree::HasStatus
```
); transitions are workflows (
```
app/workflows
```
). Extend with
```
Model.add_status('on_hold', after: 'approved')
```
— plus your own workflow to move records into it. See
```
spree-workflows
```
.
belongs_to
is required by default — pass
```
optional: true
```
when the FK may be nil, or saves fail with "… must exist". Always pass
```
class_name:
```
and an explicit
```
dependent:
```
on
```
has_many
```
.
No DB foreign keys on business tables; add an index instead. Uniqueness validations are store-scoped in core.
IDs are strings at the API surface — Stripe-style prefixed IDs (
```
prod_…
```
,
```
cart_…
```
,
```
or_…
```
,
```
py_…
```
). Look up with
```
Model.find_by_prefix_id!(id)
```
; never
```
.to_i
```
an ID and never expose integer IDs. Full table:
```
spree-data-model
```
.
Cart ≠ Order.
```
Spree::Cart
```
is mutable checkout state; completing it creates an immutable
```
Spree::Order
```
(
```
status
```
draft/placed/canceled). Code that runs on both reads
```
line_item.owner
```
, not
```
.order
```
.
Custom data: merchant-facing, typed, filterable → custom fields (
```
product.set_custom_field('custom.material', 'Cotton')
```
,
```
get_custom_field
```
). Machine/integration data → metadata
(schemaless JSON, write-only in Store API). A new column only when your own code queries it heavily.
Side effects go in events / hooks, not callbacks. React after the fact with a
```
Spree::Subscriber
```
(
```
order.placed
```
, …); run inside a flow with
```
Spree.hooks.register('carts.complete.validate', …)
```
. Don't add
```
after_save
```
to Spree models.

Writable API attributes:

Spree::Product.additional_permitted_attributes += [:brand_id]

—

+=

, never

<<

(the default is frozen).

Services return results, not exceptions:

result = Spree.cart_add_item_workflow.call(...)

; check

result.success?

Money in the API is a string (
```
"135.60"
```
) with a
```
display_…
```
twin — render the display one.
Secrets go in Rails credentials or env vars; Spree's installation settings are all
```
SPREE_*
```
env vars (see
```
spree-customization
```
). Active Record encryption keys (
```
ACTIVE_RECORD_ENCRYPTION_*
```
) must be set in every environment —
```
create-spree-app
```
generates a dev set;
```
spree encryption init
```
adds one to older projects (see
```
spree-security
```
).

Where customization goes (short version)

Walk this list top-down — higher options are cheaper and survive upgrades better. The

spree-customization

skill has the full decision table.

Store settings (dashboard → Settings; Admin API) — markets, currencies, delivery, taxes, order numbering. Data, not code.
Configuration —
```
SPREE_*
```
env vars /
```
Spree.config
```
; per-record
```
preference
```
s.

Workflow hooks —

Spree.hooks.register('<flow>.<hook>', 'MyApp::Handler')

to veto or extend a core flow (

spree-workflows

Events & subscribers — react after something happened (
```
spree-events-webhooks
```
).

Checkout registry —

Spree::Checkout::Registry.add_requirement

register_step

(

spree-checkout

Providers — tax, delivery rates, fulfillment, search, pricing, inventory, payouts, digital assets, auth (
```
spree-providers
```
).

Ransack allowlists —

Spree.ransack.add_attribute(Spree::Product, :erp_id)

Webhooks — notify external systems without Ruby.

Dependencies — replace a whole workflow/service:

Spree::Dependencies.cart_add_item_workflow = 'MyApp::Carts::AddItem'

(

spree-dependencies

Decorators — last resort, for structural additions (associations, scopes) (
```
spree-decorators
```
).

Admin UI changes happen in the React dashboard via plugins (

spree-dashboard

spree-dashboard-plugins

), not in Rails views.

Common CLI commands

bash

spree dev                      # run API (+ dashboard dev server if apps/dashboard exists); first run completes setup
spree stop | restart | logs [worker]
spree console | shell | db:console
spree migrate | migrate:status | migrate:rollback
spree generate api_resource Brand name:string   # → spree:api_resource
spree generate subscriber ErpSync order.placed   # class + registration in initializers/spree.rb
spree test [path[:line]]      # tests in RAILS_ENV=test; creates the test DB if missing (CLI 3.6+; older: spree rspec)
spree add --gem <gem>         # adds the gem, runs its installer + migrations; a prebuilt project is ejected first (asks; new dev DB)
spree eject                    # build from server/ instead of the prebuilt image
spree build [--production]     # rebuild dev image / build the production image (API + dashboard)
spree add dashboard            # add apps/dashboard (also: spree add seller-dashboard)
spree plugin new <name>        # scaffold a dashboard plugin monorepo
spree update                   # pull latest image, recreate containers (migrations run on boot)
spree upgrade [--plan]         # bundle update + migrate + spree:upgrade data steps
spree seed | sample-data | user create | api-key create|list|revoke
spree encryption init [--print]  # add ACTIVE_RECORD_ENCRYPTION_* keys to .env (never overwrites); --print for production
spree exec bin/rails spree:setup:token  # reprint the first-run admin setup link
spree api <verb> <path>        # call the Admin API from the terminal (see spree-cli)

spree db:reset

is destructive — confirm with the user before running it.

Where to find Spree documentation

Read the installed docs before guessing from training data — they match the installed version:

text

node_modules/@spree/docs/dist/
├── developer/
│   ├── getting-started/  create-spree-app/  cli/
│   ├── core-concepts/    # products, carts, orders, payments, fulfillments, markets, …
│   ├── customization/    # quickstart, configuration, workflows, dependencies, decorators, permissions, validations
│   ├── providers/        # ERP, PIM, DAM, fulfillment, payouts, SSO, observability
│   ├── how-to/           # custom payment method, delivery rate provider, search provider, B2B, marketplace…
│   ├── dashboard/        # React admin: customization, plugins, recipes
│   ├── sdk/  storefront/  multi-tenant/  security/  deployment/  upgrades/  tutorial/
└── api-reference/        # Store/Admin API guides + OpenAPI specs

No local package (classic app)? Use https://spreecommerce.org/docs/llms.txt (index) or append
```
.md
```
to any docs URL.

The Spree docs MCP server (

https://spreecommerce.org/docs/mcp

) searches the latest published docs:

claude mcp add --transport http spree-docs https://spreecommerce.org/docs/mcp

Never use
```
docs/v5/
```
pages for a Spree 6 project.

When in doubt

Which extension pattern? →
```
spree-customization
```
How models relate, which ID prefix, which status values? →
```
spree-data-model
```
New model + API endpoint? →
```
spree-resource
```
Hooks / writing a workflow? →
```
spree-workflows
```

Tests? →

spree-testing

. Upgrading? →

spree-upgrade

spree-upgrade-5-to-6

spree-project

NPX Install

Tags

SKILL.md Content