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
---
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)