Agent Skill · Spree Commerce

spree-project

Use when the user is working on a Spree Commerce project — anything involving Spree models, controllers, customization patterns (decorators, subscribers, services), Spree conventions like prefixed IDs / Spree::Model namespacing / Spree.user_class / Spree::Current, or asking how Spree works. Activates broadly for any task in a Spree backend.

View SKILL.md on GitHub → Source repository Provider profile
Provider: Spree Commerce Path in repo: skills/spree-project/SKILL.md

Skill body

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:

Signal Flavor How commands run
backend/Gemfile mentions spree + docker-compose.yml at root create-spree-app project (5.4+) spree <cmd> — the @spree/cli routes into the Docker web container
Rails app at root (config/application.rb, Gemfile with spree) + docker-compose.yml with a Spree image/build spree-starter-style Docker app spree <cmd> if the CLI resolves (npx spree --version); else docker compose exec web <cmd>
Rails app at root with spree gems, no Docker wiring classic Rails app (typical pre-5.4) Native, from the app root: bin/rails …, bundle exec rake …

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

Task Spree CLI (Docker) Classic Rails app
Boot for development spree dev bin/dev (or bin/rails server)
Rails console spree console bin/rails console
Install + run migrations spree migrate bin/rake spree:install:migrations && bin/rails db:migrate
Version upgrade spree upgrade bundle update <spree gems>, migrations, then bin/rake spree:upgrade
Run a generator spree generate api_resource … bin/rails g spree:api_resource … (spell the spree: prefix yourself — auto-prefixing is a CLI feature)
Any rake task spree rake <task> bundle exec rake <task>
Seeds / sample data spree seed / spree sample-data bin/rails db:seed / bin/rails spree:load_sample_data
Arbitrary command spree exec <cmd> just run <cmd>

Other flavor differences:

create-spree-app project layout

Directory Description
backend/ The Rails app — Spree mounted as an engine
apps/storefront/ Optional Next.js storefront
node_modules/@spree/docs/dist/ Local copy of Spree developer docs

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

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