Skip to main content
Just want to try Spree? Launch a free sandbox — a hosted Spree store with the admin dashboard and APIs, ready in your browser. Nothing to install. See Trying Spree in a sandbox.

​
Using create-spree-app

The quickest way to get started. Scaffolds a full Spree project with React admin dashboard and Next.js Storefront (optional). Requirements: Node.js 24+ with npm 9+, and Docker running. Seeing an npm error before setup starts? See Troubleshooting.
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. Once complete it will open a browser window so you can finalize the store setup (pick name, currency, your email/password).

Setting up your first store

​
Trying Spree in a sandbox

A Spree sandbox is a free, hosted Spree store at its own *.spree.sh address. Use it to explore the admin dashboard, try the APIs, or point a storefront at it — without installing Node.js, Docker or Ruby.
  1. Sign in at console.spree.sh and click Create store.
  2. Click Open to go to its admin dashboard and manage products, orders and settings.
  3. To call the Admin API, create a secret key under Settings → API Keys and use it with the Spree CLI or the Admin SDK.
When you’re ready to customize Spree’s code, install it locally with create-spree-app.

​
Project structure and overview

create-spree-app creates a project folder like this:

​
Using the Spree CLI

Projects scaffolded with create-spree-app include @spree/cli for managing the backend and calling the Admin API. Because it’s a project dependency, run it with npx (or any package-manager script):
Project setup mints a read-only Admin API key into .spree/credentials.json (and spree api mints it on first use if you skipped setup), so spree api works without any extra configuration. To call spree directly without the npx prefix, install the CLI globally:
See the Spree CLI guide for all commands and the Admin API from the CLI for querying your store’s data.

​
Next Steps

How Spree fits together

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.
In a hurry? Jump straight to the tutorial to build a feature end to end, the Next.js Storefront to put a storefront in front of it, or the API reference to see what you can do with the Admin API.
Using an AI coding agent? create-spree-app installs the Spree agent skills and connects your agent to the docs MCP server unless you said no — if you skipped them, run npx spree add ai in your project. Your agent then knows the customization patterns before you write a line of code. See Agentic Development.
Congrats! You’ve set up your Spree application and it’s looking amazing! Give Spree a GitHub Star, why don’t ya? Thank you for supporting Spree open-source! Need support or want to give some feedback? Join our Discord