Installing Spree - Spree Commerce documentation

Installation options

create-spree-app
Manual Installation

The quickest way to get started. Scaffolds a full Spree project with Next.js Storefront (optional).Requirements: Node.js 20+ and Docker running.

npx create-spree-app@latest my-store

The CLI walks you through an interactive setup:

Choose Full-stack (Backend + Next.js Storefront) or Backend only
Optionally load sample data (products, categories, images)

Once complete, your store should be running at http://localhost:3000/admin. The port can be different if 3000 is already used on your system.See the full create-spree-app documentation for all CLI flags and options.

For developers who prefer full control over the setup, or want to add Spree to an existing Rails application.

Install Ruby
Install vips for image processing
Install Rails gem:
```
gem install rails
```

Create a new Spree application:

rails new my_store -m https://raw.githubusercontent.com/spree/spree/main/spree/template.rb

To use a specific database, pass the -d flag:

rails new my_store -d postgresql -m https://raw.githubusercontent.com/spree/spree/main/spree/template.rb
rails new my_store -d mysql -m https://raw.githubusercontent.com/spree/spree/main/spree/template.rb

Navigate to the application directory:
```
cd my_store
```
Start the development server:
```
bin/dev
```
Optionally load sample data (products, categories, etc.):
```
bin/rails spree_sample:load
```

Spree works with PostgreSQL, MySQL, and SQLite databases. The Rails template defaults to SQLite for quick setup. You can switch to PostgreSQL or MySQL at any time. Learn more about database configuration.

Accessing Admin Panel

Navigate to http://localhost:3000/admin and log in with the default credentials:


Email	`spree@example.com`
Password	`spree123`

Upon successful authentication, you should see the admin screen:

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):

npx spree dev               # boot the Docker stack
npx spree api get products  # query the Admin API (read-only key preconfigured)

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:

npm install -g @spree/cli
spree api get products

See the Spree CLI guide for all commands and the Admin API from the CLI for querying your store’s data.

Next Steps

Build with AI Agents

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.

Customization Tutorial

Build a complete custom feature — model, admin UI, API, and TypeScript SDK — step by step.

Core Concepts

Understand how Spree models commerce — stores, products, orders, payments.

Next.js Storefront

Customize and extend the headless storefront.

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.

Congrats! You’ve set up your Spree Commerce 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

​Installation options

​Accessing Admin Panel

​Using the Spree CLI

​Next Steps

Build with AI Agents

Customization Tutorial

Core Concepts

Next.js Storefront

Installation options

Accessing Admin Panel

Using the Spree CLI

Next Steps