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.

12.2 KB
Raw Blame
---
title: Public API
sidebarTitle: Public API
description: Every importable symbol the dashboard exposes — components, hooks, registries, providers, and the SDK client. Treat this as the surface you can safely depend on.
---

The dashboard is structured as three packages. This page lists the symbols we commit to keeping — **treat anything not listed as internal**, liable to move or be renamed without a deprecation cycle, even where the barrel happens to export it today. Never reach past a package entry point into `@spree/dashboard-core/src/...`.

## `@spree/dashboard-core`

Default-import surface for plugins and customizations.

### Plugin facade

```ts
import { defineDashboardPlugin } from '@spree/dashboard-core'
```

Single declarative entry-point for every registry. See [Customization Quickstart](/developer/dashboard/customization/quickstart) for the full shape.

### Registries

```ts
import {
  nav,
  settingsNav,
  // route registry
  pluginRoutes,
  getPluginRoutes,
  matchPluginRoute,
  usePluginRoutes,
  // slot registry
  registerSlot,
  removeSlot,
  updateSlot,
  useSlotEntries,
  // table registry
  tables,
  // extension fields on built-in forms (hydrate + save with the host form)
  formFields,
  // input components for specific custom field definitions
  customFieldComponents,
} from '@spree/dashboard-core'
```

Each registry exposes `add`/`remove`/`update`-style mutators. See the per-feature pages for examples — form fields and custom field components are covered in the [custom form field recipe](/developer/dashboard/recipes/custom-form-field).

### Components

```ts
import {
  // Page chrome
  PageHeader,
  PageTabs,
  MobileTopBar,
  AppSidebar,
  SettingsSidebar,
  Slot,
  StoreSwitcher,
  // Tables
  ResourceTable,
  TableToolbar,
  BulkActionBar,
  // Form widgets
  StoreDatePicker,
  CountryCombobox,
  CountryStateFields,
  CurrencySelect,
  LocaleSelect,
  MarketCombobox,
  ResourceCombobox,
  ResourceMultiAutocomplete,
  TagCombobox,
  PreferencesForm,
  AddressFormDialog,
  // Permission
  Can,
  // Export
  ExportButton,
} from '@spree/dashboard-core'
```

### Hooks

```ts
import {
  useAuth,            // current admin user
  usePermissions,     // current admin's permissions
  useStore,           // current store
  useCommandPalette,  // ⌘K palette open/close state
  useGlobalSearch,    // global search query state
  useCountries,
  useCustomFields,
  useFileUpload,      // uploads a file through POST /files, resolves to its signed_id
  useExport,          // CSV export job lifecycle
  useResourceKey,     // store-scoped query key — use it for every custom query
  useResourceMutation, // useMutation wrapper with 422 handling
  useHostForm,        // the built-in form a slot widget renders inside (throws when absent)
  useOptionalHostForm, // same, but null when the page has no host form
} from '@spree/dashboard-core'
```

### Helpers

```ts
import {
  filtersToRansack,     // converts table filter state → Ransack params
  mapSpreeErrorsToForm, // 422 response → form.setError
  signedIdParam,        // image/document field → `<name>_signed_id` (set, `null` to remove, or omitted)
  // formatters
  formatPrice,          // Price object → display string
  formatStoreDateTime,  // ISO string → wall-clock in the store's timezone
  getInitials,          // full name → avatar initials
  // i18n
  i18n,                 // configured instance
  // form mappers — normalize optional text inputs before submitting
  blankToNull,
  blankToUndefined,
} from '@spree/dashboard-core'
```

### SDK client

```ts
import { adminClient } from '@spree/dashboard-core'
```

The shared `@spree/admin-sdk` instance configured for the host's API URL. Use this everywhere instead of constructing your own.

The package entry point loads the whole framework — every registry, component and translation. A small host app that builds its own screens and only needs the client and sign-in can import from subpaths instead, which keeps the rest out of its bundle:

```ts
import { adminClient } from '@spree/dashboard-core/client'          // the SDK instance alone
import { setApiClient } from '@spree/dashboard-core/api-client'     // registers the client the providers use
import { AuthProvider } from '@spree/dashboard-core/providers/auth-provider'
import { useAuth } from '@spree/dashboard-core/hooks/use-auth'
```

### Providers

```ts
import {
  AuthProvider,
  PermissionProvider,
  StoreProvider,
} from '@spree/dashboard-core'
```

Mount these at the root of your app shell. The shipped app shell does this for you — re-export only if you're composing a custom shell (vendor panel, etc.).

### Vite plugin

```ts
import { spreeDashboardPlugin } from '@spree/dashboard-core/vite'
```

Vite plugin that resolves third-party dashboard plugins and injects Tailwind `@source` directives for their CSS. See [Distributing](/developer/dashboard/plugins/distributing) for the host wiring.

## `@spree/dashboard-ui`

Design system primitives. Headless — accept data via props, never reach for providers or hooks.

### shadcn-style primitives

```ts
import {
  Button,
  Card, CardContent, CardHeader, CardTitle, CardDescription, CardFooter,
  Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter,
  Sheet, SheetContent, SheetHeader, SheetTitle, SheetFooter,
  DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem,
  Input, Textarea, Checkbox, RadioGroup, Switch,
  Select, SelectTrigger, SelectContent, SelectItem, SelectValue,
  Combobox,
  Field, FieldLabel, FieldError, FieldDescription,
  Table, TableHeader, TableBody, TableRow, TableCell,
  Badge,
  Avatar,
  Skeleton,
  Tooltip, TooltipTrigger, TooltipContent,
  Toaster,
} from '@spree/dashboard-ui'
```

Toast *notifications* come from [sonner](https://sonner.emilkowal.ski/) directly — `import { toast } from 'sonner'` — while `<Toaster>` (the mount point, already rendered by the app shell) is the only part re-exported here.

### Composed components

Higher-level pieces that bundle multiple primitives but still take data via props:

```ts
import {
  ResourceLayout,     // header + main + sidebar grid
  Empty, EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, EmptyContent,
  ColorPicker,
  // …more land here as we extract from @spree/dashboard
} from '@spree/dashboard-ui'
```

`Empty*` composes via children (icon in `<EmptyMedia>`, actions in `<EmptyContent>`) rather than taking `title`/`description` props.

### Utilities

```ts
import { cn } from '@spree/dashboard-ui'  // clsx + tailwind-merge
```

## `@spree/dashboard`

The app shell, and the single import a host application needs. It re-exports everything from `@spree/dashboard-core` and `@spree/dashboard-ui`, so code in your own dashboard app never has to work out which package an export lives in:

```ts
import { defineDashboardPlugin, useStore, adminClient, Button, ResourceTable } from '@spree/dashboard'
```

**Plugins don't import from here** — a plugin extends the dashboard through `@spree/dashboard-core` and never renders the shell, so importing the shell would pull the whole app into a package meant to plug into it.

The host (the `dashboard-starter` project, or a create-spree-app project) is also what mounts the admin:

```ts
import { createDashboardRouter, Dashboard } from '@spree/dashboard'
```

- **`Dashboard`** — the app shell component (provider stack + router). Render it with a router: `<Dashboard router={router} />`.
- **`createDashboardRouter(routeTree)`** — builds the router from the host's generated `routeTree.gen.ts` (the shell's routes composed with every installed plugin's file routes). The starter's `main.tsx` wires these together; you rarely write this by hand.

Two subpath entries complete the surface:

```ts
import { spreeDashboardPlugin } from '@spree/dashboard/vite'  // Vite plugin: Tailwind, discovery, route composition
import '@spree/dashboard/styles.css'                          // the app's CSS entry
```

A host app that builds its own sign-in or onboarding screens, rather than mounting `<Dashboard />`, can reuse the dashboard's building blocks one module at a time without pulling in the app shell:

```ts
import { AuthShell } from '@spree/dashboard/components/spree/auth-shell'              // two-column sign-in layout
import { StoreSetupFields } from '@spree/dashboard/components/spree/store-setup-fields' // store name, country, language, currency
import { useAuthProviders, authCallbackErrorKey } from '@spree/dashboard/hooks/use-auth-providers' // password + SSO options, SSO error copy
import { loginFormSchema, resetPasswordFormSchema } from '@spree/dashboard/schemas/auth' // Zod schemas for the auth forms
```

Their translations ship with `@spree/dashboard-core`, so they render translated as soon as its i18n instance is loaded.

A plugin page that works on an order in its own layout — a quote over a draft order, say — reuses the order page's building blocks from one subpath:

```ts
import {
  useOrder,               // the order with the expands the order page loads
  useOrderItemsEditor,    // staged line editing: form, picker hand-off, one-transaction save
  OrderEditItemsTable,    // quantities, removals and, on drafts, negotiated unit prices
  AddLineItemDialog,      // the variant picker
  OrderTotalsCard,        // totals that preview the staged edits
  CustomerCard,
  OrderLogisticsCard,
  OrderPurchaseOrderCard,
  companyAutocompleteProps,  // the new-order page's pickers: companies, then
  customerAutocompleteProps, // the customers who can buy for the chosen one
} from '@spree/dashboard/orders'
```

The same entry also exports the order page's other sidebar cards (`DiscountsCard`, `OrderSummaryCard`, `TagsCard`, `SpecialInstructionsCard`, `InternalNoteCard`), `CompanyComboboxOption` for rendering the company picker's options, and `useOrderMutation` for a save that refreshes the order.

`useOrderItemsEditor(order)` returns the `form` and `fields` the table renders, `items` for the totals card, `stageVariant` for the picker's `onSelect`, and `save(values)` / `discard()`. Nothing reaches the server until `save`, which resolves `true` once the lines are saved and re-baselines the form on the saved order. Once the order has loaded, render `OrderTotalsCard` against `savedOrder` (`{savedOrder && <OrderTotalsCard order={savedOrder} items={items} />}`) — it follows the save even before your `order` refreshes — and lock the editing controls while `isSaving` (`<OrderEditItemsTable disabled={isSaving} />`, and the button that opens the picker): the save replaces the form when it finishes. Their copy lives in `@spree/dashboard`'s locales, which the dashboard loads, so they render translated on any page the dashboard routes to.

A few names exist in both re-exported packages — the design system ships a presentational component and the framework wraps it with data (`ResourceCombobox`, `StatusCard`, `Slot`, `DateRange`, `ResourceMultiAutocomplete`). The facade gives you the framework's version, which is the one an application wants. Reach past it when you want the presentational half:

```ts
import { ResourceCombobox } from '@spree/dashboard-ui'  // takes its options as props
```

Importing from `@spree/dashboard` pins your code to the deployable app's version, which is what a host app wants and what a distributed plugin must avoid.

## What about `@spree/admin-sdk`?

The Admin API client is a separate package and a public dependency. Import types and `SpreeError` from it directly:

```ts
import {
  type Product,
  type Order,
  type Customer,
  SpreeError,
} from '@spree/admin-sdk'
```

The `adminClient` instance, by contrast, comes from `@spree/dashboard-core` so the host owns the configured singleton.

## Stability

Anything on this page is covered by semver from `@spree/dashboard-core` 1.0.0 onward. Pre-1.0 we may rename, but we'll call breaking moves out in the changelog.

Anything not listed here is internal. If you find yourself wanting it, open a discussion — it's a sign we should promote it to the public surface.

## Reference

- [`packages/dashboard-core/src/index.ts`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/index.ts) — canonical export list
- [`packages/dashboard-ui/src/index.ts`](https://github.com/spree/spree/blob/main/packages/dashboard-ui/src/index.ts)
- [`packages/admin-sdk/src/index.ts`](https://github.com/spree/spree/blob/main/packages/admin-sdk/src/index.ts)