Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

8.0 KB
Raw Blame
---
title: "create-spree-app"
sidebarTitle: Overview
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."
canonical: "https://spreecommerce.org/docs/developer/create-spree-app/quickstart"
---

## 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 **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](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` | 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 |

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

<Tip>
  If the default port is already in use, the CLI will automatically find a free port and let you know.
</Tip>

## Generated Project Structure

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

### Spree CLI Commands

The project includes [@spree/cli](/v5/developer/cli/quickstart) 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](http://localhost:3000/admin) and log in with:

| | |
|---|---|
| **Email** | `[email protected]` |
| **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](http://localhost:5173) — same credentials, live-reloading from `apps/dashboard/` (the classic admin remains at `/admin`). See the [React Dashboard docs](/v5/developer/dashboard/overview).

### 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**: `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](/developer/deployment) and the [dashboard deployment docs](/v5/developer/dashboard/deployment).

## Next Steps

<CardGroup cols={2}>
  <Card title="Next.js Storefront" icon="react" href="/developer/storefront/nextjs/quickstart">
    Customize and extend the Storefront
  </Card>
  <Card title="Spree SDK" icon="code" href="/developer/sdk/quickstart">
    TypeScript SDK for the Store and Admin APIs
  </Card>
  <Card title="API Reference" icon="book" href="/api-reference">
    Explore the REST API endpoints
  </Card>
  <Card title="Core Concepts" icon="brain" href="/developer/core-concepts/architecture">
    Learn about Spree's architecture
  </Card>
</CardGroup>