Quick Start
npx create-spree-app@latest my-store
- Choose Full-stack (Backend + Next.js Storefront) or Backend only
- Optionally load sample data (products, categories, images)
- 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 and PostgreSQL)
Setup Modes
Full-stack (default)
Sets up both the Spree backend (Docker) and a Next.js storefront with the Spree SDK pre-configured.
npx create-spree-app@latest my-store
apps/storefront/. The CLI automatically:
- Installs storefront dependencies
- Fetches a Store API key from the running backend
- Writes the API key to the storefront’s
.env.local
Backend only
Skips the storefront — just the Spree backend and PostgreSQL via Docker. Ideal when you’re building a custom frontend or only need the API.
npx create-spree-app@latest my-store --backend-only
CLI Flags
All prompts can be skipped with flags for non-interactive (CI/CD) usage:
npx create-spree-app@latest my-store --backend-only --no-sample-data --no-start
| Flag | Description |
|---|
--backend-only | Skip 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 + PostgreSQL
├── .env # Backend environment variables
├── .gitignore
├── package.json # Convenience scripts
├── README.md
└── apps/
└── storefront/ # Next.js 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 17 — database with persistent volume
- Health checks on both services
Spree CLI Commands
The project includes @spree/cli for managing your Spree backend:
| Command | Description |
|---|
spree start | Start backend services and stream logs |
spree stop | Stop backend services |
spree down | Stop and remove backend services |
spree update | Pull latest Spree image and restart (runs migrations automatically) |
spree logs | View backend logs |
spree logs:worker | View background jobs logs |
spree console | Rails console |
spree seed | Re-seed the database |
spree load-sample-data | Load sample products, categories, and images |
After Setup
Admin Dashboard
Open http://localhost:3000/admin and log in with:
| |
|---|
| Email | spree@example.com |
| Password | spree123 |
Store API
The REST API is available at http://localhost:3000/api/v3/store. See the API Reference for details.
Storefront (full-stack mode)
If you chose full-stack mode, start the storefront in a separate terminal:
cd my-store/apps/storefront
npm run dev
Manual Start
If you used --no-start, start services manually:
Wait for Spree to be healthy, then optionally load sample data:
Spree CLI
You can also use the Spree CLI directly for additional commands:
spree user create # Create an admin user
spree api-key create # Create an API key
spree api-key list # List API keys
Updating Spree
To update to the latest Spree version:
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:
Next Steps
