Adding a Spree Resource

Commands below use the Spree CLI form (spree …, Docker). On a classic Rails app without the CLI (typical pre-5.4), use the native mapping in the spree-project skill — bin/rails / bundle exec rake from the app root, paths without the backend/ prefix.

To add a new model that’s exposed via the Spree v3 API, use the spree:api_resource generator. One command produces:

• The model (in backend/app/models/spree/<name>.rb)
• The migration
• Store + Admin API controllers
• Store + Admin serializers
• FactoryBot factory
• Controller specs covering full CRUD
• Routes (injected into spree/api/config/routes.rb)

Prerequisite: run spree eject first — the generator executes inside the Docker container, and only the ejected dev compose bind-mounts ./backend, so generated files appear (and persist) on your host.

The one-command path

spree generate api_resource Brand name:string:uniq active:boolean --writable

Field syntax follows Rails’ attribute parser, with Spree extensions:

Example field specs:

name:string:uniq               # unique non-null string with index + validator
description:text               # non-null text column
active:boolean                 # non-null boolean
price:decimal                  # non-null decimal
brand:belongs_to               # association to Spree::Brand (class auto-resolved from the attribute name; use brand:belongs_to{OtherClass} for an explicit, unqualified class hint)

Flags

What gets created

For spree generate api_resource Brand name:string:uniq active:boolean --writable:

backend/app/models/spree/brand.rb                                 (owned-once)
backend/db/migrate/<ts>_create_spree_brands.rb                    (append-only)
backend/app/controllers/spree/api/v3/store/brands_controller.rb   (managed)
backend/app/controllers/spree/api/v3/admin/brands_controller.rb   (managed)
backend/app/serializers/spree/api/v3/brand_serializer.rb          (managed)
backend/app/serializers/spree/api/v3/admin/brand_serializer.rb    (managed)
backend/spec/factories/spree/brand_factory.rb                     (managed)
backend/spec/controllers/spree/api/v3/store/brands_controller_spec.rb (managed)
backend/spec/controllers/spree/api/v3/admin/brands_controller_spec.rb (managed)
<spree_api gem>/config/routes.rb                                  (idempotent inject — resolved via the installed gem, not under backend/; skipped with a warning if the gem path is read-only)

The “owned-once / managed-forever / append-only” contract

• Model file (owned-once) — the generator writes it once. Once it exists, the generator never touches it again. Your domain logic (validations, scopes, callbacks, custom methods) lives here and stays yours.
• Migration (append-only) — generated once at resource creation. To change the schema later, add a separate migration: spree rails g migration AddFooToBar foo:string.
• Controllers, serializers, specs, factory (managed) — the generator overwrites these on re-run. If you customize them by hand, your changes get wiped next time you regenerate. Re-runs are idempotent — Thor’s identical check leaves bytes-equal files alone.
• Routes (idempotent inject) — added between # BEGIN spree:api_resource managed routes and # END sentinel markers. Re-runs don’t duplicate.

After running the generator

The summary panel at the end of generator output lists the next steps:

1. Review the generated model — add validations, scopes, callbacks, custom methods that are specific to your resource.
2. Apply the migration — spree migrate.
3. Set up authorization — the generator can’t infer who’s allowed to access the resource under what conditions. Add CanCanCan rules in backend/app/models/spree/permission_sets/ or backend/config/initializers/spree.rb so the resource’s API surface actually returns data.
4. Decide store-scoping — if the resource should be scoped to a Store (most catalog data is), add has_many :brands on Spree::Store and override the controller’s scope method.
5. Run the specs — spree exec bundle exec rspec spec/controllers/spree/api/v3/. The generated specs cover happy paths; add edge cases as you go.

TypeScript types

The Lefthook pre-commit pipeline that regenerates packages/sdk / packages/admin-sdk TypeScript types and Zod schemas applies only when developing inside the spree monorepo itself (its hook watches spree/api/app/serializers/**/*.rb). In a CLI-created project, serializers you generate are app-local — they don’t appear in the published @spree/sdk / @spree/admin-sdk types, so type your custom resources by hand in your storefront/admin client code. (The published SDK types are emitted as TypeScript interfaces, so for fields you add to existing Spree resources you can use declaration merging — declare module '@spree/sdk' { interface Product { ... } } — but brand-new resources need their own hand-written types.)

Common patterns

Read-only catalog resource (the default):

spree generate api_resource Brand name:string:uniq active:boolean

Customers can GET via Store API; admins have full CRUD via Admin API.

Writable customer-facing resource (rare, but real — e.g. saved addresses):

spree generate api_resource SavedAddress label:string user:belongs_to --writable

Admin-only resource (back-office data):

spree generate api_resource AuditLog action:string details:text --no-store

Soft-delete with custom fields (e.g. a Vendor with metadata):

spree generate api_resource Vendor name:string:uniq slug:string:uniq --paranoid --metafields

Model only — no API surface

If you want a Spree model but no Store/Admin API (internal-only record, supporting model, lookup table), use the spree:model generator directly. It produces the model file + migration with all the Spree conventions baked in — no controllers, serializers, or routes. Unlike spree:api_resource (which strips Rails’ test-framework hooks), spree:model keeps them — and spree-starter apps configure rspec + factory_bot as generator hooks out of the box (via config/initializers/spree_dev_tools.rb), so you’ll also get a stub model spec and factory, as with any rails g model.

spree generate spree:model Brand name:string:uniq active:boolean

The spree:model generator is what spree:api_resource inherits from; running it standalone is the right choice when:

• The record is internal-only (event log, audit trail, internal join table)
• The record is exposed only through a parent’s API (e.g. BrandImage accessed via brand.images, not directly)
• You want to write controllers and serializers by hand (custom auth, non-RESTful shape)
• You’re scaffolding a model that will be associated with an existing Spree class via decorator (see the spree-decorators skill)

What it produces

For spree generate spree:model Brand name:string:uniq active:boolean:

backend/app/models/spree/brand.rb                   (owned-once)
backend/db/migrate/<ts>_create_spree_brands.rb      (append-only)
backend/spec/models/spree/brand_spec.rb             (stub, via Rails' test_framework hook)
backend/spec/factories/spree/brands.rb              (stub, via the fixture_replacement hook)

The model has:

• class Brand < Spree.base_class (the swappable base lookup, not hardcoded)
• has_prefix_id :brand (auto-derived from class name, override with --id-prefix)
• null: false on every column in the migration
• No foreign key constraints (Spree convention)
• Uniqueness validation scoped to spree_base_uniqueness_scope for any :uniq field
• Ransack allowlist set to the generated attributes (empty _associations and _scopes arrays for you to fill in)

Flags

The spree:model generator accepts the same Spree-specific flags as api_resource:

Plus everything Rails’ built-in model generator accepts (column types, indexes, references, etc.).

When to upgrade to spree:api_resource

If you later decide the model needs API access, run spree generate api_resource Brand … — the generator detects the existing model file and won’t overwrite it. It’ll generate the controllers, serializers, factory, specs, and routes around your hand-managed model.