sellbase

<div align="center">

<img src="docs/images/sellbase-mark.svg" width="72" alt="Sellbase" />

# Sellbase

**An open source Shopify alternative you drop into your existing project, run by your AI agent.**

Add products, a cart, Stripe checkout and an admin to the Next.js, React or plain HTML site you already have, on the Supabase you already use, with one command: `npx sellbase init`. Also included: orders, inventory, abandoned carts, discounts, appointments, emails, an API and an MCP server.

[Quick start](#quick-start) · [Features](#features) · [Docs](#documentation) · [Deploy](docs/guides/deploy.md) · [Contributing](CONTRIBUTING.md) · [Español](#en-español)

![Sellbase admin](docs/images/admin-home.png)

</div>

## Why Sellbase

- **Yours, end to end.** Your data lives in your Postgres, your money goes to your Stripe account and your code stays in your repo. There is no platform fee, no lock-in and no Sellbase servers in between. MIT licensed.
- **AI-first.** `sellbase init` writes `CLAUDE.md`/`AGENTS.md`, skills and an MCP server. Tell your agent "set up my store" and it creates products, connects payments and runs a test purchase. Money and destructive actions always ask the owner first, and everything is logged.
- **Works on any site.**
  - **Next.js and Vite + React:** React components.
  - **Plain HTML, WordPress, Webflow, Vue, Svelte, Astro, Angular:** `<sellbase-*>` web components (13 KB gzipped) and a static admin.
- **An admin that is a pleasure to use.** Products with drag and drop photos and variants, inventory, orders with packing slips and refunds, abandoned cart recovery, customers, discounts and settings for every connection. Also:
  - a command palette (⌘K) to search and act;
  - an AI copilot on Home;
  - built for store owners, not developers.
- **Safe by default.**
  - Money stored as integers.
  - RLS on every table, with tests.
  - Orders only come from verified payment webhooks.
  - Idempotent writes.
  - Third-party secrets in Supabase Vault.
  - Signed outbound webhooks that never reach private networks.

## Sellbase or build it yourself?

The usual way to add a store to a Next.js + Supabase app is to write it by hand: a `products` table, a cart, a Server Action for Stripe Checkout and a webhook route. It works for the first sale. Sellbase is that same stack (your Supabase and your Stripe) with the rest already built and tested.

|                                                                  | By hand (Supabase + Stripe)         | Sellbase                                                              |
| ---------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------- |
| Setup                                                            | 5–6 files to write and keep correct | `npx sellbase init`                                                   |
| Runs in your existing app and Supabase                           | Yes                                 | Yes: its own `sellbase` schema, no extra server                       |
| Admin for the owner                                              | Supabase dashboard, or build one    | `/admin`: products, photos, variants, orders, refunds, discounts      |
| Inventory, variants, shipping rates, taxes, discounts            | Build each one                      | Included                                                              |
| Orders created only by the verified webhook, idempotent          | Up to you                           | Built in, with tests                                                  |
| Emails, abandoned cart recovery, refunds                         | Build each one                      | Included                                                              |
| Your AI agent can run the store (create products, check orders…) | No                                  | MCP server with 31 tools; money and destructive actions ask the owner |

Unlike engines such as Medusa, Vendure or Saleor, Sellbase needs no separate backend server. It runs on Supabase Edge Functions next to your app, and the storefront components are copied into your repo for you to edit.

## Quick start

Requirements: Node 20+ and a Supabase project (or the local stack with Docker).

```bash
npx supabase start          # local stack (or pass --supabase-url … for a hosted project)
npx sellbase init --yes     # schema, Edge Functions, store, owner, admin, components, agent files
```

Then:

- **Admin:** open `/admin` and sign in. Locally, the owner's email and password are in `.env.sellbase`.
- **Setup:** follow the setup guide on Home.
- **Or let your agent do it:** open it in the project and say **"Configura mi tienda con Sellbase"** / **"Set up my store with Sellbase"**. It uses the `sellbase` MCP tools until a test purchase succeeds.

```bash
npx sellbase doctor         # checklist with the next step for anything missing
npx sellbase upgrade        # new versions: dry run, backup, migrations, functions, components
```

### Start from a template

```bash
npx sellbase create my-store --template nextjs   # Next.js store with the admin at /admin
npx sellbase create my-landing --template html   # plain HTML landing page, no build step
```

Both are in [`examples/`](examples) with Vercel and Netlify deploy buttons.

### With Claude Code

```
/plugin marketplace add jlgavel011/sellbase
/plugin install sellbase@sellbase
/sellbase:setup I sell handmade candles, $250 MXN each, shipping $120
```

The plugin brings the Sellbase skills and MCP server to every project. `/sellbase:setup` installs Sellbase, creates your products, connects Stripe in test mode and runs a test purchase. Any other MCP client can use `npx sellbase mcp` (listed in the MCP registry as `io.github.jlgavel011/sellbase`).

### With any agent (Cursor, Codex, Copilot, Gemini CLI, Windsurf…)

```bash
npx skills add jlgavel011/sellbase    # the Sellbase skills, including add-ecommerce
```

Then ask your agent to "add a store to this project". The `add-ecommerce` skill installs Sellbase and sets it up.

### With shadcn

The storefront components are also a shadcn-compatible registry:

```bash
npx shadcn add https://jlgavel011.github.io/sellbase/r/store.json          # everything
npx shadcn add https://jlgavel011.github.io/sellbase/r/product-grid.json   # or one component
```

They still need the backend: `npx sellbase init --yes`. The index is at [`/r/registry.json`](https://jlgavel011.github.io/sellbase/r/registry.json).

Going live: [deploy guide](docs/guides/deploy.md) and [live payments with Stripe](docs/guides/stripe-live.md).

## Features

|                                                           |                                                         |
| --------------------------------------------------------- | ------------------------------------------------------- |
| ![Products](docs/images/admin-products.png)               | ![Product editor](docs/images/admin-product-editor.png) |
| ![Orders](docs/images/admin-orders.png)                   | ![Order](docs/images/admin-order.png)                   |
| ![Command palette](docs/images/admin-command-palette.png) | ![Sign in](docs/images/admin-login.png)                 |

**Catalog:**

- physical products, digital downloads and services with appointments;
- up to 3 options per product (size, color…) with a variant matrix, compare-at prices and SEO;
- collections, tags and stock per variant;
- CSV import (including Shopify exports) and export;
- bulk price changes with a preview.

**Checkout:**

- Stripe Checkout (cards, Apple Pay, Google Pay; test and live mode);
- shipping rates, free shipping thresholds and local pickup;
- inclusive or exclusive taxes;
- discount codes and automatic discounts;
- deposits for services;
- a required consent checkbox (e.g. 18+ for alcohol) enforced by the server and stored with the order.

**Orders:**

- payment and fulfillment statuses;
- shipping with carrier and tracking;
- full or partial refunds;
- cancellations with restock;
- a timeline with comments;
- printable packing slips;
- manual orders (cash, transfer, WhatsApp) and payment links.

**Growth:**

- abandoned checkouts with one-click or automatic recovery emails that restore the cart;
- customers with their history;
- sales metrics and best sellers.

**Services:**

- resources with weekly hours and exceptions;
- availability;
- bookings with reminders (24 h and 2 h before) and calendar invites.

**Emails (Resend):** order confirmation with download links, shipping updates, refunds, cancellations, appointment notices and cart recovery. All of them carry your logo and brand color.

**Team and AI:**

- staff roles and invitations;
- API tokens with scopes for agents (money and data export scopes are opt-in);
- an activity log;
- signed outbound webhooks with retries for your ERP, spreadsheets or Zapier.

**Storefront:**

- React components copied into your repo (edit freely);
- headless hooks;
- web components for any site;
- SEO helpers (JSON-LD, sitemap);
- order lookup and download pages;
- accessible markup (checked with axe).

![Storefront](docs/images/storefront.jpg)

## How it works

```
your site ──(@sellbase/react or <sellbase-*> web components)──┐
/admin (@sellbase/admin) ─────────────────────────────────────┤
your AI agent ──(sellbase MCP server)─────────────────────────┤
                                                              ▼
                    Supabase: Edge Functions (sellbase-api, -webhooks, -jobs)
                              Postgres schema `sellbase` (RLS) · Vault · Storage · pg_cron
                                                              │
                                   Stripe · Resend · your webhooks
```

- **One API contract.** Every route is declared once with Zod in `@sellbase/core`. The Hono server validates with it, the OpenAPI spec and the typed SDK come from it, and the MCP tools reuse it.
- *