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 React Dashboard (Developer Preview of the next-generation admin) is available with the --react-dashboard flag, or later via spree add 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-storefront --no-sample-data --no-start

Flag	Description
`--react-dashboard`	Include the React Dashboard (Developer Preview — also available later via `spree add dashboard`)
`--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/
├── docker-compose.yml        # Spree backend (prebuilt image) + Postgres + Meilisearch
├── docker-compose.dev.yml    # Alternative: build from local backend/
├── render.yaml               # Render Blueprint — one Docker service built from this repo
├── .env                      # SECRET_KEY_BASE, SPREE_PORT, SPREE_VERSION_TAG, SPREE_SAMPLE_DATA
├── .dockerignore             # Keeps the production build context to sources
├── .gitignore
├── package.json              # Convenience scripts
├── README.md
├── backend/                  # Full Rails app — the Spree API (from spree/spree-starter)
│   ├── Gemfile
│   ├── Dockerfile            # Also builds the production image (API + dashboard)
│   ├── config/
│   ├── app/
│   └── ...
└── apps/
    ├── storefront/           # Next.js storefront (unless --no-storefront)
    │   ├── .env.local        # API URL + API key
    │   └── ...
    └── dashboard/            # React Dashboard (with --react-dashboard)
        ├── .env.local        # Dev proxy target — no credentials
        └── ...

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 backend/ 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 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 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 `backend/`
`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`

With --react-dashboard, the React Dashboard’s dev server is the admin instead: spree dev starts it alongside the API at http://localhost:5173 — same credentials, live-reloading from apps/dashboard/ (the classic admin remains at /admin). See the React 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: backend/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