create-spree-app - Spree Commerce documentation

Quick Start

npx create-spree-app@latest my-store

The CLI walks you through an interactive setup:

Include Next.js Storefront (default: yes)
Optionally load sample data (products, categories, images)
Optionally start Docker services immediately

Once complete, your store is running at http://localhost:3000 — setup pulls the latest Spree image, seeds the database, and configures API keys, then prints a summary with your admin credentials and keys. If you skipped starting services, the first pnpm dev completes setup automatically. The admin dashboard is included in every project (skip it with --no-dashboard and the API still serves the built-in one at /dashboard). The installer asks whether to add the seller panel — a dedicated panel where marketplace vendors manage their products, orders and settings. Answer yes only if you run a marketplace; you can add it later with spree add seller-dashboard.

Prerequisites

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

CLI Flags

All prompts can be skipped with flags for non-interactive (CI/CD) usage:

npx create-spree-app@latest my-store --no-seller-dashboard --no-storefront --no-start

Flag	Description
`--no-dashboard`	Skip the admin dashboard app — the API still serves the built-in one at `/dashboard`
`--seller-dashboard`	Include the marketplace seller panel without asking
`--no-seller-dashboard`	Skip the marketplace seller panel
`--no-storefront`	Skip Next.js storefront setup
`--no-start`	Don’t start Docker services after scaffolding
`--port <number>`	Port for the Spree backend (default: `3000`)
`--use-npm`	Use npm as package manager
`--use-yarn`	Use yarn as package manager
`--use-pnpm`	Use 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/
├── server/                   # The Spree API — a full Rails app from spree/spree-starter
│   ├── app/                  # Your models, controllers, serializers and jobs
│   ├── config/
│   ├── Dockerfile            # Also builds the production image (API + dashboard)
│   └── Gemfile
├── apps/
│   ├── dashboard/            # Admin dashboard (unless --no-dashboard)
│   │   └── .env.local        # Dev proxy target — no credentials
│   ├── seller-dashboard/     # Seller panel, for marketplaces (unless --no-seller-dashboard)
│   └── storefront/           # Next.js storefront (unless --no-storefront)
│       └── .env.local        # API URL + publishable key
├── .env                      # SECRET_KEY_BASE, encryption keys, SPREE_PORT, SPREE_VERSION_TAG, SPREE_SAMPLE_DATA
├── .spree/                   # CLI credentials — gitignored, created on first run
├── docker-compose.yml        # Spree backend (prebuilt image) + Postgres + Meilisearch
├── docker-compose.dev.yml    # Alternative: build from local server/
├── render.yaml               # Render Blueprint — one Docker service built from this repo
├── .dockerignore             # Keeps the production build context to sources
├── .gitignore
├── package.json              # Scripts and the pinned @spree/cli
├── AGENTS.md                 # Instructions for coding agents
├── CLAUDE.md                 # Project layout and conventions
└── README.md                 # How to run everything

server/ is the only part that is Spree’s. The apps under apps/ are ordinary Vite and Next.js projects you own — restyle, restructure or replace them without forking anything. Each carries its own instructions (server/CLAUDE.md, apps/dashboard/AGENTS.md), which is also what a coding agent reads.

What’s in docker-compose.yml

Spree — one web container running the ghcr.io/spree/spree:latest image on the configured port (default 3000); background jobs run in-process via Solid Queue (stored in Postgres — job dashboard at /jobs)
PostgreSQL 18 — database with persistent volume
Meilisearch — search engine
Health checks on postgres, meilisearch, and web

Customizing the Spree API

The server/ directory is the Spree API — a full Rails application with Spree installed (cloned from spree-starter) serving the Store and Admin APIs your storefront and dashboard talk to, plus background jobs and transactional emails. By default, the project runs it from a prebuilt Docker image. To switch to building from your local copy:

npx spree eject

This replaces docker-compose.yml with a version that builds from server/, rebuilds the image, and restarts services. You can then:

Add gems to server/Gemfile
Override models with decorators in server/app/models/
Add controllers in server/app/controllers/
Configure Spree in server/config/initializers/spree.rb
Add migrations with spree generate migration AddFooToSpreeBars foo:string (runs inside the container)

See the Customization Guide for more details.

Spree CLI Commands

The project includes @spree/cli for managing your Spree backend:

Command	Description
`spree dev`	Run the app in the foreground — streams logs, Ctrl+C stops it. First run completes setup automatically; co-runs the Admin Dashboard dev server when `apps/dashboard` exists
`spree stop`	Stop backend services
`spree upgrade`	Upgrade Spree — the server, database and `@spree/*` packages
`spree eject`	Switch from prebuilt image to building from `server/`
`spree add dashboard`	Add the Admin Dashboard to an existing project, to customize it
`spree add seller-dashboard`	Add the marketplace seller panel to an existing project
`spree build --production`	Build the production image — the Spree API plus your dashboard, in one
`spree logs`	View backend logs
`spree logs worker`	View background jobs logs
`spree console`	Rails console

After Setup

Admin Dashboard

The dashboard runs as its own dev server: spree dev starts it alongside the API at http://localhost:5173, live-reloading from apps/dashboard/. See the dashboard docs. No default admin account is created. On the first run, spree dev opens a one-time setup link where you create the admin account. If you missed it, print it again with spree rails spree:setup:token.

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
pnpm dev

Open http://localhost:3001 to see your store.

Updating Spree

To update to the latest Spree version:

spree upgrade

This updates the server (the Docker image, or the Spree gems on an ejected project) and the @spree/* packages of the project and its dashboard apps, then runs database migrations and data backfills. See spree upgrade for details. To pin a specific version, edit SPREE_VERSION_TAG in .env:

SPREE_VERSION_TAG=5.4

Deployment

The project deploys as one image: server/Dockerfile builds the Spree API together with your Admin Dashboard (when apps/dashboard exists), served same-origin at /dashboard — no CORS, no cookie configuration, no second service.

Render — the render.yaml at the project root is a ready Blueprint: one Docker service built straight from your repo, migrations run on boot.
Anywhere else — spree build --production builds the same image locally; push it to a registry and run it on any Docker host.

See the Deployment Guide and the dashboard deployment docs.

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

​Quick Start

​Prerequisites

​CLI Flags

​Generated Project Structure

​What’s in docker-compose.yml

​Customizing the Spree API

​Spree CLI Commands

​After Setup

​Admin Dashboard

​Store API

​Storefront

​Updating Spree

​Deployment

​Next Steps

Next.js Storefront

Spree SDK

API Reference

Core Concepts

Quick Start

Prerequisites

CLI Flags

Generated Project Structure

What’s in docker-compose.yml

Customizing the Spree API

Spree CLI Commands

After Setup

Admin Dashboard

Store API

Storefront

Updating Spree

Deployment

Next Steps