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.

11.0 KB
Raw Blame
---
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. Include the **Seller Panel**, for marketplaces (default: yes)
3. **Set up AI coding agents** (default: yes) — installs the [Spree agent skills](/developer/agentic/agent-skills), which teach agents how to work with Spree, and connects Claude Code, Cursor and VS Code to the [Spree docs MCP server](/developer/agentic/docs-mcp) so they can search the latest docs
4. **Start Docker services** immediately (default: yes)

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 **admin dashboard** is included in every project (skip it with `--no-dashboard` and the API still serves the built-in one at `/dashboard`). The installer asks whether to add the **seller panel** — a dedicated panel where marketplace vendors manage their products, orders and settings. Answer yes only if you run a marketplace; you can add it later with `spree add seller-dashboard`.

## Prerequisites

- [Node.js](https://nodejs.org/) 20 or later, with npm 9 or later (check with `node -v` and `npm -v`)
- [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-seller-dashboard --no-storefront --no-start
```

| Flag | Description |
|------|-------------|
| `--no-dashboard` | Skip the admin dashboard app — the API still serves the built-in one at `/dashboard` |
| `--seller-dashboard` | Include the marketplace seller panel without asking |
| `--no-seller-dashboard` | Skip the marketplace seller panel |
| `--no-storefront` | Skip Next.js storefront setup |
| `--agent-skills` | Install the Spree agent skills without asking |
| `--no-agent-skills` | Skip installing the Spree agent skills |
| `--docs-mcp` | Connect coding agents to the Spree docs MCP server without asking |
| `--no-docs-mcp` | Skip connecting coding agents to the Spree docs MCP server |
| `--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/
├── 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 (unless --no-dashboard)
│   │   └── .env.local        # Dev proxy target — no credentials
│   ├── seller-dashboard/     # Seller panel, for marketplaces (unless --no-seller-dashboard)
│   └── storefront/           # Next.js storefront (unless --no-storefront)
│       └── .env.local        # API URL + publishable key
├── .env                      # SECRET_KEY_BASE, encryption keys, 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/skills/           # Spree agent skills (unless --no-agent-skills)
├── .mcp.json                 # Spree docs MCP server for Claude Code (unless --no-docs-mcp)
├── .cursor/mcp.json          # …for Cursor
├── .vscode/mcp.json          # …for VS Code (Copilot)
├── AGENTS.md                 # Instructions for coding agents
├── CLAUDE.md                 # Imports AGENTS.md for Claude Code
└── 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 for coding agents (`server/AGENTS.md`, `apps/dashboard/AGENTS.md`).

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

### Spree CLI Commands

The project includes [@spree/cli](/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 Admin Dashboard dev server when `apps/dashboard` exists |
| `spree stop` | Stop backend services |
| `spree upgrade` | Upgrade Spree — the server, database and `@spree/*` packages |
| `spree eject` | Switch from prebuilt image to building from `server/` |
| `spree add dashboard` | Add the Admin Dashboard to an existing project, to customize it |
| `spree add seller-dashboard` | Add the marketplace seller panel to an existing project |
| `spree add ai` | Install the Spree agent skills and connect coding agents to the Spree docs MCP server |
| `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

The dashboard runs as its own dev server: `spree dev` starts it alongside the API at [http://localhost:5173](http://localhost:5173), live-reloading from `apps/dashboard/`. See the [dashboard docs](/developer/dashboard/overview).

No default admin account is created. On the first run, `spree dev` opens a one-time setup link where you create the admin account. If you missed it, print it again with `spree task setup:token`.

### 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
pnpm dev
```

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

## Updating Spree

To update to the latest Spree version:

```bash
spree upgrade
```

This updates the server (the Docker image, or the Spree gems on an ejected project) and the `@spree/*` packages of the project and its dashboard apps, then runs database migrations and data backfills. See [`spree upgrade`](/developer/cli/quickstart#spree-upgrade) for details.

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 Admin 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](/developer/dashboard/deployment).

## Troubleshooting

### `npm ERR! cb.apply is not a function`

Your npm is too old for the Node.js version installed on your machine (npm 6 or earlier running on a newer Node.js). npm crashes while it downloads the installer, before `create-spree-app` starts. This usually happens when an old global npm or a Node.js version manager points at a different version than the one you expect.

Reinstall a current Node.js from [nodejs.org](https://nodejs.org/) or with your version manager (for example `nvm install --lts && nvm use --lts`). It ships with a matching npm. Running `npm install -g npm@latest` usually fails with the same error, because the broken npm runs the upgrade.

If the error remains, clear npm's cache and run the installer again:

```bash
rm -rf ~/.npm/_npx ~/.npm/_cacache
npx create-spree-app@latest my-store
```

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