Skip to main content
This tutorial builds one complete feature — Brands, a manufacturer or label attached to products — through every layer of a Spree application. By the end you will have a custom model with its own Store and Admin API, brand management in the dashboard, brands rendered on the storefront, other systems reacting to brand changes, and tests covering all of it. It is written for both backend and frontend developers. The backend code you write is minimal and mostly generated — Spree’s generators produce convention-correct models, controllers and serializers, and the TypeScript SDK gives you typed access from your storefront. Most of what you write by hand is TypeScript.

​
What you’ll build

  • A Spree::Brand model with a Store API and an Admin API — one generator command
  • A brands screen in the dashboard: a list page, navigation and a card on the product page
  • Brands on the storefront, fetched through @spree/sdk with generated types
  • Lifecycle events other systems subscribe to, in the app or over webhooks
  • Specs for the model and both APIs, plus an end-to-end pass

​
The five steps

1. Models & API

Generate the model, migration, Store and Admin controllers, serializers and routes in one command

2. Dashboard

Scaffold the back-office UI with the CLI — a table, a form, navigation and a product slot

3. Storefront

Regenerate SDK types and render brands on the product page in the Next.js storefront

4. Events

Publish lifecycle events and consume them with subscribers and outbound webhooks

5. Testing

Model and request specs, dashboard plugin tests, and one end-to-end check
The order is deliberate. Step 1 gives every later step something real to talk to: the dashboard plugin calls the Admin API, the storefront calls the Store API, and the events in step 4 reuse the serializer the same generator produced.

​
Before you start

You need a running Spree application. The fastest path is create-spree-app, a Docker-based project with the Spree CLI and nothing to install locally:
Every command in this tutorial runs from the root of that project, through the spree CLI. Nothing needs installing on your machine — the CLI routes each command into the right container. The project it creates has this shape, and the paths in every chapter are relative to its root:
create-spree-app projects: run spree eject once before starting. Fresh projects use a prebuilt Docker image; ejecting switches to the development setup that mounts your app into the container, so the files the generators create land in your project and reload as you edit them.
Using an AI coding agent? Install the Spree agent skills (npx skills add spree/agent-skills) and connect the docs MCP server before starting. Your agent will know the conventions this tutorial teaches and can follow along with you. See AI-assisted development.