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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
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>