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 — 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

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:

After Setup

Admin Dashboard

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

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