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 dashboard and the marketplace seller panel are included in every project — there is no flag to add them.

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-storefront --no-sample-data --no-start

Flag	Description
`--react-dashboard`	No-op — the dashboard is always included. Kept so existing scripts keep working
`--no-storefront`	Skip Next.js storefront setup
`--no-sample-data`	Skip loading sample products and categories
`--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 (React)
│   │   └── .env.local        # Dev proxy target — no credentials
│   ├── seller-dashboard/     # Seller panel, for marketplaces (React)
│   └── storefront/           # Next.js storefront (unless --no-storefront)
│       └── .env.local        # API URL + publishable key
├── .env                      # SECRET_KEY_BASE, 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 React Dashboard dev server when `apps/dashboard` exists
`spree stop`	Stop backend services
`spree update`	Pull latest Spree image and restart (runs migrations automatically)
`spree eject`	Switch from prebuilt image to building from `server/`
`spree add dashboard`	Add the React Dashboard 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

Open http://localhost:3000/admin and log in with:


Email	`spree@example.com`
Password	`spree123`

The dashboard runs as its own dev server: spree dev starts it alongside the API at http://localhost:5173, with the same credentials, live-reloading from apps/dashboard/. See the dashboard docs.

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

Deployment

The project deploys as one image: server/Dockerfile builds the Spree API together with your React 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