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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Update TS packages README files, standarize LICENSEs (MIT)
Damian Legawiec4db3c0ef284d
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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`)```rubyclass Spree::Product < Spree.base_classinclude Spree::Metafields+ include Spree::Metadata++ acts_as_paranoidhas_many :variants, class_name: 'Spree::Variant', dependent: :destroyscope :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 paramsdef 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::Storeend```+```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 IDsAll 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 datamodule Spree::Api::V3class ProductSerializer < BaseSerializertypelize purchasable: :boolean, in_stock: :boolean, price: 'number | null'@@ -232,11 +276,11 @@ module Spree::Api::V3endend-# Admin serializer — extends store+# Admin serializer — extends store, adds back-office attributes + timestampsmodule Spree::Api::V3::Adminclass ProductSerializer < V3::ProductSerializertypelize 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_atendend```@@ -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 depspnpm build # build all packages (Turbo-cached)pnpm test # run all package testspnpm 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 ClientTypeScript 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 & VersioningPublished 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/LICENSEnew file mode 100644index 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.mdindex 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)+MITdiff --git a/packages/admin-sdk/package.json b/packages/admin-sdk/package.jsonindex 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/LICENSEnew file mode 100644index 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.mdindex 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++MITdiff --git a/packages/admin/package.json b/packages/admin/package.jsonindex 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/LICENSEnew file mode 100644index 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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",