Skip to main content

​
Quick Start

npx create-spree-app@latest my-store
The CLI walks you through an interactive setup:
  1. Include Next.js Storefront (default: yes)
  2. Optionally load sample data (products, categories, images)
  3. Optionally start Docker services immediately
Once complete, your store is running at http://localhost:3000.

​
Prerequisites

  • Node.js 20 or later
  • Docker (for running the Spree backend, PostgreSQL, and Redis)

​
CLI Flags

All prompts can be skipped with flags for non-interactive (CI/CD) usage: 
npx create-spree-app@latest my-store --no-storefront --no-sample-data --no-start
FlagDescription
--no-storefrontSkip Next.js storefront setup
--no-sample-dataSkip loading sample products and categories
--no-startDon’t start Docker services after scaffolding
--port <number>Port for the Spree backend (default: 3000)
--use-npmUse npm as package manager
--use-yarnUse yarn as package manager
--use-pnpmUse pnpm as package manager
The package manager is auto-detected from how you run the command. If you use pnpm dlx create-spree-app, pnpm will be used automatically.
If the default port is already in use, the CLI will automatically find a free port and let you know.

​
Generated Project Structure

my-store/
├── docker-compose.yml        # Spree backend (prebuilt image) + Postgres + Redis
├── docker-compose.dev.yml    # Alternative: build from local backend/
├── .env                      # SECRET_KEY_BASE, SPREE_PORT
├── .gitignore
├── package.json              # Convenience scripts
├── README.md
├── backend/                  # Full Rails app (from spree/spree-starter)
│   ├── Gemfile
│   ├── Dockerfile
│   ├── config/
│   ├── app/
│   └── ...
└── apps/
    └── storefront/           # Next.js storefront (unless --no-storefront)
        ├── .env.local        # API URL + API key
        └── ...

​
What’s in docker-compose.yml

  • Spree — runs the ghcr.io/spree/spree:latest image on the configured port (default 3000)
  • PostgreSQL 18 — database with persistent volume
  • Redis 7 — caching, background jobs, and Action Cable
  • Mailpit — local email inbox at http://localhost:8025
  • Health checks on all services

​
Customizing the Backend

The backend/ directory contains a full Rails application with Spree installed (cloned from spree-starter). By default, the project uses a prebuilt Docker image. To switch to building from your local backend: 
npx spree eject
This replaces docker-compose.yml with a version that builds from backend/, rebuilds the image, and restarts services. You can then:
  • Add gems to backend/Gemfile
  • Override models with decorators in backend/app/models/
  • Add controllers in backend/app/controllers/
  • Configure Spree in backend/config/initializers/spree.rb
  • Add migrations with cd backend && bin/rails generate migration
See the Customization Guide for more details.

​
Spree CLI Commands

The project includes @spree/cli for managing your Spree backend:
CommandDescription
spree devStart backend services and stream logs
spree stopStop backend services
spree updatePull latest Spree image and restart (runs migrations automatically)
spree ejectSwitch from prebuilt image to building from backend/
spree logsView backend logs
spree logs workerView background jobs logs
spree consoleRails console

​
After Setup

​
Admin Dashboard

Open http://localhost:3000/admin and log in with:
Emailspree@example.com
Passwordspree123

​
Store API

The REST API is available at http://localhost:3000/api/v3/store. See the API Reference for details.

​
Storefront

If you included the storefront, start it in a separate terminal: 
cd my-store/apps/storefront
npm run dev
Open http://localhost:3001 to see your store.

​
Updating Spree

To update to the latest Spree version: 
spree update
This pulls the latest Docker image and recreates the containers. The entrypoint automatically runs database migrations. To pin a specific version, edit SPREE_VERSION_TAG in .env: 
SPREE_VERSION_TAG=5.4

​
Next Steps

Next.js Storefront

Customize and extend the Storefront

Spree SDK

TypeScript SDK for the Store and Admin APIs

API Reference

Explore the REST API endpoints

Core Concepts

Learn about Spree’s architecture