spree-setup

name	spree-setup
description	Bootstrap a new Spree project — `create-spree-app` CLI (v5.2+), `spree-starter` Rails backend, the Next.js storefront repo, `bin/rails g spree:install`, sample data, Docker Compose, and the PostgreSQL + Redis + Sidekiq prerequisites. Use when starting a new Spree project from scratch or onboarding an existing repo.
allowed-tools	Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch

Spree Setup

Before writing code

Fetch live docs:

1. Fetch https://spreecommerce.org/docs/developer/cli/quickstart for the current create-spree-app flags and Node/Ruby version requirements.
2. Fetch https://github.com/spree/spree-starter (README) for the Rails-backend starter setup.
3. Fetch https://github.com/spree/storefront (README) for the Next.js storefront prerequisites.
4. Web-search the latest release tag at https://github.com/spree/spree/releases — confirm the current minor version and matching spree-starter / storefront branch.
5. Check the v5.2 announcement (https://spreecommerce.org/announcing-spree-5-2/) for CLI changes if working on an older project.

Conceptual Architecture

Two Repos, One Project

A modern Spree project typically combines:

1. spree-starter (Rails 7+) — the backend application running the spree umbrella gem, admin, APIs, webhooks
2. storefront (Next.js 16+) — the headless storefront talking to the Rails backend over API v3

The create-spree-app CLI scaffolds both. Older projects often have only the Rails app — the headless storefront is opt-in.

Prerequisites

• Ruby 3.2+, Rails 7.1+ (verify against the Spree version's Gemfile)
• Node 20+ (for the storefront and admin asset pipeline)
• PostgreSQL 14+ (MySQL works but Postgres is the recommended path)
• Redis 7+ (Sidekiq, cache, Action Cable)
• ImageMagick or libvips for image processing
• MeiliSearch (optional, for v5.4+ faceted catalog)

What spree:install Does

The Spree installer initializes:

• Database migrations for all Spree tables
• Default admin user (prompts for email/password)
• Routes mounted at /admin, /api/v3/, /api/v2/ (legacy via gem)
• Default Store, Country, Zone, ShippingMethod, PaymentMethod, TaxRate
• Spree initializers (config/initializers/spree.rb)
• Optional sample data (spree_sample:load)

Bootstrap Sequences

Path A — create-spree-app (recommended in v5.2+):

npx create-spree-app@latest my-store
cd my-store
# Follow prompts: backend? storefront? Docker? sample data?

Path B — Clone spree-starter directly:

git clone https://github.com/spree/spree-starter my-store
cd my-store
docker compose up -d        # PostgreSQL + Redis + MeiliSearch
bin/setup                    # bundle install, db:create, db:migrate, spree:install

Path C — Add Spree to an existing Rails app:

bundle add spree
bundle add spree_admin       # optional: admin dashboard
bundle add spree_emails      # optional: transactional emails
bin/rails g spree:install
bin/rails db:migrate

Adding the Next.js Storefront

git clone https://github.com/spree/storefront my-storefront
cd my-storefront
cp .env.example .env.local
# Set SPREE_API_URL and NEXT_PUBLIC_SPREE_PUBLISHABLE_KEY
npm install
npm run dev   # http://localhost:3000

The publishable key (pk_…) comes from your Spree admin → Settings → API Keys.

Sample Data

bin/rails spree_sample:load

Loads ~25 demo products, taxonomies, payment methods, shipping methods. Idempotent unless --force. Useful for dev, never run in production.

Docker Compose (from spree-starter)

The starter ships a docker-compose.yml with:

• db — PostgreSQL 16
• redis — Redis 7
• meilisearch — MeiliSearch v1 (v5.4+)
• web — Puma serving the Rails app
• sidekiq — background job worker

Environment Variables

Var	Purpose
DATABASE_URL	Postgres connection string
REDIS_URL	Redis connection (used by Sidekiq, cache, Action Cable)
SECRET_KEY_BASE	Rails session/cookie signing key
RAILS_MASTER_KEY	For config/credentials.yml.enc
MEILISEARCH_HOST, MEILISEARCH_API_KEY	v5.4+ search backend
SPREE_API_URL	Storefront's URL to hit the Rails backend
NEXT_PUBLIC_SPREE_PUBLISHABLE_KEY	Public publishable key (pk_…) for the storefront

Setup Decision Checklist

• Spree version — pin to the latest stable (verify on releases page); v5.4+ for API v3 + Payment Sessions + @spree/sdk.
• Storefront — Next.js (recommended), Rails storefront (spree-rails-storefront), or headless-only (API-only deployment)?
• Payment gateway — Stripe (spree_stripe), Adyen (spree_adyen), PayPal (spree_paypal_checkout)?
• Search — MeiliSearch (v5.4+ default), Algolia (community gem), or Postgres full-text only?
• Auth — Devise (in-core v5+; never re-add the archived spree_auth_devise)? OAuth providers?
• Multi-store — single store or multi-store from day one?

Common Setup Failures

• bin/setup fails on spree:install: missing imagemagick / libvips. Install OS dependency.
• pg gem fails to build: install libpq-dev (Debian) or postgresql@16 headers (macOS).
• Storefront 401s against API: publishable key not set, or storefront pointed at the wrong SPREE_API_URL.
• MeiliSearch connection refused: starter expects MeiliSearch on http://meilisearch:7700 in Docker; on bare-metal, set MEILISEARCH_HOST=http://localhost:7700.
• Admin login 500s: missing RAILS_MASTER_KEY — set the env var or recreate credentials.

Always re-verify against the live spree-starter README — bootstrap commands and Docker compose versions move quickly.