Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Improve Contributing guides

Damian Legawiec13947e4022ef
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 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.rb
deleted file mode 100644
index 9a7f95d0f8..0000000000
--- a/backend/app/models/spree.rb
+++ /dev/null
@@ -1,5 +0,0 @@
-module Spree
- def self.table_name_prefix
- "spree_"
- end
-end
diff --git a/backend/engines/api/config/initializers/typelizer.rb b/backend/engines/api/config/initializers/typelizer.rb
index 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.rb
index 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 time
def self.store_api_schemas
diff --git a/docs/developer/contributing/developing-spree.mdx b/docs/developer/contributing/developing-spree.mdx
index 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/engines
bundle 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
```
- 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 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
-
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.
-## 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 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
@@ -181,21 +254,7 @@ Please keep your commit history meaningful and clear. [This guide](https://about
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 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!