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
Straighten the getting-started path
Damian Legawiec70e05320c220
diff --git a/docs/developer/core-concepts/architecture.mdx b/docs/developer/core-concepts/architecture.mdxindex 06c135c5c6..6e6aef39c0 100644--- a/docs/developer/core-concepts/architecture.mdx+++ b/docs/developer/core-concepts/architecture.mdx@@ -113,6 +113,7 @@ Spree assumes you'll extend it, and gives you three ways in that survive an upgr| Approach | Use it for | Guide ||---|---|---|+| **Events** | Reacting inside your own app when something happens — indexing a record, calling an API with your credentials | [Events](/developer/core-concepts/events) || **Webhooks** | Telling another system something happened — an ERP, a warehouse, an email tool | [Webhooks](/developer/core-concepts/webhooks) || **Custom fields** | Storing your own data on a product, order or customer without changing the schema | [Custom Fields](/developer/core-concepts/metafields) || **Providers** | Plugging in a real service for tax, delivery rates, payments or search | [Providers](/developer/providers/overview) |@@ -126,43 +127,32 @@ One Spree installation can run more than one business:- **[Stores](/developer/core-concepts/stores)** are separate businesses — their own catalog, orders, customers and settings. Data does not cross between them.- **[Channels](/developer/core-concepts/channels)** are the ways one store sells: a website, a mobile app, a retail till.- **[Markets](/developer/core-concepts/markets)** are the regions a store sells into, each with its currency, locale and tax treatment.-- **[Sellers](/developer/core-concepts/products#seller-submissions)** let one store list goods from many vendors, for a marketplace.+- **[Sellers](/developer/core-concepts/sellers)** let one store list goods from many vendors, for a marketplace.## What you install-| Package | What it is |-|---|---|-| `spree` | The engine — catalog, checkout, payments, both APIs |-| `spree_emails` | Transactional email, if you don't send your own |-| `spree_dashboard` | The back-office dashboard |--Providers for search, delivery rates, tax and payments install separately, so you only carry what you use.--**TypeScript:**-| Package | What it is ||---|---|| [`@spree/sdk`](/developer/sdk/quickstart) | Store API client — for your storefront || [`@spree/admin-sdk`](/developer/sdk/admin/quickstart) | Admin API client — for back-office and integrations || [`@spree/cli`](/developer/cli/quickstart) | Command line for local setup and calling the Admin API |+| [`@spree/dashboard`](/developer/dashboard/overview) | The admin interface, a React app you own and extend |<Info>-Spree runs on PostgreSQL, MySQL or SQLite. PostgreSQL is recommended for production — [database configuration](/developer/deployment/database).+Spree runs on PostgreSQL, MySQL or SQLite. Check [database configuration](/developer/deployment/database) for more details.</Info>## Where to go next+Two ways in, depending on how you prefer to learn.+<CardGroup cols={2}>- <Card title="Quickstart" icon="rocket" href="/developer/getting-started/quickstart">- Get an installation running.- </Card>- <Card title="Store SDK" icon="code" href="/developer/sdk/quickstart">- Build a storefront against the Store API.+ <Card title="Build something" icon="graduation-cap" href="/developer/tutorial/introduction">+ Add one feature end to end — a model with its own API, a screen in the dashboard, a page on the storefront, and the tests around it. Start here if you learn by doing.</Card>- <Card title="Products" icon="package" href="/developer/core-concepts/products">- How the catalog is modelled.- </Card>- <Card title="Carts" icon="shopping-cart" href="/developer/core-concepts/carts">- Cart, checkout, and what completion guarantees.+ <Card title="Read the reference" icon="book-open" href="/developer/core-concepts/products">+ Every part of the platform, one page each: products and pricing, carts and orders, payments, fulfillment, promotions. Start here if you already know what you need.</Card></CardGroup>++Building a storefront rather than extending the backend? Go straight to the [Store SDK](/developer/sdk/quickstart) or the [Next.js starter](/developer/storefront/nextjs/quickstart).diff --git a/docs/developer/getting-started/quickstart.mdx b/docs/developer/getting-started/quickstart.mdxindex 43908566fb..4815bfa278 100644--- a/docs/developer/getting-started/quickstart.mdx+++ b/docs/developer/getting-started/quickstart.mdx@@ -6,37 +6,21 @@ description: "Install Spree Commerce locally, run your first store, and deploy i## Using `create-spree-app`- The quickest way to get started. Scaffolds a full Spree project with Next.js Storefront (optional).+ The quickest way to get started. Scaffolds a full Spree project with React admin dashboard and Next.js Storefront (optional).- **Requirements:** [Node.js](https://nodejs.org/) 20+ and [Docker](https://docs.docker.com/get-docker/) running.+ **Requirements:** [Node.js](https://nodejs.org/) 24+ and [Docker](https://docs.docker.com/get-docker/) running.```bashnpx create-spree-app@latest my-store```- The CLI walks you through an interactive setup:+ The CLI walks you through an interactive setup where you choose the project name and whether to include the Next.js Storefront. It then builds a Docker stack with Postgres, and Spree API.- 1. Choose **Full-stack** (Backend + Next.js Storefront) or **Backend only**- 2. Optionally load **sample data** (products, categories, images)+ Once complete it will open a browser window so you can finalize the store setup (pick name, currency, your email/password).- Once complete, your store should be running at [http://localhost:3000/admin](http://localhost:3000/admin). The port can be different if `3000` is already used on your system.-- See the full [create-spree-app documentation](/developer/create-spree-app/quickstart) for all CLI flags and options.--## Accessing Admin Panel--Navigate to [http://localhost:3000/admin](http://localhost:3000/admin) and log in with the default credentials:--| | |-|---|---|-| **Email** | `[email protected]` |-| **Password** | `spree123` |--Upon successful authentication, you should see the admin screen:--<Frame caption="Spree Admin Dashboard">- <img src="/images/spree_admin_dashboard.png" />-</Frame>+ <Frame caption="Setting up your first store">+ <video autoPlay muted loop playsInline controls className="block w-auto max-w-full h-auto rounded-xl" src="/videos/store-setup.mp4"></video>+ </Frame>## Using the Spree CLI@@ -60,20 +44,11 @@ See the [Spree CLI guide](/developer/cli/quickstart) for all commands and the [A## Next Steps-<CardGroup cols={2}>- <Card title="Build with AI Agents" icon="bot" href="/developer/agentic/overview">- Install the Spree agent skills and connect the docs MCP server — Claude Code, Cursor, Copilot, and 60+ other tools learn Spree's conventions and build features with you.- </Card>- <Card title="Customization Tutorial" icon="graduation-cap" href="/developer/tutorial/introduction">- Build a complete custom feature — model, admin UI, API, and TypeScript SDK — step by step.- </Card>- <Card title="Core Concepts" icon="brain" href="/developer/core-concepts/architecture">- Understand how Spree models commerce — stores, products, orders, payments.- </Card>- <Card title="Next.js Storefront" icon="react" href="/developer/storefront/nextjs/quickstart">- Customize and extend the headless storefront.- </Card>-</CardGroup>+<Card title="How Spree fits together" icon="brain" href="/developer/core-concepts/architecture" horizontal>+ The catalog, the cart, the order and fulfillment — what each one is for, and the two APIs you build against. Twenty minutes here saves a lot of guessing later, and it ends by pointing you at whichever path suits you.+</Card>++In a hurry? Jump straight to the [tutorial](/developer/tutorial/introduction) to build a feature end to end, the [Next.js starter](/developer/storefront/nextjs/quickstart) to put a storefront in front of it, or the [CLI reference](/developer/create-spree-app/quickstart) for what the scaffold generated.<Tip>Using an AI coding agent? Run `npx skills add spree/agent-skills` in your new project — it teaches your agent the customization patterns before you write a line of code. See [Agentic Development](/developer/agentic/overview).diff --git a/docs/docs.json b/docs/docs.jsonindex b8d56304da..e05391f7ae 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -612,7 +612,6 @@"group": "Getting Started","pages": ["developer/getting-started/quickstart",- "developer/create-spree-app/quickstart","developer/core-concepts/architecture"],"icon": "rocket"@@ -945,6 +944,7 @@{"group": "Operations","pages": [+ "developer/create-spree-app/quickstart","developer/cli/quickstart",{"group": "Upgrading",@@ -2872,17 +2872,13 @@"navbar": {"links": [{- "label": "15.5k",+ "label": "16k","href": "https://github.com/spree/spree","icon": {"library": "lucide","name": "github"}},- {- "label": "v5.6.0",- "href": "https://github.com/spree/spree/releases/tag/v5.6.0"- },{"label": "Join Discord","href": "https://discord.spreecommerce.org",@@ -2891,12 +2887,7 @@"name": "discord"}}- ],- "primary": {- "type": "button",- "label": "Create a free sandbox",- "href": "https://console.spree.sh"- }+ ]},"footer": {"socials": {