Skip to main content

​
Cloning the repository

Spree is a big monorepo. For a faster clone, use a partial clone which downloads file contents on demand while keeping full commit history for git log and git blame: 
git clone --filter=blob:none https://github.com/spree/spree.git

​
Spree codebase

Spree is a monorepo with three main areas:
  • spree/ — Ruby gems (core, api, admin, emails) distributed as separate packages via RubyGems
  • packages/ — TypeScript packages (SDK, Next.js helpers)
  • server/ — A Rails application that mounts the Spree gems and serves the API and admin interface

​
Backend Development (Ruby)

​
Engines overview

The Spree Rails engines live inside spree/ and are distributed as separate gems (Ruby packages installed via Bundler):
EngineGemDescription
corespree_coreModels, services, business logic
apispree_apiREST APIs
adminspree_adminAdmin dashboard
emailsspree_emailsTransactional emails

​
Spree namespace

All Spree models, controllers and other Ruby classes are namespaced by the Spree keyword, eg. Spree::Product. This means that those files are also located in spree sub-directories eg. app/models/spree/product.rb.

​
Setup

cd server
bin/setup
bin/rails server
bin/setup handles everything: installs Ruby (via mise if available, otherwise uses your system Ruby), system packages (libpq, vips), gems, and prepares the database. PostgreSQL must be running before you run bin/setup. If you don’t have it installed locally, start it with Docker: 
docker run -d --name spree-postgres -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres:17-alpine
By default the app connects to PostgreSQL at localhost:5432 as user postgres with no password. Override with environment variables if needed: 
DATABASE_HOST=127.0.0.1 DATABASE_PORT=5433 DATABASE_USERNAME=myuser bin/setup
Use bin/setup --reset to drop and recreate the database. The app runs at http://localhost:3000. Admin Panel is at http://localhost:3000/admin.

​
Running engine tests

Each engine has its own test suite. First install the shared dependencies at the spree/ level, then navigate into the specific engine to set up and run its tests: 
# 1. Install shared dependencies
cd spree
bundle install

# 2. Set up and run tests for a specific engine (e.g. core)
cd core
bundle install
bundle exec rake test_app
bundle exec rspec
Replace core with api, admin, or emails to test other engines. By default engine tests run against SQLite3. To run against PostgreSQL, set the DB environment variable: 
DB=postgres DB_USERNAME=postgres DB_PASSWORD=password DB_HOST=localhost bundle exec rake test_app
Run a single spec file: 
cd spree/core
bundle exec rspec spec/models/spree/state_spec.rb
Run a specific test by line number: 
cd spree/core
bundle exec rspec spec/models/spree/state_spec.rb:7

​
Running tests in parallel

For faster test runs on multi-core machines, you can use the parallel_tests gem to distribute spec files across multiple CPU cores. After setting up the test app, create databases for parallel workers: 
cd spree/core
bundle exec rake parallel_setup
Then run specs in parallel: 
bundle exec parallel_rspec spec
You can also specify the number of workers: 
bundle exec rake "parallel_setup[4]"
bundle exec parallel_rspec -n 4 spec
After schema changes, re-run bundle exec rake parallel_setup to update the worker databases.

​
Integration tests (Admin Panel)

The Admin Panel uses feature specs that run in a real browser via chromedriver. You only need this if you’re working on admin UI changes. Install chromedriver on macOS: 
brew install chromedriver

​
Performance in development mode

You may notice that your Spree store runs slower in development environment. This is caused by disabled caching and automatic reloading of code after each change. Caching is disabled by default. To turn on caching please run: 
cd server
bin/rails dev:cache
You will need to restart rails server after this change.

​
TypeScript Development

​
Setup

TypeScript developers don’t need Ruby installed. Use Docker Compose from the repository root to start the backend: 
docker compose up -d
This boots PostgreSQL and the Spree backend automatically. The API is available at http://localhost:3000. Then install dependencies and start all packages in watch mode: 
pnpm install
pnpm dev

​
Packages

PackagePathDescription
@spree/sdkpackages/sdkTypeScript SDK for the Spree Storefront API
@spree/nextpackages/nextNext.js integration (server actions, caching, cookie-based auth)

​
Common commands

Run from the repository root — Turborepo orchestrates tasks across all packages:
CommandDescription
pnpm devStart Docker backend + watch mode for all packages
pnpm buildBuild all packages (SDK first, then Next.js)
pnpm testRun tests in all packages
pnpm lintLint all packages
pnpm typecheckType-check all packages
pnpm cleanRemove build artifacts

​
Package-specific commands

You can also run commands in a single package: 
pnpm --filter @spree/sdk test:watch
pnpm --filter @spree/sdk console
pnpm --filter @spree/sdk generate:zod
Tests use Vitest with MSW for API mocking at the network level.

​
Type generation

TypeScript types in packages/sdk/src/types/generated/ are auto-generated from the Rails API serializers using typelizer. To regenerate after changing serializers: 
cd spree/api
mise install --yes # to install Ruby if you don't have it already
bundle install # to install dependencies
bundle exec rake typelizer:generate
After regenerating types, update the Zod schemas: 
pnpm --filter @spree/sdk generate:zod

​
Releasing packages

Packages use Changesets for version management: 
pnpm changeset
This creates a changeset file describing your changes. Commit it with your PR. When merged to main, a GitHub Action creates a “Version Packages” PR that bumps the version and publishes to npm.

​
Code Style

Consistent code style is enforced via automated linters. Please make sure your changes pass linting before submitting a PR. Ruby: We use RuboCop for Ruby code. Configuration lives in server/.rubocop.yml. Run it from the server/ directory: 
cd server
bundle exec rubocop
To auto-fix correctable offenses: 
bundle exec rubocop -a
TypeScript: We use Biome for linting and formatting TypeScript code. Run it from the repository root: 
pnpm lint

​
Making Changes

​
Branch naming

Create a new branch for your changes. Do not push changes to the main branch. Branch names should be human-readable and informative:
  • Bug fixes: fix/order-recalculation-total-bug
  • Features: feature/my-new-amazing-feature

​
Commit messages

Keep your commit history meaningful and clear. Each commit should represent a logical unit of work. This guide covers this well. A few tips:
  • Write commit messages in the imperative mood (e.g. “Add feature” not “Added feature”)
  • Keep the first line under 72 characters
  • If your change references a GitHub issue, include Fixes #<number> in the commit message or PR description to auto-close it on merge

​
Using AI tools for development

Spree comes with an AGENTS.md file that instructs coding agents like Claude Code or Codex to help you with your development. We also have an MCP server built on top of our Documentation website to help you with your development. Add this URL to your AI tools: 
https://spreecommerce.org/docs/mcp
In Claude Code you need to go to Connectors settings and add the URL.

​
Submitting Changes

We use GitHub Actions to run CI.
  1. Push your changes to a topic branch in your fork of the repository. 
    git push origin fix/order-recalculation-total-bug
  2. Create a Pull Request against the main branch.
  3. Wait for CI to pass.
  4. Wait for Spree Core team code review. We aim to review and leave feedback as soon as possible.

​
Pull request guidelines

To help us review your PR quickly:
  • Keep PRs focused. One feature or fix per PR. Smaller PRs are easier to review and merge.
  • Describe your changes. Explain what you changed and why. Include screenshots for UI changes.
  • Add tests. All new features and bug fixes should include appropriate test coverage.
  • Update documentation. If your change affects user-facing behavior, update the relevant docs.
  • Include a changeset (TypeScript packages only). Run pnpm changeset if your change affects @spree/sdk or @spree/next.
  • Ensure CI passes. PRs with failing CI will not be reviewed.

​
Reporting Bugs

We use GitHub Issues to track bugs. Before filing a new issue, please search existing issues to avoid duplicates. When reporting a bug, please include:
  • Spree version you’re using
  • Steps to reproduce the problem
  • Expected behavior vs actual behavior
  • Relevant logs or stack traces (formatted with triple backticks)
  • Your environment (Ruby version, database, OS)
Issues that are open for 14 days without actionable information or activity will be marked as stale and then closed. They can be re-opened if the requested information is provided.

​
That’s a wrap!

Thank you for participating in Open Source and improving Spree - you’re awesome!