create-spree-app

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

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
• 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:

After Setup

Admin Dashboard

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

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