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.

Update TS packages README files, standarize LICENSEs (MIT)

Damian Legawiec4db3c0ef284d
diff --git a/CLAUDE.md b/CLAUDE.md
index e8af2c1337..ca94fb30d3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -31,8 +31,6 @@ Current plans:
- `6.0-rich-text-descriptions.md` — Drop ActionText storage, store HTML in text columns, sanitize on write, serve `description` + `description_html` in API
- `5.4-store-api-naming-standardization.md` — Standardize API naming against industry (address fields, discounts, customer_note, label, brand/last4, etc.)
- `5.4-6.0-eu-legal-compliance.md` — GDPR (data export/anonymization, consent timestamps), Omnibus (PriceHistory, lowest-in-30-days), Consumer Rights (withdrawal period). Core primitives + enterprise hooks.
-
-
- `5.5-6.0-order-cancellation-and-approval.md` — First-class `OrderCancellation` + `OrderApproval` models, capture reasons/restock/refund decisions, polymorphic actor; 6.0 drops denormalized columns
- `5.5-admin-api-key-scopes.md` — Shopify-style `read_*`/`write_*` scopes on `Spree::ApiKey` for Admin API authorization (apps), independent of CanCanCan (which stays for JWT users)
- `5.4-disjunctive-option-faceting.md` — Per-option-type filter params with disjunctive facet counts (OR within option type, AND across)
@@ -51,10 +49,11 @@ Completed plans:
|---|---|
| `spree/core` | Ruby gem — models, services, business logic (`spree_core`) |
| `spree/api` | Ruby gem — Store & Admin REST APIs (`spree_api`) |
-| `spree/emails` | Ruby gem — transactional emails (`spree_emails`, optional) |
+| `spree/emails` | Ruby gem — transactional emails (optional). Deprecated in 6.0 — Next.js storefront handles consumer emails via webhooks. |
+| `packages/admin` | `@spree/admin` — React SPA admin dashboard (Spree 6.0, replaces `spree/admin`) |
| `packages/sdk` | `@spree/sdk` — TypeScript Store API client |
-| `packages/admin-sdk` | `@spree/admin-sdk` — TypeScript Admin API client (private) |
-| `packages/sdk-core` | `@spree/sdk-core` — shared HTTP/retry/error layer (private) |
+| `packages/admin-sdk` | `@spree/admin-sdk` — TypeScript Admin API client (Developer Preview) |
+| `packages/sdk-core` | `@spree/sdk-core` — shared HTTP/retry/error layer (private internal) |
| `packages/cli` | `@spree/cli` — Docker-based project management CLI |
| `packages/create-spree-app` | `create-spree-app` — project scaffolding |
| `server/` | Rails app cloned from `spree/spree-starter` (.gitignored, run `pnpm server:setup`) |
@@ -94,16 +93,21 @@ Per-request context available in models, controllers, jobs, and services:
### Models
- Inherit from `Spree.base_class`
-- Always pass `class_name` and `dependent` on associations
-- Include `Spree::Metafields` for metadata support
+- Always pass `class_name` and `dependent` on associations; use `dependent: :destroy_async` for high-fanout associations to offload deletion to a background job
+- Include `Spree::Metafields` for custom fields support (see docs/plans/5.4-6.0-custom-fields-rename.md)
+- Include `Spree::Metadata` for JSON metadata support
- Use string columns instead of enums
-- State machines: use `state_machines-activerecord` gem, default column `status` (legacy uses `state`)
+- State machines: use `state_machines-activerecord` gem, default column `status` (legacy uses `state`, see docs/plans/6.0-normalize-state-to-status.md)
- Never cast IDs to integer — always treat as strings (UUID support)
-- Uniqueness validations: always use `scope: spree_base_uniqueness_scope`
+- Uniqueness validations: always use `scope: spree_base_uniqueness_scope`, should be also enforced by database index
+- If needed use paranoia gem for soft delete support (via `acts_as_paranoid`)
```ruby
class Spree::Product < Spree.base_class
include Spree::Metafields
+ include Spree::Metadata
+
+ acts_as_paranoid
has_many :variants, class_name: 'Spree::Variant', dependent: :destroy
scope :available, -> { where(available_on: ..Time.current) }
@@ -153,11 +157,13 @@ end
### API Controllers
+The Store API (customer-facing) and Admin API (back-office) are two halves of the same v3 API and should follow the same conventions. The differences are in **what data is exposed**, **who can call it**, and **which actions are enabled by default** — not in routing style, parameter shape, or response format.
+
#### Hierarchy
-- **Base:** `Spree::Api::V3::ResourceController` — CRUD, pagination (Pagy), Ransack, CanCanCan, prefixed ID lookups, HTTP caching
-- **Store API:** `Spree::Api::V3::Store::ResourceController` — publishable API key auth
-- **Admin API:** `Spree::Api::V3::Admin::ResourceController` — secret API key auth
+- **Base:** `Spree::Api::V3::ResourceController` — pagination (Pagy), Ransack, CanCanCan, prefixed ID lookups, HTTP caching
+- **Store API:** `Spree::Api::V3::Store::ResourceController` — publishable API key auth, **read-only by default**; opt into `create`/`update`/`destroy` per resource where it makes sense (carts, customers, addresses)
+- **Admin API:** `Spree::Api::V3::Admin::ResourceController` — secret API key auth (with scopes) **or** JWT auth (with CanCanCan), **full CRUD by default** (`index`, `show`, `create`, `update`, `destroy`); subclasses don't need to redeclare actions unless restricting
#### Key overridable methods
@@ -165,12 +171,12 @@ end
#### Flat request/response structure
-API v3 uses flat params — no nested Rails-style wrapping. The base controller auto-infers from `Spree::PermittedAttributes`:
+API v3 uses flat params — no nested Rails-style wrapping. **For new controllers, prefer enumerating attributes directly with `params.permit(...)`** rather than reaching into `Spree::PermittedAttributes`. Existing controllers that use the global allowlist remain valid until migrated as part of the 6.0 transition.
```ruby
# ✅ Flat params
def permitted_params
- params.permit(Spree::PermittedAttributes.product_attributes)
+ params.permit(:name, :description, :slug)
end
# ❌ Nested params — not used in API v3
@@ -199,6 +205,26 @@ module Spree::Api::V3::Store
end
```
+```ruby
+# Admin counterpart — gets full CRUD for free from the base class
+module Spree::Api::V3::Admin
+ class ProductsController < ResourceController
+ protected
+
+ def model_class
+ Spree::Product
+ end
+
+ def serializer_class
+ Spree.api.admin_product_serializer
+ end
+
+ # No need to declare index/show/create/update/destroy — inherited.
+ # Only override scope/find_resource/permitted_params when behavior differs.
+ end
+end
+```
+
### Prefixed IDs
All API v3 uses Stripe-style prefixed IDs (e.g. `prod_86Rf07xd4z`, `variant_k5nR8xLq`):
@@ -221,10 +247,28 @@ attribute :variant_id
### Serializers (Alba)
-Located in `api/app/serializers/spree/api/v3/`. Store and Admin APIs have separate serializers; Admin extends Store:
+Located in `api/app/serializers/spree/api/v3/`. Store and Admin APIs have separate serializers; **Admin always extends Store** so changes to public fields propagate automatically.
+
+#### What goes where
+
+The Store API is a customer-facing surface. The Admin API is a back-office surface. Two rules govern which serializer an attribute belongs to:
+
+**Store serializer (customer-visible):**
+- Public product/category/cart/order data the customer sees in the storefront
+- Computed display values (`display_total`, `purchasable`, `in_stock`)
+- Customer-facing pricing (`price`, `compare_at_price`, `prior_price` for EU Omnibus)
+- **No timestamps** (`created_at`, `updated_at`, `deleted_at`) — these leak operational info and aren't useful to customers
+- **No internal state** — never expose `cost_price`, internal status flags, soft-delete columns, audit logs, internal notes, private metadata, or admin-only relations (vendors, fulfillment providers)
+
+**Admin serializer (back-office):**
+- Always include `created_at`, `updated_at`, and `deleted_at` (when paranoid)
+- Cost price, margins, internal notes, private metadata
+- Internal status, audit fields (`approved_by_id`, `cancelled_by_id`)
+- Operational relations (stock movements, fulfillment providers, internal customer tags)
+- Anything an admin needs to see but a customer must not
```ruby
-# Store serializer
+# Store serializer — customer-facing, no timestamps, no back-office data
module Spree::Api::V3
class ProductSerializer < BaseSerializer
typelize purchasable: :boolean, in_stock: :boolean, price: 'number | null'
@@ -232,11 +276,11 @@ module Spree::Api::V3
end
end
-# Admin serializer — extends store
+# Admin serializer — extends store, adds back-office attributes + timestamps
module Spree::Api::V3::Admin
class ProductSerializer < V3::ProductSerializer
typelize cost_price: 'number | null', private_metadata: 'Record<string, unknown> | null'
- attributes :status, :cost_price, :private_metadata
+ attributes :status, :cost_price, :private_metadata, :created_at, :updated_at, :deleted_at
end
end
```
@@ -271,10 +315,18 @@ For new models, add `publishes_lifecycle_events` concern and create an event ser
### API Authentication
-- **Publishable keys** (`pk_xxx`) — Store API, via `X-Spree-API-Key` header
-- **Secret keys** (`sk_xxx`) — Admin API, via `X-Spree-API-Key` header
-- **JWT tokens** — user auth, via `Authorization: Bearer <token>` header
-- **Guest cart tokens** — via `X-Spree-Token` header
+Four credential types, each with its own header and authorization model:
+
+- **Publishable keys** (`pk_xxx`) — Store API, `X-Spree-API-Key` header. Identifies the store; permits public/guest endpoints. Safe to expose in client-side code.
+- **Secret keys** (`sk_xxx`) — Admin API, `X-Spree-API-Key` header. **Server-to-server only.** Each key carries a list of [Shopify-style scopes](docs/plans/5.5-admin-api-key-scopes.md) (`read_products`, `write_orders`, etc.) that gate which endpoints it can hit. Authorization is scope-based, not CanCanCan-based.
+- **JWT tokens** — user auth, `Authorization: Bearer <token>` header. Used by both Store API (logged-in customer) and Admin API (logged-in admin user). Admin JWT auth uses **CanCanCan abilities** for authorization, not scopes — this is what the admin SPA uses.
+- **Guest cart tokens** — `X-Spree-Token` header. Authorizes operations on a specific guest cart.
+
+Admin API authorization summary:
+- Secret API key + scopes → for apps and integrations (audit-friendly, fine-grained)
+- JWT + CanCanCan → for human admin users (role-based)
+
+Both code paths converge at the same controllers; the controller checks permissions appropriately based on which credential authenticated the request.
### Dependencies System
@@ -287,9 +339,9 @@ Spree::Dependencies.cart_add_item_service = 'Spree::Cart::AddItem'
### Security
- CanCanCan permission checks on all actions
-- `Spree::PermittedAttributes` for parameter allowlists
+- Use Rails [`params.permit`](https://api.rubyonrails.org/classes/ActionController/Parameters.html) to whitelist parameters in controllers
- Use `Spree.user_class` / `Spree.admin_user_class` — never reference user models directly
-- Use `spree.` route engine prefix in views and controllers
+- Declare Ransack allowlists on **models** via `whitelisted_ransackable_attributes`, `whitelisted_ransackable_associations`, and `whitelisted_ransackable_scopes` to control which attributes, associations, and scopes are queryable from API requests
### Performance
@@ -321,8 +373,13 @@ pnpm install # install all workspace deps
pnpm build # build all packages (Turbo-cached)
pnpm test # run all package tests
pnpm typecheck # TypeScript validation across all packages
+pnpm lint # Biome lint across all packages
+pnpm lint:fix # Biome lint + auto-fix
+pnpm format # Biome format-write
```
+**Linting:** All TypeScript packages use [Biome](https://biomejs.dev/) (replaces ESLint + Prettier). Root config at `biome.json`; per-package configs extend it via `"extends": ["../../biome.json"]` and set `"root": false`. CI runs `pnpm turbo lint` on every PR touching `packages/**`.
+
### @spree/sdk — Store API Client
TypeScript SDK for the customer-facing Store API v3.
@@ -352,7 +409,37 @@ pnpm typecheck
### @spree/admin-sdk — Admin API Client
-Same patterns as `@spree/sdk` but for the Admin API. Supports both secret key (server-to-server) and JWT (admin SPA) authentication. Private package.
+Same patterns as `@spree/sdk` but for the Admin API. Supports both secret key (server-to-server) and JWT (admin SPA) authentication. Published under the `next` dist-tag during the Spree 6.0 Developer Preview.
+
+### @spree/admin — Admin UI (React SPA)
+
+The Spree 6.0 admin dashboard. A Vite-built React SPA that replaces the legacy Rails `spree/admin` engine entirely. See [`packages/admin/README.md`](packages/admin/README.md) for the full tech stack, project structure, and architecture (auth flow, permissions, multi-store, extension points). Architecture decisions live in `docs/plans/6.0-admin-spa.md`.
+
+**Tech stack at a glance:** Vite, TanStack Router (file-based, type-safe), TanStack Query, React Hook Form + Zod, shadcn/ui + Base UI + Tailwind, Biome, Vitest. All API calls go through `@spree/admin-sdk`.
+
+**Running the admin UI locally:**
+
+```bash
+# 1. Boot a Spree backend (one terminal, from monorepo root)
+pnpm server:setup # one-time: clones spree-starter into ./server
+pnpm server:dev # Rails on http://localhost:3000
+
+# 2. Boot the admin (separate terminal)
+cd packages/admin
+pnpm dev # http://localhost:5173 (proxies /api/* to :3000)
+```
+
+`VITE_SPREE_API_URL` overrides the backend URL for both dev and build (defaults to `http://localhost:3000`). Sign in with the seed admin user (`[email protected]` / `spree123` by default — check your server's `db/seeds.rb`).
+
+**When implementing a new admin feature:**
+
+1. **Look at the legacy Rails admin in `spree/admin/`** for guidance on what the feature does today (data shape, business rules, edge cases). It's a useful reference for "what does this screen actually need to do."
+2. **Don't port the UX 1:1.** The legacy admin is Rails + Turbo, which constrained UX choices around server round-trips, full page navigations, and form submissions. The React SPA can do better — inline editing, optimistic updates, multi-step flows without page reloads, modal-driven workflows, real-time validation, drag-and-drop, virtualized lists. Use those patterns where they meaningfully improve the experience.
+3. **The Admin API is the only data source.** Never reach into Rails models or import server-rendered HTML.
+4. **Follow `docs/plans/6.0-admin-spa.md`** for the three extension points (table registry, navigation registry, component injection) and the shadcn copy-paste ownership model.
+5. **Wrap SDK calls in custom hooks** under `src/hooks/` (e.g., `useOrders`, `useProduct`) — never call `adminClient` directly from components.
+
+If a needed Admin API endpoint or attribute is missing, **add it to `spree/api` first** (see backend conventions above), regenerate types via the [Type Generation Pipeline](#type-generation-pipeline), then consume it from the SPA.
### @spree/sdk-core — Shared HTTP Layer
@@ -374,6 +461,8 @@ cd packages/sdk && pnpm test # 5. SDK tests
- Zod schemas → `packages/sdk/src/zod/generated/`
- Store types: `StoreProduct`, `StoreOrder`, etc. Admin types: `AdminProduct`, `AdminOrder`, etc.
+A **Lefthook pre-commit hook** (`lefthook.yml`) regenerates types and Zod schemas automatically whenever `spree/api/app/serializers/**/*.rb` files are committed, then re-stages the generated output. You don't need to run steps 1 and 2 manually if you're committing serializer changes — the hook handles it. Steps 3–5 (integration tests, OpenAPI regen, SDK tests) still need to run locally before pushing.
+
### Changesets & Versioning
Published packages use **Changesets** for versioning. Place changeset files in the package's `.changeset/` directory.
diff --git a/packages/admin-sdk/LICENSE b/packages/admin-sdk/LICENSE
new file mode 100644
index 0000000000..fbaaca776c
--- /dev/null
+++ b/packages/admin-sdk/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vendo Connect Inc., Vendo Sp. z o.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/packages/admin-sdk/README.md b/packages/admin-sdk/README.md
index 1559dc0fd4..44781c3b0d 100644
--- a/packages/admin-sdk/README.md
+++ b/packages/admin-sdk/README.md
@@ -170,6 +170,38 @@ try {
When a request fails because the API key lacks the required scope, the error has `code: 'access_denied'` and `details.required_scope` carries the missing scope name.
+## TypeScript support
+
+Full TypeScript support with generated types from the API serializers:
+
+```typescript
+import type {
+ AdminOrder,
+ AdminProduct,
+ AdminCustomer,
+ AdminFulfillment,
+ AdminPayment,
+ PaginatedResponse,
+} from '@spree/admin-sdk'
+
+const orders: PaginatedResponse<AdminOrder> = await client.orders.list()
+const product: AdminProduct = await client.products.get('prod_xxx')
+```
+
+Admin types are exported with the `Admin` prefix to distinguish them from the customer-facing `@spree/sdk` types (which use `Store` prefixes for the same domain entities). Admin types include fields and relationships hidden from the Store API.
+
+## Custom fetch
+
+You can provide a custom fetch implementation:
+
+```typescript
+const client = createAdminClient({
+ baseUrl: 'https://store.example.com',
+ secretKey: 'sk_xxx',
+ fetch: customFetchImplementation,
+})
+```
+
## Documentation
- **Full API reference:** [spreecommerce.org/docs/api-reference/admin-api](https://spreecommerce.org/docs/api-reference/admin-api/introduction)
@@ -177,6 +209,71 @@ When a request fails because the API key lacks the required scope, the error has
- **Errors:** [spreecommerce.org/docs/api-reference/admin-api/errors](https://spreecommerce.org/docs/api-reference/admin-api/errors)
- **Querying:** [spreecommerce.org/docs/api-reference/admin-api/querying](https://spreecommerce.org/docs/api-reference/admin-api/querying)
+## Development
+
+### Setup
+
+```bash
+cd packages/admin-sdk
+pnpm install
+```
+
+### Scripts
+
+| Command | Description |
+|---|---|
+| `pnpm test` | Run tests once |
+| `pnpm test:watch` | Run tests in watch mode |
+| `pnpm typecheck` | Type-check with `tsc --noEmit` |
+| `pnpm lint` | Lint with Biome |
+| `pnpm lint:fix` | Lint and auto-fix with Biome |
+| `pnpm format` | Format source with Biome |
+| `pnpm build` | Build CJS + ESM bundles with `tsup` |
+| `pnpm dev` | Build in watch mode |
+| `pnpm generate:admin-client` | Regenerate the resource client from the OpenAPI spec |
+
+### Type generation pipeline
+
+When the upstream Admin API serializers in `spree/api` change, regenerate types from the monorepo root:
+
+```bash
+# 1. Regenerate TypeScript types from Alba serializers
+cd spree/api && bundle exec rake typelizer:generate
+
+# 2. Rebuild the SDK (consumes the generated types)
+cd packages/admin-sdk && pnpm build
+
+# 3. Run tests to confirm nothing broke
+pnpm test
+```
+
+Generated TypeScript types land in `src/types/generated/`; do not edit by hand.
+
+### Releasing
+
+This package uses [Changesets](https://github.com/changesets/changesets) for version management and publishing.
+
+**After making changes:**
+
+```bash
+pnpm changeset
+```
+
+This prompts you to select a semver bump type (patch/minor/major) and write a summary. A changeset file is created in `.changeset/`.
+
+**How releases work:**
+
+1. Changeset files are committed with your PR
+2. When merged to `main`, a GitHub Action creates a "Version Packages" PR that bumps the version and updates the CHANGELOG
+3. When that PR is merged, the package is automatically published to npm under the `next` dist-tag (Developer Preview), so `npm install @spree/admin-sdk` does not pick it up as `latest`
+
+**Manual release (if needed):**
+
+```bash
+pnpm version # Apply changesets and bump version
+pnpm release # Build and publish to npm
+```
+
## License
-MIT © [Vendo Connect Inc.](https://vendoconnect.com)
+MIT
diff --git a/packages/admin-sdk/package.json b/packages/admin-sdk/package.json
index e92560afeb..abe19e622d 100644
--- a/packages/admin-sdk/package.json
+++ b/packages/admin-sdk/package.json
@@ -30,7 +30,8 @@
},
"files": [
"dist",
- "README.md"
+ "README.md",
+ "LICENSE"
],
"scripts": {
"generate:admin-client": "tsx scripts/generate-admin-client.ts",
diff --git a/packages/admin/LICENSE b/packages/admin/LICENSE
new file mode 100644
index 0000000000..fbaaca776c
--- /dev/null
+++ b/packages/admin/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vendo Connect Inc., Vendo Sp. z o.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/packages/admin/README.md b/packages/admin/README.md
index d2e77611fd..99be2055e2 100644
--- a/packages/admin/README.md
+++ b/packages/admin/README.md
@@ -1,73 +1,171 @@
-# React + TypeScript + Vite
+# @spree/admin
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+The Spree Commerce admin dashboard — a React single-page application that replaces the legacy Rails `spree/admin` engine entirely. Built on the [Admin API](https://spreecommerce.org/docs/api-reference/admin-api/introduction) via `@spree/admin-sdk`, with a modern extension model (table registry, navigation registry, component injection) for plugin authors.
-Currently, two official plugins are available:
+> **Developer Preview.** The Admin SPA is in active development for Spree 6.0. Some routes still fall back to the Rails admin while feature parity is being reached. See [`docs/plans/6.0-admin-spa.md`](../../docs/plans/6.0-admin-spa.md) for the current scope.
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+## Tech stack
-## React Compiler
+| Layer | Choice |
+|---|---|
+| Build & dev | [Vite](https://vitejs.dev/) |
+| Routing | [TanStack Router](https://tanstack.com/router) (file-based, type-safe) |
+| Data fetching | [TanStack Query](https://tanstack.com/query) |
+| Forms | [React Hook Form](https://react-hook-form.com/) + [Zod](https://zod.dev/) |
+| UI primitives | [shadcn/ui](https://ui.shadcn.com/) + [Base UI](https://base-ui.com/) + [Tailwind CSS](https://tailwindcss.com/) |
+| Icons | [lucide-react](https://lucide.dev/) |
+| Charts | [Recharts](https://recharts.org/) |
+| Rich text | [Tiptap](https://tiptap.dev/) |
+| Notifications | [Sonner](https://sonner.emilkowal.ski/) |
+| Lint & format | [Biome](https://biomejs.dev/) |
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+## Getting started
-## Expanding the ESLint configuration
+The admin needs a running Spree backend exposing the Admin API. The simplest setup:
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+```bash
+# 1. Boot a Spree server (from the monorepo root)
+pnpm server:setup # one-time: clones spree-starter into ./server
+pnpm server:dev # runs Rails on http://localhost:3000
-```js
-export default defineConfig([
- globalIgnores(['dist']),
- {
- files: ['**/*.{ts,tsx}'],
- extends: [
- // Other configs...
+# 2. In a separate terminal, run the admin dev server
+cd packages/admin
+pnpm dev # http://localhost:5173
+```
+
+Vite proxies `/api/*` to `http://localhost:3000`. The first time you load the admin, sign in with the seed admin user (default: `[email protected]` / `spree123` — see your server's `db/seeds.rb`). If you need to reset an admin password, run `pnpm server:console` and update the user from the Rails console.
+
+### Configuration
+
+The dev server reads its API base URL from `VITE_SPREE_API_URL` (defaults to `http://localhost:3000`). For a custom backend:
+
+```bash
+VITE_SPREE_API_URL=https://my-spree.example.com pnpm dev
+```
- // Remove tseslint.configs.recommended and replace with this
- tseslint.configs.recommendedTypeChecked,
- // Alternatively, use this for stricter rules
- tseslint.configs.strictTypeChecked,
- // Optionally, add this for stylistic rules
- tseslint.configs.stylisticTypeChecked,
+For production builds, set the same env var at build time:
- // Other configs...
- ],
- languageOptions: {
- parserOptions: {
- project: ['./tsconfig.node.json', './tsconfig.app.json'],
- tsconfigRootDir: import.meta.dirname,
- },
- // other options...
- },
- },
-])
+```bash
+VITE_SPREE_API_URL=https://api.mystore.com pnpm build
```
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
- globalIgnores(['dist']),
- {
- files: ['**/*.{ts,tsx}'],
- extends: [
- // Other configs...
- // Enable lint rules for React
- reactX.configs['recommended-typescript'],
- // Enable lint rules for React DOM
- reactDom.configs.recommended,
- ],
- languageOptions: {
- parserOptions: {
- project: ['./tsconfig.node.json', './tsconfig.app.json'],
- tsconfigRootDir: import.meta.dirname,
- },
- // other options...
- },
- },
-])
+## Scripts
+
+| Command | Description |
+|---|---|
+| `pnpm dev` | Start Vite dev server with HMR on port 5173 |
+| `pnpm build` | Type-check and build the SPA into `dist/` |
+| `pnpm preview` | Serve the production build locally |
+| `pnpm lint` | Lint with Biome |
+| `pnpm lint:fix` | Lint and auto-fix with Biome |
+| `pnpm format` | Format source with Biome |
+
+## Project structure
+
```
+src/
+├── client.ts # adminClient instance (configures @spree/admin-sdk)
+├── main.tsx # app entry, providers
+├── router.tsx # TanStack Router configuration
+├── routeTree.gen.ts # generated by @tanstack/router-plugin (do not edit)
+├── routes/ # file-based routes
+│ ├── __root.tsx # router context (auth, permissions)
+│ ├── login.tsx # public login page
+│ └── _authenticated/ # auth-guarded routes
+│ └── $storeId/ # multi-store routes (orders, products, customers, ...)
+├── components/ # app-level components
+│ └── ui/ # shadcn/ui primitives
+├── hooks/ # data hooks built on @spree/admin-sdk
+├── providers/ # AuthProvider, PermissionProvider, StoreProvider
+├── tables/ # table definitions for the registry
+├── schemas/ # Zod form schemas
+└── lib/ # utilities, query client, table registry
+```
+
+## Architecture notes
+
+### Authentication
+
+JWT-based, with automatic token refresh:
+
+- Login → `POST /api/v3/admin/auth/login` returns `{ token, refresh_token, user }`
+- Access token stored in React context + `localStorage`; refresh token in `localStorage`
+- Background refresh every 58 minutes
+- 401 responses trigger an automatic refresh via the SDK's `onUnauthorized` hook, then retry the original request
+- All concurrent refreshes are serialized to prevent double-rotation
+
+Public routes (login) sit at the root; everything else is gated by `routes/_authenticated.tsx`.
+
+### Permissions
+
+Permissions are **server-driven**. On login, `GET /api/v3/admin/me` returns the user's CanCanCan abilities serialized as JSON. The SPA mirrors them via:
+
+```tsx
+import { Can } from '@/components/can'
+import { usePermissions } from '@/providers/permission-provider'
+
+// Declarative
+<Can I="update" a="Order"><EditButton /></Can>
+
+// Imperative
+const { can } = usePermissions()
+if (can('destroy', 'Product')) { /* ... */ }
+```
+
+The server still enforces `authorize!` on every request — the SPA is UX only.
+
+### Multi-store
+
+All authenticated routes include a `$storeId` segment (e.g. `/store_abc/orders`). The `StoreProvider` configures the SDK with the active store and exposes `useStore()` to read the current store's currency, locale, and metadata. The root authenticated route redirects to the user's default store.
+
+### Extension points
+
+Three extension points are designed for plugin authors (full design in [`docs/plans/6.0-admin-spa.md`](../../docs/plans/6.0-admin-spa.md)):
+
+1. **Table registry** — register columns/filters/actions for any list view
+2. **Navigation registry** — inject sidebar menu items
+3. **Component injection** — slot points in core pages (e.g., extra cards on the order detail)
+
+The shadcn copy-paste model means UI components in `src/components/ui/` are owned by this project, not a component library. Extensions can copy-and-modify rather than fighting library abstractions.
+
+## Adding a shadcn/ui component
+
+```bash
+pnpm dlx shadcn@latest add <component-name>
+```
+
+Components land in `src/components/ui/`. Customize freely.
+
+## Working with @spree/admin-sdk
+
+All API calls go through the SDK instance configured in `src/client.ts`. Wrap calls in custom hooks under `src/hooks/`:
+
+```ts
+// src/hooks/use-orders.ts
+import { useQuery } from '@tanstack/react-query'
+import { adminClient } from '@/client'
+
+export function useOrders(params: ListOrdersParams) {
+ return useQuery({
+ queryKey: ['orders', params],
+ queryFn: () => adminClient.orders.list(params),
+ })
+}
+```
+
+Mutations follow the same pattern with `useMutation` and `queryClient.invalidateQueries(...)` to refresh affected views.
+
+## Contributing
+
+This package is private and ships as part of the Spree 6.0 release. Architecture decisions live in `docs/plans/6.0-admin-spa.md` — please read that before proposing significant changes.
+
+When changing API contracts, also update the upstream serializers in `spree/api` and regenerate types:
+
+```bash
+cd spree/api && bundle exec rake typelizer:generate
+cd packages/admin-sdk && pnpm build
+```
+
+## License
+
+MIT
diff --git a/packages/admin/package.json b/packages/admin/package.json
index 089268bbf7..46603e366b 100644
--- a/packages/admin/package.json
+++ b/packages/admin/package.json
@@ -1,6 +1,7 @@
{
"name": "@spree/admin",
"private": true,
+ "license": "MIT",
"version": "0.0.0",
"type": "module",
"scripts": {
diff --git a/packages/cli/LICENSE b/packages/cli/LICENSE
new file mode 100644
index 0000000000..fbaaca776c
--- /dev/null
+++ b/packages/cli/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vendo Connect Inc., Vendo Sp. z o.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/packages/cli/package.json b/packages/cli/package.json
index f303ce886b..f1f73f62af 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -8,7 +8,8 @@
},
"files": [
"dist",
- "README.md"
+ "README.md",
+ "LICENSE"
],
"scripts": {
"build": "tsup",
diff --git a/packages/create-spree-app/package.json b/packages/create-spree-app/package.json
index cbbc03934e..03a1924370 100644
--- a/packages/create-spree-app/package.json
+++ b/packages/create-spree-app/package.json
@@ -6,7 +6,8 @@
"bin": "./dist/index.js",
"files": [
"dist",
- "README.md"
+ "README.md",
+ "LICENSE"
],
"scripts": {
"build": "tsup",
diff --git a/packages/sdk-core/package.json b/packages/sdk-core/package.json
index 71085e8d03..24a0bc528b 100644
--- a/packages/sdk-core/package.json
+++ b/packages/sdk-core/package.json
@@ -2,6 +2,7 @@
"name": "@spree/sdk-core",
"version": "0.1.0",
"private": true,
+ "license": "MIT",
"description": "Shared internals for Spree Commerce SDKs",
"type": "module",
"main": "./dist/index.cjs",
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index 2f8f46e8f9..64cc2e3405 100644
--- a/packages/sdk/package.json
+++ b/packages/sdk/package.json
@@ -50,7 +50,8 @@
},
"files": [
"dist",
- "README.md"
+ "README.md",
+ "LICENSE"
],
"scripts": {
"generate:zod": "tsx scripts/generate-zod.ts",