> ## Documentation Index > Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt > Use this file to discover all available pages before exploring further. # create-spree-app > 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 theme={"theme":"night-owl"} 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 theme={"theme":"night-owl"} 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 ` | 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 | 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. If the default port is already in use, the CLI will automatically find a free port and let you know. ## Generated Project Structure ```text theme={"theme":"night-owl"} 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 theme={"theme":"night-owl"} 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](/docs/developer/customization) for more details. ### Spree CLI Commands The project includes [@spree/cli](/docs/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** | `spree@example.com` | | **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](/docs/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](/docs/api-reference) for details. ### Storefront If you included the storefront, start it in a separate terminal: ```bash theme={"theme":"night-owl"} 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 theme={"theme":"night-owl"} 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](/docs/developer/deployment) and the [dashboard deployment docs](/docs/developer/dashboard/deployment). ## Next Steps Customize and extend the Storefront TypeScript SDK for the Store and Admin APIs Explore the REST API endpoints Learn about Spree's architecture