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.
Spree TypeScript Packages
This directory contains the TypeScript side of the Spree monorepo: the shared core library, the SDKs, the admin dashboard and seller panel, the CLI, project scaffolding, and the docs bundle. Everything here is managed with pnpm workspaces + Turbo, built with tsup (or Vite for the admin SPA), tested with Vitest, and linted with Biome. Versioning for published packages is handled by Changesets.
For monorepo-wide conventions (type generation pipeline, code style, testing) see the root CLAUDE.md. For backend conventions see spree/.
Status legend
| Badge | Meaning |
|---|---|
| Stable | Published to npm under latest, follows semver, safe for production. Packages that talk to the Spree API carry the Spree version: 6.0.x works with Spree 6.0.x. |
| Developer Preview | Published to npm on the 0.x line; the API may change between minor versions. Pin exact versions. |
| Internal | Private to the workspace ("private": true), not published. |
Packages
| Package | npm | Status | Description |
|---|---|---|---|
sdk |
@spree/sdk |
Stable (6.x) | TypeScript client for the customer-facing Store API v3. 1.x targets Spree 5.x. |
admin-sdk |
@spree/admin-sdk |
Stable (6.x) | TypeScript client for the Admin API v3. |
seller-sdk |
@spree/seller-sdk |
Stable (6.x) | TypeScript client for the Seller API, used by marketplace seller panels. |
core |
@spree/core |
Stable (6.x) | Universal code with no HTTP: country, currency, locale and unit code lists, unit systems, display names, exact money arithmetic and input parsing, the filter vocabulary. |
sdk-core |
— | Internal | Shared HTTP, retry and error layer the SDKs bundle. |
dashboard |
@spree/dashboard |
Stable (6.x) | The Spree 6.0 admin dashboard, a React single-page app. Replaces the legacy Rails spree/admin engine. |
dashboard-core |
@spree/dashboard-core |
Stable (6.x) | Dashboard framework: registries (table, nav, slot, settings-nav), providers, shared hooks, defineDashboardPlugin. The extension API. |
dashboard-ui |
@spree/dashboard-ui |
Stable (6.x) | Design system: shadcn primitives, headless composed components, design tokens. Source-only. |
seller-dashboard |
@spree/seller-dashboard |
Stable (6.x) | The marketplace seller panel, the seller-facing counterpart to the admin dashboard. |
dashboard-starter |
— | Internal | Host app for the admin dashboard; the source of the spree/dashboard-starter template. |
seller-dashboard-starter |
— | Internal | Host app for the seller panel; the source of the spree/seller-dashboard-starter template. |
dashboard-plugin-example |
— | Internal | Example dashboard plugin (a Brands feature); the reference for the plugin authoring docs. |
cli |
@spree/cli |
Stable (3.x) | CLI for managing Spree projects scaffolded with create-spree-app. |
create-spree-app |
create-spree-app |
Stable (2.x) | One-shot scaffolder: npx create-spree-app my-store. Sets up the backend and, optionally, the Next.js storefront. |
docs |
@spree/docs |
Developer Preview (0.x) | Spree developer documentation packaged for local access by AI agents and dev tools. |
@spree/sdk — Store API client
The customer-facing SDK. Powers storefronts (Next.js or otherwise) and any client that needs read access to the catalog plus write access to carts, customers, addresses, and checkout. Auth modes: publishable key (guest) or JWT (logged-in customer).
Includes auto-generated TypeScript types and Zod schemas derived from the Rails Alba serializers — see the type generation pipeline in the root docs.
@spree/admin-sdk — Admin API client
The back-office counterpart to @spree/sdk. Same patterns, but targets the Admin API and supports both secret API key (server-to-server, scope-based authorization) and JWT (admin user, CanCanCan-based authorization) auth modes. Used by the @spree/dashboard app and by integrations and admin tooling.
@spree/seller-sdk — Seller API client
The client for the Seller API, which marketplace sellers use to manage their own products, orders and fulfillment. Used by @spree/seller-dashboard.
@spree/dashboard, @spree/dashboard-core, @spree/dashboard-ui — the admin dashboard stack
The Spree 6.0 admin is a three-package stack:
@spree/dashboard-ui— the design system. Shadcn primitives + headless composed components (PageHeader, ResourceTable, AppSidebar, …) + design tokens. Headless rule: components accept their data via props, never import providers or hooks. Source-only; the consuming Vite/Tailwind app compiles it. Pluggable into any React app, not just@spree/dashboard.@spree/dashboard-core— the framework. The four registries (table, nav, slot, settings-nav), the four providers (auth, permission, store, theme), generic infra hooks (use-auth,use-permissions,use-resource-mutation,use-direct-upload,use-global-search, …), the admin SDK client singleton, and thedefineDashboardPluginextension facade. This is what plugin authors import to register navigation, slots, table columns, and routes.@spree/dashboard— the deployable SPA. Routes, resource hooks (use-orders,use-products,use-customers, …), Zod schemas, locale strings, the app shell. Composes the other two. Built with Vite + TanStack Router (file-based) + TanStack Query + React Hook Form + Tailwind.
Plugin authors install @spree/dashboard-ui + @spree/dashboard-core as peer dependencies. The seller panel (@spree/seller-dashboard), white-label admins, and other custom variants compose the same packages with their own routes and shell. Merchants run the dashboards from the dashboard-starter and seller-dashboard-starter templates.
Architecture, extension points (table registry, navigation registry, component injection), the package boundary rules, and the phased migration are documented in docs/plans/6.0-admin-spa.md. Local setup for the SPA is in packages/dashboard/README.md.
The three packages always release together under one version, and ship with Spree 6.0.
@spree/core — Universal code
The code every Spree client shares, whatever it runs on: code lists generated from the API references, unit systems, display names, money helpers that work on decimal strings without floating point (arithmetic, percentages, reading typed amounts), and the filter types. The dashboard packages depend on it directly. No dependencies and no network calls. The SDKs bundle it and re-export its code lists and money helpers, so SDK users never install it separately. It is the home for any code a client could use — a conversion, a format, a rule shared with the server — and the base for moving more of Spree to TypeScript.
@spree/sdk-core — Shared internals
Private package. Provides createRequestFn(), SpreeError, retry logic, and Ransack query-param transformation (transformListParams()), and re-exports @spree/core. Consumed by the SDKs; not intended for direct use.
@spree/cli — Project management CLI
Commands for projects scaffolded via create-spree-app: starting/stopping services, running migrations, opening Rails consoles, loading sample data, etc. Bundled automatically into new projects.
create-spree-app — Project scaffolder
The recommended entry point for new Spree projects. Clones spree/spree-starter, optionally adds the Next.js storefront, and runs first-time setup.
@spree/docs — Documentation bundle
Spree developer documentation (core concepts, customization, API reference, integration guides) packaged as plain Markdown so AI agents and offline tooling can read it from node_modules/@spree/docs/dist/. Built from the docs/ tree at the repo root.
Working in the monorepo
From the repo root:
pnpm install # install workspace deps
pnpm build # turbo-cached build for all packages
pnpm test # run all package tests
pnpm typecheck # TypeScript across all packages
pnpm lint # Biome lint
pnpm lint:fix # Biome lint + auto-fix
pnpm format # Biome format-write
Per-package commands are documented in each package's README.md. Changesets for versioning go in the root .changeset/ directory (pnpm changeset), never in a package's own directory.