Spree 6 for self-hosted commerce: one Ruby backend, a pnpm monorepo, and a Docker-first local setup

One set of commerce primitives stretched across marketplaces, B2B and regions

Spree's pitch is that the same core serves very different businesses, and the feature list backs that up with concrete primitives rather than vertical editions. For a multi-vendor marketplace, the open-source core ships seller onboarding with configurable requirement checklists, orders split per seller at completion, a commission engine, a payout ledger built on Stripe Connect, and a dedicated Seller Panel. For B2B and wholesale, there are price lists with volume tiers, customer groups, companies with locations, contacts and tax exemptions, catalogs for per-segment assortments, and storefronts gated to approved buyers.

Two concepts tie the surfaces together. Channels give each surface (a web storefront, a mobile app, a point of sale, a B2B panel, a marketplace) its own catalog, pricing, payment methods and order attribution while sharing one backend. Markets bundle currency, language, payment methods and shipping per region, so a customer in one country sees a localized storefront from the same install. Product translations, EU Omnibus price history and customs duties are built in.

The consequence for a buyer is that the model is broad from day one. A single-brand shop with one currency still inherits channels, markets and catalogs as concepts it has to understand, even if it only ever uses one of each. That breadth is the reason to pick Spree, and also the reason a small store may find it heavier than it needs.

create-spree-app will not run without Node.js 24 and a live Docker daemon

The local install is a single scaffolding command:

npx create-spree-app@latest my-store

It sets up the Spree backend, the React Admin Dashboard and, optionally, the Next.js storefront inside one monorepo. The storefront uses Next.js 16, React 19, Tailwind CSS 4 and TypeScript; the admin dashboard uses Vite and TanStack. The project claims this takes about five minutes.

The prerequisites are stated plainly: Node.js 24 or newer installed, and Docker running. That rules out a few common setups. A laptop pinned to an older Node LTS for other work will need a version manager or a separate environment before the scaffold runs. A machine where Docker is not allowed, such as some locked-down corporate workstations or CI runners without a Docker socket, cannot use this path at all, because the backend is started through Docker Compose rather than as a bare Ruby process. The repository also carries a .node-version file at the top level, so tools that read it will switch Node versions when you enter the checkout.

If you only want to look around, the free sandbox at console.spree.sh avoids all of this: it is a hosted store with the admin dashboard and APIs in the browser, created by signing in and clicking Create store. It is a way to evaluate the admin and API surface, not a place to run your own code.

The monorepo refuses npm and yarn, and the spree command depends on a postinstall build

If you clone spree/spree itself instead of scaffolding a project, the root package.json sets rules that bite early. The preinstall script is `npx only-allow pnpm`, so running npm install or yarn at the root aborts. The workspace is driven by pnpm-workspace.yaml and turbo.json, and the day-to-day scripts are thin wrappers around Turborepo: `turbo dev`, `turbo build`, `turbo test`, `turbo lint` and `turbo typecheck`.

The postinstall step tries to build the Spree CLI package and its dependencies with turbo, unless the CI environment variable is set. If that build fails, installation does not stop. Instead it prints a warning that the spree command will not work until it builds. The practical consequence is that a green install is not proof of a working CLI. A broken toolchain shows up later, when a command such as `spree add ai` is missing or errors, and the fix is to rerun the CLI build rather than reinstall everything. In CI, where CI is set, the CLI is not built at all during install, so pipelines that call it need an explicit build step.

There are also code generation scripts that cross the Ruby and TypeScript boundary. `generate:types` changes into spree/api and runs `bundle exec rake typelizer:generate`, which means regenerating TypeScript types needs a working Ruby and Bundler environment, not just Node. The zod, filters and params generators run across every package under packages/.

Running the backend from source goes through spree-starter and Docker Compose

Contributors who want the Rails server against their local checkout use a set of server scripts. `server:create` shallow-clones the separate spree/spree-starter repository into a server directory, deletes its git metadata, and writes a server/.env file containing `SPREE_PATH=..` and a `SECRET_KEY_BASE` generated with `openssl rand -hex 64`. That means openssl has to be on the path, and the secret lives in a plain file you must keep out of version control yourself, because the script also deletes the starter's .gitignore.

`server:setup` runs scripts/server-setup.sh. The development server is then started with this exact compose invocation:

SPREE_PATH=$PWD docker compose -f server/docker-compose.dev.yml -f scripts/docker-compose.edge.yml ${SPREE_MEILISEARCH:+-f scripts/docker-compose.meilisearch.yml} up --force-recreate --remove-orphans web

Two details matter. Meilisearch is opt-in: the extra compose file is only added when the SPREE_MEILISEARCH variable is set, so search behaves differently depending on your shell environment. And `--force-recreate --remove-orphans` rebuilds the web service's containers on every start, so state kept inside a container rather than in a volume does not survive a restart.

The admin builds are served from fixed paths. `server:dashboard` builds the dashboard with `VITE_BASE_PATH=/dashboard/`, and `server:seller` builds the seller dashboard with `VITE_BASE_PATH=/sellers/`. A reverse proxy in front of a source build has to route those two prefixes.

Multi-tenant SaaS is the one use case the BSD license does not cover

Nearly every capability on the feature list is stated to ship in the repository under BSD 3-Clause: the REST API and SDKs, the React admin, the Seller Panel, the Next.js storefront and the CLI. The exception is multi-tenant SaaS, where each tenant gets an isolated store with its own catalog, orders, customers, payment methods and branding, and staff can manage several tenants. That use case is marked Enterprise and requires the Enterprise Edition from spreecommerce.org/pricing.

This matters for a specific kind of buyer. An agency or platform company planning to host many independent merchants on one deployment cannot do it with the open-source core alone, at least not with the built-in tenant isolation. The alternatives are to run one Spree install per merchant, with the operational cost that multiplies, or to license Enterprise. The multi-vendor marketplace feature is not a substitute: a marketplace has many sellers inside one store with shared customers and split orders, while multi-tenant SaaS keeps stores apart.

The pricing terms are not part of the repository, so anyone with this requirement needs to talk to the vendor before choosing Spree, rather than discovering the boundary after building on the open-source edition.

Customizing the React admin without forking it

The admin dashboard is a Vite and React application built on TanStack Router and TanStack Query, shadcn/ui and Tailwind. Spree's stated position is that you own it and customize it without forking. The documented extension points are concrete: change the navigation, add or remove routes, modify table columns, and insert your own UI widgets through slots. A matching Seller Panel ships for marketplace vendors, built and served separately under /sellers/.

This design has a clear payoff. Upgrades to the core dashboard can flow in without a merge against your own copy, as long as your changes stay inside those extension points. The flip side is that anything outside them, such as restructuring a core screen in a way slots do not allow, pushes you back toward a fork and the upgrade pain that comes with it. Teams should check the customization docs for the specific screens they need to change before assuming everything is reachable through slots.

The storefront takes the opposite approach. The Next.js storefront lives in its own repository, spree/storefront, and the instruction is simply to fork it, customize it and deploy it. It includes multi-region URL routing, Stripe payments with Apple Pay, Google Pay, Klarna and Affirm, customer accounts and SEO. Because it is a fork, keeping it current with upstream is your job.

A REST API with separate key types and generated TypeScript SDKs

Spree is headless at its core. The REST API serves three audiences, storefronts, admins and sellers, and each has its own TypeScript SDK. Access is controlled with publishable keys and scoped secret keys, the API applies rate limiting, and an OpenAPI 3.0 spec describes it.

The split between key types is the important design decision for anyone building a frontend. A publishable key is meant for client-side storefront code, while scoped secret keys belong on servers and can be narrowed to what a given integration needs. Mixing them up, for example shipping a secret key in a browser bundle, is the kind of mistake the separation exists to prevent, and it is worth deciding key scopes before wiring up an ERP or PIM.

Because the types are generated from the Rails API through the typelizer rake task, the SDKs track the backend schema rather than being written by hand. If you extend the Ruby models or serializers, you regenerate types to keep the SDK in sync, and that loop needs both the Ruby and Node toolchains present. The OpenAPI spec is also the natural input for clients in other languages, since the published SDKs cover TypeScript only.

Agent skills and MCP servers come preinstalled, and 6.0 is days old

Spree leans into AI-assisted development. It ships agent skills that teach Claude Code, Codex, Cursor, Copilot and more than 60 other tools Spree's conventions, customization patterns and upgrade flows, and it connects Claude Code, Cursor and VS Code to a documentation MCP server so an agent can search current docs. The project also describes a local MCP server for managing a store via chat. All of this is set up automatically by `npx create-spree-app`, and existing projects can add it with `spree add ai`. The repository's own .agents/, .claude/ and AGENTS.md entries show the maintainers use the same setup. If you do not want agent configuration in your project, expect to remove it after scaffolding.

The bigger caution is release timing. Spree 6.0 (v6.0.0) was tagged on 2026-10-27, v6.0.1 followed on 2026-10-29 and v6.0.2 on 2026-11-02, with the last push to main on 2026-11-02. The project is plainly active, but two patch releases in a week after a major version is a sign the 6.0 line is still settling. Pin an exact version, read CHANGELOG.md before upgrading, and treat guides written for earlier major versions with suspicion, since the React admin, CLI and scaffolding described here belong to the current line.

Editorial conclusion

Spree fits teams that want to own a commerce backend outright and need marketplace, B2B or multi-region features without a per-order platform fee, and that are comfortable running Docker, pnpm and a Ruby service. It does not fit someone who wants multi-tenant SaaS on the open-source license, since that requires the Enterprise Edition, or a team that cannot install Node.js 24. Before committing, read the 6.0 release notes in CHANGELOG.md and pin an exact patch version, because v6.0.0, v6.0.1 and v6.0.2 all shipped within a week.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. README
4. Releases
5. spree/spree on GitHub