Skip to main content
This tutorial walks you through creating a complete Spree feature from scratch: a “Brands” feature that lets admins manage Product brands, exposes them through the Store API, and consumes them from TypeScript. It’s written for both backend and frontend developers. The Ruby you’ll write is minimal and mostly generated — Spree’s generators produce convention-correct models, admin UIs, and API endpoints, and the TypeScript SDK gives you typed access from your storefront. You don’t need to be a Rails expert to follow along.

​
Before you start

You need a running Spree app. The fastest path is create-spree-app — a Docker-based project with the Spree CLI, no local Ruby required: 
npx create-spree-app@latest my-store
An existing app with Spree gems works just as well. Every command in this tutorial is shown in two forms — Spree CLI (runs inside Docker) and Without Spree CLI (runs directly on your machine) — pick the tab that matches your setup and ignore the other.
create-spree-app projects: run spree eject once before starting. Fresh projects use a prebuilt Docker image; ejecting switches to the dev setup that mounts backend/ into the container, so the files the generators create land in your project (and reload live 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 Agentic Development.

​
What you’ll build

  • A Brand model with a rich text description and an uploadable logo — one generator command
  • An admin UI for managing brands — one generator command, then customized
  • A brand association on Products, surfaced in the product admin form
  • Store API endpoints (GET /api/v3/store/brands) with serializers and prefixed IDs
  • Typed TypeScript access to brands from your storefront via @spree/sdk
  • Event subscribers and webhooks connecting the store to external systems
  • Automated tests for all of it

​
Tutorial Sections

1. Model

Generate the Brand model — columns, rich text description, and logo upload in one command

2. Admin Dashboard

Scaffold the admin UI, then add the description editor, logo upload, and table columns

3. Extending Core Models

Connect Brands to Products using a decorator and an association

4. API

Expose Brands through the Store and Admin APIs — generated in one command, or hand-built to learn the pieces

5. Events & Webhooks

React to store activity and connect external systems — OMS, warehouse, ERP

6. SDK

Consume Brand endpoints from TypeScript using the SDK

7. Testing

Write automated tests for your feature