Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Improve Contributing guides
Damian Legawiec13947e4022ef
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.mdindex d96d98e62f..3382d4dbe4 100644--- a/.github/CONTRIBUTING.md+++ b/.github/CONTRIBUTING.md@@ -1,3 +1,256 @@# Contributing-Please visit [Contributing section](https://docs.spreecommerce.org/developer/contributing) of Spree Guides. Thank you!+## Spree codebase++Spree is a monorepo with two main areas:++- **`backend/`** — A Rails application that mounts the Spree engines and serves the API and admin interface+- **`packages/`** — TypeScript packages (SDK, Next.js helpers, CLI)++## Backend Development (Ruby)++The Spree [Rails engines](https://guides.rubyonrails.org/engines.html) live inside `backend/engines/` and are distributed as separate gems (ruby packages installed via Bundler):++| Engine | Gem | Description |+|---|---|---|+| `core` | `spree_core` | Models, services, business logic |+| `api` | `spree_api` | REST APIs |+| `admin` | `spree_admin` | Admin dashboard |+| `emails` | `spree_emails` | Transactional emails |+| `sample` | `spree_sample` | Sample seed data |++### 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](https://github.com/spree/spree/blob/main/backend/engines/core/app/models/spree/product.rb).++### Setup++ ```bash+ cd backend+ bin/setup+ bin/rails server+ ```++`bin/setup` handles everything: installs Ruby (via [mise](https://mise.jdx.dev) 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:++ ```bash+ 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:++ ```bash+ 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](http://localhost:3000). Admin Panel is at [http://localhost:3000/admin](http://localhost:3000/admin).++### Running engine tests++Each engine has its own test suite. You first need to install the shared dependencies, then set up a test app for the engine you want to test:++ ```bash+ cd backend/engines+ bundle install++ cd core+ bundle install+ bundle exec rake test_app+ bundle exec rspec+ ```++Replace `core` with `api`, `admin`, `emails`, or `sample` to test other engines.++By default engine tests run against SQLite3. To run against PostgreSQL, set the `DB` environment variable:++ ```bash+ DB=postgres DB_USERNAME=postgres DB_PASSWORD=password DB_HOST=localhost bundle exec rake test_app+ ```++Run a single spec file:++ ```bash+ cd backend/engines/core+ bundle exec rspec spec/models/spree/state_spec.rb+ ```++Run a particular line of spec:++ ```bash+ cd backend/engines/core+ bundle exec rspec spec/models/spree/state_spec.rb:7+ ```++### Running tests in parallel++You can run specs in parallel locally using the `parallel_tests` gem. This distributes spec files across multiple CPU cores for faster execution.++After setting up the test app, create databases for parallel workers:++ ```bash+ cd backend/engines/core+ bundle exec rake parallel_setup+ ```++Then run specs in parallel:++ ```bash+ bundle exec parallel_rspec spec+ ```++You can also specify the number of workers:++ ```bash+ 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.++### Running integration tests on MacOS (only applicable for Admin Panel)++We use chromedriver to run integration tests. To install it please use this command:++ ```bash+ 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:++ ```bash+ cd backend+ 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:++ ```bash+ docker compose up -d+ ```++This boots PostgreSQL and the Spree backend automatically. The API is available at `http://localhost:3000`.++### Packages++| Package | Path | Description |+|---|---|---|+| `@spree/sdk` | `packages/sdk` | TypeScript SDK for the Spree Storefront API |+| `@spree/next` | `packages/next` | Next.js integration (server actions, caching, cookie-based auth) |++### SDK development++ ```bash+ cd packages/sdk+ npm install+ npm run dev # build in watch mode+ npm run test:watch # run tests in watch mode+ ```++| Command | Description |+|---|---|+| `npm test` | Run tests once |+| `npm run test:watch` | Run tests in watch mode |+| `npm run test:coverage` | Run tests with coverage report |+| `npm run typecheck` | Type-check with `tsc --noEmit` |+| `npm run build` | Build CJS + ESM bundles |+| `npm run dev` | Build in watch mode |+| `npm run console` | Interactive REPL for testing the SDK |+| `npm run generate:zod` | Generate Zod schemas from TypeScript types |++Tests use [Vitest](https://vitest.dev/) with [MSW](https://mswjs.io/) for API mocking at the network level.++### Next.js package development++ ```bash+ cd packages/next+ npm install+ npm run dev # build in watch mode+ npm run test:watch # run tests in watch mode+ ```++The `@spree/next` package depends on `@spree/sdk` locally via `file:../sdk`. Changes to the SDK are picked up automatically.++### Type generation++TypeScript types in `packages/sdk/src/types/generated/` are auto-generated from the Rails API serializers using [typelizer](https://github.com/skryukov/typelizer). To regenerate after changing serializers:++ ```bash+ cd backend/engines+ bundle exec rake typelizer:generate+ ```++After regenerating types, update the Zod schemas:++ ```bash+ cd packages/sdk+ npm run generate:zod+ ```++### Releasing packages++Packages use [Changesets](https://github.com/changesets/changesets) for version management:++ ```bash+ cd packages/sdk+ npx 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.++## Making changes++Create a new branch for your changes. Do not push changes to the main branch. Branch name should be human-readable and informative, eg.++* bug fixes: `fix/order-recalculation-total-bug`+* features: `feature/my-new-amazing-feature`++## Using AI tools for development++Spree comes with an [AGENTS.md](../../../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](https://claude.ai/settings/connectors) settings and add the URL.++## Submitting Changes++Please keep your commit history meaningful and clear. [This guide](https://about.gitlab.com/blog/2018/06/07/keeping-git-commit-history-clean/) covers it quite well and we recommend reading it, not only for Spree project but for any IT project overall.++We use [GitHub Actions](https://github.com/spree/spree/actions) to run CI.++1. Push your changes to a topic branch in your fork of the repository.++ ```bash+ git push -u origin fix/order-recalculation-total-bug+ ```++2. Create a Pull request - [please follow this guide](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork)++ If your changes references Github issues, please mark which issue you're fixing by adding `Fixes #<number or url of the issue>` in the commit name or PR title/description. This will automatically mark that issue as closed when your PR will be merged.+3. Wait for CI to pass+4. If CI passed wait for Spree Core team code review++ We're aiming to review and leave feedback as soon as possible. We'll leave you a meaningful feedback if needed.++## That's a wrap!++Thank you for participating in Open Source and improving Spree - you're awesome!diff --git a/backend/app/models/spree.rb b/backend/app/models/spree.rbdeleted file mode 100644index 9a7f95d0f8..0000000000--- a/backend/app/models/spree.rb+++ /dev/null@@ -1,5 +0,0 @@-module Spree- def self.table_name_prefix- "spree_"- end-enddiff --git a/backend/engines/api/config/initializers/typelizer.rb b/backend/engines/api/config/initializers/typelizer.rbindex 9f891758e8..635cdff88a 100644--- a/backend/engines/api/config/initializers/typelizer.rb+++ b/backend/engines/api/config/initializers/typelizer.rb@@ -5,7 +5,7 @@ Typelizer.configure do |config|api_root.join('app/serializers/spree/api/v3'),api_root.join('app/serializers/spree/api/v3/admin')]- config.output_dir = api_root.join('../packages/sdk/src/types/generated')+ config.output_dir = api_root.join('../../../../packages/sdk/src/types/generated')config.comments = true# Type names: StoreProduct, AdminProduct, etc.diff --git a/backend/engines/api/spec/swagger_helper.rb b/backend/engines/api/spec/swagger_helper.rbindex e408b5979b..885eebc404 100644--- a/backend/engines/api/spec/swagger_helper.rb+++ b/backend/engines/api/spec/swagger_helper.rb@@ -9,7 +9,7 @@ require 'spree/api/openapi/schema_helper'RSpec.configure do |config|# Output to the main spree docs directory at /docs/api-reference/- config.openapi_root = Rails.root.join('../../../docs').to_s+ config.openapi_root = Rails.root.join('../../../../../docs').to_s# Helper to generate schemas from Typelizer at spec run timedef self.store_api_schemasdiff --git a/docs/developer/contributing/developing-spree.mdx b/docs/developer/contributing/developing-spree.mdxindex 0ddd5bfb85..7ab962afee 100644--- a/docs/developer/contributing/developing-spree.mdx+++ b/docs/developer/contributing/developing-spree.mdx@@ -7,168 +7,241 @@ description: >-## Spree codebase-Spree is written in Ruby on Rails framework and is mounted into a Rails application as [a Rails Engine](https://guides.rubyonrails.org/engines.html).+Spree is a monorepo with two main areas:-Each of spree components (eg. Storefront) is distributed as a separate gem, eg. `spree_storefront`, inside a subdirectory of the `spree` directory, eg. `spree/storefront`.+- **`backend/`** — A Rails application that mounts the Spree engines and serves the API and admin interface+- **`packages/`** — TypeScript packages (SDK, Next.js helpers, CLI)++## Backend Development (Ruby)++The Spree [Rails engines](https://guides.rubyonrails.org/engines.html) live inside `backend/engines/` and are distributed as separate gems (ruby packages installed via Bundler):++| Engine | Gem | Description |+|---|---|---|+| `core` | `spree_core` | Models, services, business logic |+| `api` | `spree_api` | REST APIs |+| `admin` | `spree_admin` | Admin dashboard |+| `emails` | `spree_emails` | Transactional emails |+| `sample` | `spree_sample` | Sample seed data |### 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](https://github.com/spree/spree/blob/main/core/app/models/spree/product.rb).+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](https://github.com/spree/spree/blob/main/backend/engines/core/app/models/spree/product.rb).-## Forking Spree repo+### Setup-Go to [Spree GitHub repository](https://github.com/spree/spree) and click the **Fork** button. This will create a copy of the Spree repository on your GitHub account. See [Github Documentation](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) for more information on forking.+ ```bash+ cd backend+ bin/setup+ bin/rails server+ ```-## Local setup+`bin/setup` handles everything: installs Ruby (via [mise](https://mise.jdx.dev) if available, otherwise uses your system Ruby), system packages (libpq, vips), gems, and prepares the database.-Clone your fork repository+PostgreSQL must be running before you run `bin/setup`. If you don't have it installed locally, start it with Docker:```bash- git clone git://github.com/your_github_username/spree.git && cd spree+ docker run -d --name spree-postgres -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres:17-alpine```-## Create a sandbox application+By default the app connects to PostgreSQL at `localhost:5432` as user `postgres` with no password. Override with environment variables if needed:-Install gem dependencies:+ ```bash+ 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](http://localhost:3000). Admin Panel is at [http://localhost:3000/admin](http://localhost:3000/admin).++### Running engine tests++Each engine has its own test suite. You first need to install the shared dependencies, then set up a test app for the engine you want to test:```bash+ cd backend/enginesbundle install++ cd core+ bundle install+ bundle exec rake test_app+ bundle exec rspec```-Below command will setup a Rails application with Spree pre-installed with some data seeded:+Replace `core` with `api`, `admin`, `emails`, or `sample` to test other engines.++By default engine tests run against SQLite3. To run against PostgreSQL, set the `DB` environment variable:```bash- bin/sandbox.sh+ DB=postgres DB_USERNAME=postgres DB_PASSWORD=password DB_HOST=localhost bundle exec rake test_app```-This script will automatically install the necessary dependencies such as Ruby, libvips and Rails.+Run a single spec file:-## Running the application+ ```bash+ cd backend/engines/core+ bundle exec rspec spec/models/spree/state_spec.rb+ ```-Go to the `sandbox` directory:+Run a particular line of spec:```bash- cd sandbox+ cd backend/engines/core+ bundle exec rspec spec/models/spree/state_spec.rb:7```-And run the application using the following command:+### Running tests in parallel++You can run specs in parallel locally using the `parallel_tests` gem. This distributes spec files across multiple CPU cores for faster execution.++After setting up the test app, create databases for parallel workers:```bash- bin/dev+ cd backend/engines/core+ bundle exec rake parallel_setup```-This will start the web server and all the necessary processes (such as Tailwind CSS compiler).--You can access the application at [http://localhost:3000](http://localhost:3000).+Then run specs in parallel:-To access the Admin Panel, you can go to [http://localhost:3000/admin](http://localhost:3000/admin).+ ```bash+ bundle exec parallel_rspec spec+ ```-The default credentials for the Admin Panel are:+You can also specify the number of workers:+ ```bash+ bundle exec rake "parallel_setup[4]"+ bundle exec parallel_rspec -n 4 spec```- Email: [email protected]- Password: spree123++After schema changes, re-run `bundle exec rake parallel_setup` to update the worker databases.++### Running integration tests on MacOS (only applicable for Admin Panel)++We use chromedriver to run integration tests. To install it please use this command:++ ```bash+ brew install chromedriver```### Performance in development modeYou 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-Caching is disabled by default. To turn on caching please run:```bash+ cd backendbin/rails dev:cache```You will need to restart rails server after this change.-## Making changes--Create a new branch for your changes. Do not push changes to the main branch. Branch name should be human-readable and informative, eg.+## TypeScript Development-* bug fixes: `fix/order-recalculation-total-bug`-* features: `feature/my-new-amazing-feature`+### Setup-### Using AI tools for development+TypeScript developers don't need Ruby installed. Use Docker Compose from the repository root to start the backend:-Spree is ready to work nicely with AI tools such as Cursor or Claude Code. We already have Cursor rules for each module and global ones, as well as a global Claude Code rules file.+ ```bash+ docker compose up -d+ ```-## Running Tests+This boots PostgreSQL and the Spree backend automatically. The API is available at `http://localhost:3000`.-We use [CircleCI](https://circleci.com/) to run the tests for Spree.+### Packages-You can see the build statuses at [https://circleci.com/gh/spree/spree](https://circleci.com/gh/spree/spree).+| Package | Path | Description |+|---|---|---|+| `@spree/sdk` | `packages/sdk` | TypeScript SDK for the Spree Storefront API |+| `@spree/next` | `packages/next` | Next.js integration (server actions, caching, cookie-based auth) |-Each gem contains its own series of tests, and for each directory, you need to do a quick one-time creation of a test application and then you can use it to run the tests. For example, to run the tests for the core project.+### SDK development```bash- cd core- bundle exec rake test_app- bundle exec rspec+ cd packages/sdk+ npm install+ npm run dev # build in watch mode+ npm run test:watch # run tests in watch mode```-If you would like to run specs against a particular database you may specify the dummy app's database, which defaults to sqlite3.+| Command | Description |+|---|---|+| `npm test` | Run tests once |+| `npm run test:watch` | Run tests in watch mode |+| `npm run test:coverage` | Run tests with coverage report |+| `npm run typecheck` | Type-check with `tsc --noEmit` |+| `npm run build` | Build CJS + ESM bundles |+| `npm run dev` | Build in watch mode |+| `npm run console` | Interactive REPL for testing the SDK |+| `npm run generate:zod` | Generate Zod schemas from TypeScript types |++Tests use [Vitest](https://vitest.dev/) with [MSW](https://mswjs.io/) for API mocking at the network level.++### Next.js package development```bash- DB=postgres DB_USERNAME=postgres DB_PASSWORD=password DB_HOST=localhost bundle exec rake test_app+ cd packages/next+ npm install+ npm run dev # build in watch mode+ npm run test:watch # run tests in watch mode```-If you want to run specs for only a single spec file+The `@spree/next` package depends on `@spree/sdk` locally via `file:../sdk`. Changes to the SDK are picked up automatically.++### Type generation++TypeScript types in `packages/sdk/src/types/generated/` are auto-generated from the Rails API serializers using [typelizer](https://github.com/skryukov/typelizer). To regenerate after changing serializers:```bash- cd core- bundle exec rspec spec/models/spree/state_spec.rb+ cd backend/engines+ bundle exec rake typelizer:generate```-If you want to run a particular line of spec+After regenerating types, update the Zod schemas:```bash- cd core- bundle exec rspec spec/models/spree/state_spec.rb:7+ cd packages/sdk+ npm run generate:zod```-### Running tests in parallel--You can run specs in parallel locally using the `parallel_tests` gem. This distributes spec files across multiple CPU cores for faster execution.+### Releasing packages-After setting up the test app, create databases for parallel workers:+Packages use [Changesets](https://github.com/changesets/changesets) for version management:```bash- cd core- bundle exec rake parallel_setup+ cd packages/sdk+ npx changeset```-Then run specs in parallel:+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.- ```bash- bundle exec parallel_rspec spec- ```+## Making changes-You can also specify the number of workers:+Create a new branch for your changes. Do not push changes to the main branch. Branch name should be human-readable and informative, eg.- ```bash- bundle exec rake "parallel_setup[4]"- bundle exec parallel_rspec -n 4 spec- ```+* bug fixes: `fix/order-recalculation-total-bug`+* features: `feature/my-new-amazing-feature`-After schema changes, re-run `bundle exec rake parallel_setup` to update the worker databases.+### Using AI tools for development-This works with both SQLite (default) and PostgreSQL. For PostgreSQL, set the `DB` environment variable when generating the test app as described above.+Spree comes with an [AGENTS.md](../../../AGENTS.md) file that instructs coding agents like Claude Code or Codex to help you with your development.-### Running integration tests on MacOS (only applicable for Admin Panel/Storefront)+We also have an MCP server built on top of our Documentation website to help you with your development.-We use chromedriver to run integration tests. To install it please use this command:+Add this URL to your AI tools:+```+https://spreecommerce.org/docs/mcp+```- ```bash- brew cask install chromedriver- ```+In Claude Code you need to go to [Connectors](https://claude.ai/settings/connectors) settings and add the URL.## Submitting ChangesPlease keep your commit history meaningful and clear. [This guide](https://about.gitlab.com/blog/2018/06/07/keeping-git-commit-history-clean/) covers it quite well and we recommend reading it, not only for Spree project but for any IT project overall.+We use [GitHub Actions](https://github.com/spree/spree/actions) to run CI.+1. Push your changes to a topic branch in your fork of the repository.```bash@@ -181,21 +254,7 @@ Please keep your commit history meaningful and clear. [This guide](https://about3. Wait for CI to pass4. If CI passed wait for Spree Core team code review- We're aiming to review and leave feedback as soon as possible. We'll leave you a meaningul feedback if needed.--## Troubleshooting--This section will help you troubleshoot common issues with Spree.--#### libvips error--If you encounter the following libvips error:-- ```bash- LoadError: Could not open library 'vips.so.42'- ```--This error is usually an indication that you do not have libvips installed locally on your machine. Check that libvips is installed with `vips -v`, and if it is not installed, follow [installation instructions here](https://www.libvips.org/install.html).+ We're aiming to review and leave feedback as soon as possible. We'll leave you a meaningful feedback if needed.## That's a wrap!