---
title: "create-spree-app"
sidebarTitle: create-spree-app
description: "Scaffold a new Spree Commerce project with a single command — bootstraps a full Rails backend, Docker dev stack, and the @spree/cli for customization."
---

## Quick Start

```bash
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](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](https://nodejs.org/) 20 or later
- [Docker](https://docs.docker.com/get-docker/) (for running the Spree backend, PostgreSQL, and Meilisearch)

## CLI Flags

All prompts can be skipped with flags for non-interactive (CI/CD) usage:

```bash
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 |

> **TIP:** 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.

> **TIP:** If the default port is already in use, the CLI will automatically find a free port and let you know.

## Generated Project Structure

```text
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](https://github.com/spree/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:

```bash
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](../customization.md) for more details.

### Spree CLI Commands

The project includes [@spree/cli](../cli/quickstart.md) 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](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](http://localhost:5173), with the same credentials, live-reloading from `apps/dashboard/`. See the [dashboard docs](../dashboard/overview.md).

### Store API

The REST API is available at [http://localhost:3000/api/v3/store](http://localhost:3000/api/v3/store). See the [API Reference](/api-reference) for details.

### Storefront

If you included the storefront, start it in a separate terminal:

```bash
cd my-store/apps/storefront
npm run dev
```

Open [http://localhost:3001](http://localhost:3001) to see your store.

## Updating Spree

To update to the latest Spree version:

```bash
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](../deployment.md) and the [dashboard deployment docs](../dashboard/deployment.md).

## Next Steps


  - [Next.js Storefront](../storefront/nextjs/quickstart.md) — Customize and extend the Storefront
  - [Spree SDK](../sdk/quickstart.md) — TypeScript SDK for the Store and Admin APIs
  - [API Reference](/api-reference) — Explore the REST API endpoints
  - [Core Concepts](../core-concepts/architecture.md) — Learn about Spree's architecture