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.

Straighten the getting-started path

Damian Legawiec70e05320c220
diff --git a/docs/developer/core-concepts/architecture.mdx b/docs/developer/core-concepts/architecture.mdx
index 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.mdx
index 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.
```bash
npx 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.json
index 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": {