Skip to content

About

@spree application starter template

Topics

Resources

Stars

402 stars

Watchers

26 watching

Forks

Repository files navigation

Spree Starter

The Rails application behind every Spree Commerce 6 project. It serves:

  • the Store API for storefronts and mobile apps
  • the Admin API
  • the Admin Dashboard, at /dashboard
  • background jobs, with their dashboard at /jobs
  • transactional emails

Projects created with create-spree-app keep this application in their server/ directory.

Getting started

Create a new project with create-spree-app:

npx create-spree-app@latest my-store

It sets up this application together with:

  • the Admin Dashboard and an optional Seller Panel for marketplaces, as apps you can customize
  • an optional Next.js storefront
  • the Spree CLI, which runs everything in Docker
  • the Spree agent skills for AI coding agents

You only need Node.js and Docker.

Just evaluating Spree? Skip self-hosting and use a hosted sandbox.

Customization

Start with the Customization Guide. It covers, in the order you should reach for them:

  • events and subscribers
  • workflow hooks
  • dependencies
  • extensions
  • decorators, as a last resort

Run commands through the Spree CLI, never through bin/rails or bundle directly. For example, spree generate subscriber, spree migrate and spree rspec.

Coding agents

AGENTS.md holds the instructions for coding agents such as Claude Code, Codex, Cursor and Copilot. CLAUDE.md imports it.

For deeper Spree knowledge, install the Spree agent skills:

npx skills add spree/agent-skills

Environment variables

.env.example lists the required variables. See the Environment Variables reference for the full list.

Deployment

This application builds into a single Docker image: the API, the Admin Dashboard and background jobs. render.yaml deploys it to Render.

See the Deployment Guide for Render, AWS and other Docker hosts.

Docker image

Every release of this repository is published as ghcr.io/spree/spree, tagged with the Spree version and latest, for linux/amd64 and linux/arm64. It is built from this repository's Dockerfile by .github/workflows/release.yml.

The image holds this application with the Store and Admin APIs, the MCP server, the Admin Dashboard and Seller Panel, and background jobs. It needs Postgres; docker-compose.yml runs it with Postgres and Mailpit:

cp .env.example .env   # then set SECRET_KEY_BASE, e.g. to the output of: openssl rand -hex 64
docker compose up

The API then listens on http://localhost:3000 and the Admin Dashboard on http://localhost:3000/dashboard.

License

MIT

About

@spree application starter template

Topics

Resources

Stars

402 stars

Watchers

26 watching

Forks

Used by

Contributors

Languages