spree-setup
/spree-setup
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.
- Author
- OrcaQubits ↗
- Repository
- agentic-commerce-skills-plugins ↗
- Licence
- MIT
- Last repository change
- 14.09.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 10
No signals detected. Repository changed on 14.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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.
Original author 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.
How it works
- Before writing code
- Conceptual Architecture
SKILL.md preview
--- 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+)**: ```bash npx create-spree-app@latest my-store cd my-store # Follow prompts: backend? storefront? Docker? sample data? ``` **Path B — Clone `spree-starter` directly**: ```bash 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**: ```bash 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 ```bash 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 ```bash 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.
Versions
The database has no other skills named spree-setup.
Database snapshot: 13.11.2026 · package version cb1f1aade2aa (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100spree-project
Use for any work in a Spree Commerce 6 project — orienting in the repo (server/, apps/dashboard, apps/storefront), detecting the project flavor (create-spree-app + `spree` CLI vs a classic Rails app), running commands, following Spree conventions (Spree:: namespace,… - 100spree-deployment
Deploy Spree to production — PostgreSQL + Redis + Sidekiq stack, Docker multi-arch images on GHCR, the `spree-starter` Dockerfile + Compose, Heroku/Render/Fly.io/AWS targets, env-var conventions, RAILS_MASTER_KEY, asset precompilation (Tailwind 4 + Propshaft), Action Cable,… - 100spree-extensions
Use when installing a Spree gem (spree_stripe, spree_easypost, spree_meilisearch, spree_opentelemetry, spree_i18n, spree_adyen, spree_multi_store…) or building your own reusable Spree 6 extension — a gem (Rails engine) for models, API endpoints, permissions, hooks and providers,… - 100new-project-rails
Creates a new Rails project with personal preferences (RSpec, PostgreSQL, Docker, master branch). Use when the user asks to "create a new Rails project", "start a new Rails app", "new-project-rails", or "/new-project-rails <name>". - 100spree-typescript-sdk
Build storefronts and integrations using `@spree/sdk` — the official TypeScript SDK for Spree's API v3 (v5.4+). Covers installation, the resource-builder pattern (`spree.products.list`, `spree.checkout.create`, etc.), Zod schema validation, server-only auth (httpOnly JWTs, never… - 100spree-webhooks
Receive and verify Spree Commerce webhooks. Use when setting up Spree webhook endpoint handlers, debugging X-Spree-Webhook-Signature verification, or handling order.placed, order.paid, order.canceled, payment.completed, fulfillment.fulfilled, user.created and product.updated events.