The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
UI Architecture — @mercurjs/admin, @mercurjs/vendor, @mercurjs/dashboard-shared
This document is the contract for every UI surface in the Mercur monorepo. It covers three packages that ship one consistent dashboard experience:
@mercurjs/dashboard-shared— the design-system layer. React primitives, hooks, and helpers (forms, modals, tables, layout shells, action menus, query-key factory) consumed by both dashboards.@mercurjs/admin— the marketplace operator dashboard. Mounted byapps/admin-teston port7000. Hits/admin/*viasdk.admin.*.@mercurjs/vendor— the seller dashboard. Mounted byapps/vendoron port7001. Hits/vendor/*viasdk.vendor.*.
Both dashboards share identical structure, primitives, and visual rules; they differ only in pages, the SDK namespace, sidebar route set, and which audience-specific data they fetch. Whenever this document says "the dashboard" without qualifier, the rule applies to both admin and vendor. Differences are called out explicitly.
Layer diagram
+-----------------------------------------------------------------------+
| Hosts |
| apps/admin-test (Vite, port 7000) -> mounts @mercurjs/admin |
| apps/vendor (Vite, port 7001) -> mounts @mercurjs/vendor |
+-----------------------------------------------------------------------+
| App root (packages/{admin,vendor}/src/app.tsx) |
| TooltipProvider |
| HelmetProvider |
| QueryClientProvider (shared queryClient) |
| ThemeProvider (Medusa UI) |
| I18nProvider (i18next + browser language detector) |
| RouterProvider (react-router-dom) |
| Toaster (Medusa UI) |
+-----------------------------------------------------------------------+
| Layouts |
| ProtectedRoute -> MainLayout / SettingsLayout / PublicLayout |
| Shell + Sidebar (MainSidebar) + Outlet |
+-----------------------------------------------------------------------+
| Pages (packages/{admin,vendor}/src/pages/<domain>/...) |
| - List -> SingleColumnPage + Container (divide-y, p-0) |
| - Detail -> TwoColumnPage with Main / Sidebar Sections |
| - Create -> RouteFocusModal + TabbedForm |
| - Edit -> RouteDrawer + Form |
+-----------------------------------------------------------------------+
| Design-system layer |
| @mercurjs/dashboard-shared (Form, TabbedForm, RouteFocusModal, |
| RouteDrawer, SingleColumnPage, TwoColumnPage, ActionMenu, |
| DataTable, SwitchBox, FileUpload, ChipInput, queryKeysFactory) |
+-----------------------------------------------------------------------+
| Data layer |
| src/lib/client -> @mercurjs/client (typed sdk) |
| src/hooks/api/*.tsx -> TanStack Query hooks per backend domain |
| src/lib/query-key-factory -> queryKeysFactory(domain) for cache keys|
+-----------------------------------------------------------------------+
Package map
@mercurjs/dashboard-shared — the primitives
Library only. No pages, no routes, no providers, no i18n. Built with tsup, re-exports everything from src/index.ts.
packages/dashboard-shared/src/
index.ts Re-exports components/* and hooks/*
lib/
query-key-factory.ts queryKeysFactory + TQueryKey + UseQueryOptionsWrapper
components/
common/ form, action-menu, section, skeleton,
empty-table-content, switch-box, file-upload,
chip-group, listicle, tax-badge, thumbnail,
json-view-section, metadata-section, ...
layout/pages/ SingleColumnPage, TwoColumnPage
modals/ RouteFocusModal, RouteDrawer, StackedDrawer,
StackedFocusModal, RouteModalForm,
route-modal-provider, stacked-modal-provider
tabbed-form/ TabbedForm, useTabbedForm, defineTabMeta, TabDefinition
forms/ Address, email, metadata composite forms
inputs/ Handle, Combobox, Country/Province, ChipInput, ...
data-grid/, data-table/, table/ TanStack-Table data tables + cells
filtering/ Filter UI for tables
utilities/ KeyboundForm, ErrorBoundary, ...
hooks/ use-data-table, use-document-direction,
use-debounced-search, use-query-params, ...
Public surface (consumed by both admin and vendor):
import {
// layout
SingleColumnPage, TwoColumnPage,
// modals
RouteFocusModal, RouteDrawer, useRouteModal,
StackedDrawer, StackedFocusModal, useStackedModal,
// forms
Form, SwitchBox, FileUpload, ChipInput,
TabbedForm, useTabbedForm, defineTabMeta, type TabDefinition,
// tables
DataTable, useDataTable, type Filter,
// common UI
ActionMenu, NoResults, NoRecords, Skeleton, SectionRow,
// data-layer helper
queryKeysFactory, type TQueryKey, type UseQueryOptionsWrapper,
} from "@mercurjs/dashboard-shared"
Rule: any new cross-dashboard primitive belongs in dashboard-shared. Page-specific composites stay in the consuming package.
@mercurjs/admin — operator dashboard
packages/admin/src/
app.tsx App root + providers
get-route-map.tsx Static route map merged with virtual:mercur/routes
index.ts Re-exports (TabbedForm, Form, DataTable, ...)
assets/ Static assets
i18n/ i18next config + translations per language
providers/ ThemeProvider, KeybindProvider, SearchProvider, SidebarProvider
lib/
client/ sdk = createClient<Routes>(...) + fetchQuery / uploadFilesQuery
query-client.ts Shared TanStack QueryClient
query-key-factory.ts queryKeysFactory(domain) (mirrors the shared one)
form-helpers.ts transformNullableFormData / transformNullableFormNumber
hooks/
api/<domain>.tsx One file per backend domain — sdk.admin.* + TanStack Query
use-data-table.tsx, use-document-direction.tsx, use-debounced-search.tsx,
use-query-params.tsx, ...
components/
common/, layout/, modals/, tabbed-form/, forms/, inputs/,
data-table/, table/, filtering/, search/, utilities/
(local equivalents kept until fully migrated to
`@mercurjs/dashboard-shared`)
pages/<domain>/ One folder per route segment (see Page anatomy)
Operator-specific characteristics:
- SDK namespace:
sdk.admin.*(e.g.sdk.admin.productCategories.$id.query(...)). - Sidebar (
MainLayout,useCoreRoutes()): Orders → Products → Inventory → Customers → Promotions → Price Lists → Stores → Payouts. - Authentication: login, accept-invite, reset-password are public routes; everything else under
<ProtectedRoute>.
@mercurjs/vendor — seller dashboard
packages/vendor/src/
app.tsx Same App shape as admin
get-route-map.tsx Vendor route map merged with virtual:mercur/routes
index.ts Re-exports (TabbedForm, Notifications)
assets/, i18n/, providers/ Same shape as admin
lib/ client/ (sdk.vendor.*), query-client, query-key-factory
hooks/ api/<domain>.tsx — uses sdk.vendor.* + TanStack Query
components/ Same shape as admin (common, layout, modals, tabbed-form, ...)
+ onboarding-wizard (vendor-specific)
pages/<domain>/ Vendor uses two folder-naming variants — see Page anatomy
Seller-specific characteristics:
- SDK namespace:
sdk.vendor.*(e.g.sdk.vendor.productCategories.$id.query(...)). - Includes vendor-only flows:
onboarding,register,store-select,homedashboard with seller-scoped metrics. No platform-wide pages (e.g. nosellerslist, no platform-wide commission management). onboarding-wizardcomponent lives undercomponents/because it is vendor-only.- Folder naming inside
pages/<domain>/may use_components/(instead ofcomponents/) and[id]/(instead of<domain>-detail/). Both styles are accepted in the vendor package today.
Routing model (admin + vendor)
Routes live in two places and are merged at runtime:
src/get-route-map.tsx— the static route map shipped by the dashboard package. Each leaf is alazy()import of a page module. Pages export aComponent(and optionallyloader,Breadcrumb,ErrorBoundary).virtual:mercur/routes— generated by@mercurjs/dashboard-sdkfrom files dropped underapps/<host>/src/routes/. Pages with matching paths override the base; non-matching paths are appended (seegetRouteMap::mergeRoutes).
Three top-level buckets exist (createRouteMap(getRoutesByType(customRoutes, type))):
main— under<ProtectedRoute><MainLayout>(default surface).settings— under<ProtectedRoute><SettingsLayout>(/settings/*).public— under<PublicLayout>(login, reset password, accept invite, vendor register).
The sidebar in MainLayout is composed of two parts:
- Core routes via
useCoreRoutes()— hard-coded order per dashboard:- Admin: Orders → Products → Inventory → Customers → Promotions → Price Lists → Stores → Payouts.
- Vendor: seller-scoped equivalents (orders, products, categories, collections, customers, promotions, campaigns, price-lists, payouts, etc.).
- Custom routes from
virtual:mercur/menu-items(sorted byrank).
Page anatomy
Every domain folder follows the same shape across both dashboards:
src/pages/<domain>/
index.ts barrel that re-exports each sub-page module
common/ cross-page hooks, types, utils, shared subcomponents
hooks/use-delete-<entity>-action.tsx
utils.ts
<domain>-list/ list page (vendor may use bare <domain>/ root)
<domain>-list.tsx page Component
index.ts re-export
components/<domain>-list-table/ (vendor variant: _components/...)
<domain>-list-table.tsx Container shell
<domain>-list-header.tsx Title + Actions
<domain>-list-data-table.tsx DataTable wiring + row actions
use-<domain>-table-columns.tsx
use-<domain>-table-query.tsx
<domain>-detail/ (vendor variant: [id]/)
<domain>-detail.tsx page Component (TwoColumnPage)
breadcrumb.tsx Breadcrumb component
loader.ts react-router data loader
components/<section>-section/... Each section is a Container
<domain>-create/
<domain>-create.tsx RouteFocusModal wrapper
components/create-<domain>-form/
create-<domain>-form.tsx TabbedForm host + useForm + handleSubmit
create-<domain>-<tab>.tsx One file per tab, exports Root with _tabMeta
schema.ts Zod schema + inferred type
<domain>-edit/
<domain>-edit.tsx RouteDrawer wrapper, fetches entity by :id
components/edit-<domain>-form/
edit-<domain>-form.tsx RouteDrawer.Form host
Vendor-specific variants you may see today:
pages/categories/_components/instead ofpages/categories/category-list/components/.pages/categories/[id]/...instead ofpages/categories/category-detail/....
Prefer the admin-style convention (category-list/, category-detail/) for new pages; both styles are accepted in vendor until a migration sweep aligns them.
Every page is also exported as a Compound Component: a Root is combined with named subparts via Object.assign(Root, { Header, HeaderTitle, ... }). Consumers (custom pages, downstream blocks) can either render the page as-is, or replace any slot by passing children explicitly. Example:
export const CategoryListPage = Object.assign(Root, {
Table: CategoryListTable,
Header: CategoryListHeader,
HeaderTitle: CategoryListTitle,
HeaderActions: CategoryListActions,
DataTable: CategoryListDataTable,
})
The Root pattern uses Children.count(children) > 0 ? children : <DefaultContent /> so the page renders defaults when used unchanged and exposes every part for overrides.
Layout primitives
All pages mount inside one of two layouts (components/layout/pages locally, or @mercurjs/dashboard-shared):
SingleColumnPage<TData>
- Vertical stack with
flex flex-col gap-y-3. - Renders children, optional
MetadataSection, optionalJsonViewSection, optional<Outlet />for nested modal routes. - Use for list pages, settings pages, and simple detail pages.
TwoColumnPage<TData>
- Grid
xl:grid-cols-[minmax(0,_1fr)_440px], vertical stack until xl breakpoint. - Exactly two children required:
<TwoColumnPage.Main />and<TwoColumnPage.Sidebar />. showJSONandshowMetadatatoggle a JSON viewer and a key-value metadata section. Passdata={entity}whenever these flags are on — there is a dev-mode warning if you forget.- Sidebar is
xl:max-w-[440px]. Stack each section withgap-y-3.
Section container
Every section inside a page is wrapped in Container from @medusajs/ui with two consistent classes:
<Container className="divide-y p-0">
<div className="flex items-center justify-between px-6 py-4">
<Heading>{t("domain.section.title")}</Heading>
{/* actions */}
</div>
{/* divided rows below */}
</Container>
divide-y+p-0is the standard section shell.- Each row uses
px-6 py-4. - Header row:
flex items-center justify-between px-6 py-4with<Heading>on the left and anActionMenu/Buttoncluster on the right. - For label/value rows prefer
SectionRow(grid grid-cols-2 gap-4 px-6 py-4withtext-ui-fg-subtle), or inline grids for one-off rows.
Forms
Forms are built with React Hook Form + Zod + the Form primitive (components/common/form, also exported from @mercurjs/dashboard-shared). Never use raw Controller — always go through Form.Field.
The shape of every field
<Form.Field
control={form.control}
name="title"
render={({ field }) => (
<Form.Item>
<Form.Label>{t("fields.title")}</Form.Label>
<Form.Control>
<Input autoComplete="off" {...field} />
</Form.Control>
<Form.ErrorMessage />
</Form.Item>
)}
/>
Rules:
- Wrap every field in
<Form.Item>so error and label ids are wired through context. Form.Labelsupportsoptional(auto-appends(optional)),tooltip(rendersInformationCircleSolidfrom@medusajs/icons), andicon.Form.ErrorMessagereads the field error from RHF automatically — never render error text manually.- Use
Form.Hintfor help text below the input (uses<Hint>from@medusajs/ui). - For selects, destructure
{ ref, onChange, ...field }and passonValueChange={onChange}; passdir={useDocumentDirection()}for RTL. - Wrap the form element in
<KeyboundForm>(fromcomponents/utilities/keybound-form) so Cmd/Ctrl+Enter submits.
Schemas
- One Zod schema per form, exported alongside the form (
schema.tsor co-located). - Use
zodResolver(schema)and infer the form type withz.infer<typeof Schema>. - For nullable / optional values pass through
transformNullableFormData/transformNullableFormNumber(lib/form-helpers.ts) before calling the mutation.
Layout
- Wrap form bodies in
flex w-full max-w-[720px] flex-col gap-y-8for tab content. For drawer bodies useflex flex-col gap-y-4. - Two-column field rows:
grid grid-cols-1 gap-4 md:grid-cols-2. - For toggles use
SwitchBox(components/common/switch-box) which already adds the card styling (bg-ui-bg-component shadow-elevation-card-rest rounded-lg p-3).
Create flow — RouteFocusModal + TabbedForm
Create pages live behind a routed full-screen modal:
const Root = ({ children }: { children?: ReactNode }) => (
<RouteFocusModal>
<RouteFocusModal.Title asChild>
<span className="sr-only">{t("...title")}</span>
</RouteFocusModal.Title>
{Children.count(children) > 0 ? children : <CreateXForm />}
</RouteFocusModal>
)
RouteFocusModalopens on mount, navigates toprev(default..) on close, and supports stacked drawers/modals viaStackedModalProvider.RouteFocusModal.FormisRouteModalForm: blocks navigation while the form is dirty and shows a confirmationPrompt.
For multi-step creates, use TabbedForm (components/tabbed-form):
<TabbedForm form={form} onSubmit={handleSubmit} isLoading={isPending}>
<CreateXDetails />
<CreateXOrganize />
</TabbedForm>
- Each tab is a component whose
RootcarriesRoot._tabMeta = defineTabMeta<Schema>({ id, labelKey, validationFields, isVisible? }). validationFieldstriggers field-level validation on Continue; the last tab submits.- Tab body uses the standard padding:
flex flex-col items-center p-16→flex w-full max-w-[720px] flex-col gap-y-8. TabbedForm.Tabis the bare layout primitive; prefer typed tab components with_tabMeta.- Keyboard: Cmd/Ctrl+Enter advances or submits (handled by
TabbedForminternally). - Default footer renders Cancel + Continue/Save; override via the
footerprop if needed.
Edit flow — RouteDrawer
Quick edits live in a side drawer:
<RouteDrawer>
<RouteDrawer.Header>
<RouteDrawer.Title asChild>
<Heading>{t("domain.edit.header")}</Heading>
</RouteDrawer.Title>
<RouteDrawer.Description className="sr-only">
{t("domain.edit.description")}
</RouteDrawer.Description>
</RouteDrawer.Header>
{ready && <EditXForm entity={entity} />}
</RouteDrawer>
Inside the form:
<RouteDrawer.Form form={form}>
<KeyboundForm onSubmit={handleSubmit} className="flex flex-1 flex-col">
<RouteDrawer.Body>
<div className="flex flex-col gap-y-4">{/* fields */}</div>
</RouteDrawer.Body>
<RouteDrawer.Footer>
<div className="flex items-center gap-x-2">
<RouteDrawer.Close asChild>
<Button size="small" variant="secondary">
{t("actions.cancel")}
</Button>
</RouteDrawer.Close>
<Button size="small" type="submit" isLoading={isPending}>
{t("actions.save")}
</Button>
</div>
</RouteDrawer.Footer>
</KeyboundForm>
</RouteDrawer.Form>
- Always gate the form behind
ready = !isPending && !!entityso the drawer is empty until data is loaded. - Use
useRouteModal().handleSuccess(path?)insideonSuccessto close the modal and (optionally) navigate. - Throw render-time errors (
if (isError) throw error) soErrorBoundarycatches them.
Tables and lists
Container shell
List pages mount a SingleColumnPage with a Container that holds a header + DataTable:
<SingleColumnPage hasOutlet>
<Container className="divide-y p-0">
<CategoryListHeader />
<CategoryListDataTable />
</Container>
</SingleColumnPage>
Header
flex items-center justify-between px-6 py-4 with two parts:
Title:<Heading>+<Text size="small" className="text-ui-fg-subtle">{subtitle}</Text>.Actions:<Button size="small" variant="secondary" asChild><Link to="...">…</Link></Button>cluster (e.g. Organize, Create).
Data table
- Use
DataTable(_DataTablein older admin imports) +useDataTable(components/table/data-table,hooks/use-data-table, or the@mercurjs/dashboard-sharedexports). - Build columns with
createColumnHelper<Row>()and anactionsdisplay column that renders<ActionMenu>. - For row navigation, pass
navigateTo={(row) => row.id}so clicking a row enters the detail route. - Standard
PAGE_SIZE = 20. - Use
keepPreviousDatafrom TanStack Query for smooth pagination. - Filters / search are wired through the
useXTableQueryhook (returns{ raw, searchParams }).
Empty states
Use the two variants from components/common/empty-table-content (or @mercurjs/dashboard-shared):
<NoResults />— filtered/searched view returned nothing (usesMagnifyingGlass).<NoRecords action={{ to, label }} />— entity has no records yet (usesExclamationCircle, optional CTA button or transparent-icon-left link).
Row & section actions — ActionMenu
components/common/action-menu is the only acceptable way to render a row or section action menu:
<ActionMenu
groups={[
{ actions: [{ label: t("actions.edit"), icon: <PencilSquare />, to: "edit" }] },
{ actions: [{ label: t("actions.delete"), icon: <Trash />, onClick: handleDelete }] },
]}
/>
- Each
Actionis either{ to }(renders a<Link>) or{ onClick }. - Group ordering is meaningful — the trigger renders dropdown groups in order with separators between them. Convention: edit/navigation actions first; destructive actions last in their own group.
- Provide
disabled+disabledTooltipinstead of hiding actions when context requires. - The default trigger is
<IconButton size="small"><EllipsisHorizontal /></IconButton>. Passchildrento override the trigger element.
Delete flow
Encapsulate destructive actions in a use-delete-<entity>-action.tsx hook under pages/<domain>/common/hooks/. The hook:
- Calls
usePrompt()from@medusajs/uiwith i18ntitle,description,confirmText,cancelText. - Awaits user confirmation, then calls the mutation.
- Toasts via
toast.success/toast.error. - Navigates back on success.
This is the only sanctioned destructive-action pattern; never inline a confirmation modal.
Data fetching
All HTTP traffic goes through the typed SDK: sdk (and fetchQuery for the few edge cases) live in lib/client. Never call fetch directly from a page.
SDK namespaces
| Package | Namespace | Example |
|---|---|---|
@mercurjs/admin |
sdk.admin.* |
sdk.admin.productCategories.$id.query({ $id: id, ...query }) |
@mercurjs/vendor |
sdk.vendor.* |
sdk.vendor.productCategories.$id.query({ $id: id, ...query }) |
Both surfaces follow the same route-based pattern:
sdk.<surface>.entities.query({ ...query }) // list (GET)
sdk.<surface>.entities.$id.query({ $id: id, ...query }) // detail (GET)
sdk.<surface>.entities.mutate(payload) // create (POST)
sdk.<surface>.entities.$id.mutate({ $id: id, ...payload }) // update (PATCH/POST)
sdk.<surface>.entities.$id.delete({ $id: id }) // delete (DELETE)
Inputs/outputs come from InferClientInput / InferClientOutput (@mercurjs/client). Errors are ClientError from @mercurjs/client.
TanStack Query hooks (src/hooks/api/<domain>.tsx)
One file per backend domain. Each file:
- Creates
const xQueryKeys = queryKeysFactory("x"). - Exposes
useX(id, query?, options?)for detail,useXList(query?, options?)for list, anduseCreate/Update/DeleteX(options?)for mutations. - Inside mutations, invalidate the right keys via
queryClient.invalidateQueries({ queryKey: xQueryKeys.lists() })(ordetails()/detail(id)), and forwardonSuccessthrough to the caller.
queryKeysFactory from @mercurjs/dashboard-shared (or local lib/query-key-factory.ts) is the standard shape: all / lists() / list(query) / details() / detail(id, query?). Use it for any new domain.
For initial data, page detail components use a loader.ts (react-router data loader) and pass the result to the hook via initialData.
Internationalization
- Every user-facing string goes through
useTranslation()/t(key). - Translation files live in
src/i18n/translations/<lng>.jsonper dashboard package (English is canonical; other locales are merged).$schema.jsondocuments the shape and is enforced by tests ini18n/translations/__tests__. - Common keys:
actions.*(save, cancel, edit, delete, create, continue),fields.*(title, handle, description, optional),general.*(areYouSure, noResultsTitle, noRecordsTitle, unsavedChangesTitle),<domain>.domain(sidebar label),<domain>.subtitle(page subtitle),<domain>.<verb>.header / hint / successToast / description. - Tab labels use
labelKeyon_tabMeta; column headers, drawer titles, dialog copy all go through i18n keys. - Tooltip content (
Form.Label tooltip={t(...)}) is also translated. - For RTL support, always pass
dir={useDocumentDirection()}toSelect,DropdownMenu, etc.
Design system rules
@medusajs/ui is the only UI library
- Use components from
@medusajs/ui:Container,Button,IconButton,Heading,Text,Hint,Label,Input,Textarea,Select,Switch,Checkbox,RadioGroup,DropdownMenu,Tooltip,Badge,StatusBadge,Drawer,FocusModal,Prompt,ProgressTabs,Tabs,Avatar,Divider,Toaster(+toast/usePrompt). - For Radix primitives that Medusa UI does not re-export, use the bundled
radix-uipackage (e.g.Label,Slot). - Never introduce a parallel UI library or restyle Medusa UI components with custom CSS. Custom variants belong on top of Medusa UI primitives.
Icons
- Only icons from
@medusajs/iconsare allowed (e.g.PencilSquare,Trash,EllipsisHorizontal,MagnifyingGlass,PlusMini,InformationCircleSolid,OpenRectArrowOut,ExclamationCircle,BuildingStorefront,CogSixTooth). - Do not bundle other icon packs (lucide, heroicons, custom SVGs) inside the dashboard packages.
- For row/section actions, place the icon inside the
ActionMenuaction descriptor (icon: <PencilSquare />). - Icons in dropdowns/menus inherit color via the
[&_svg]:text-ui-fg-subtleutility; disabled menu items dim to[&_svg]:text-ui-fg-disabled.
Colors
Use only the Medusa UI color tokens. Never write hex colors, rgb(...), or palette names. Common tokens by purpose:
- Backgrounds:
bg-ui-bg-base,bg-ui-bg-subtle,bg-ui-bg-subtle-hover,bg-ui-bg-component,bg-ui-bg-disabled,bg-ui-bg-field,bg-ui-bg-highlight. - Foreground:
text-ui-fg-base,text-ui-fg-subtle,text-ui-fg-muted,text-ui-fg-disabled,text-ui-fg-interactive,text-ui-fg-on-color,text-ui-fg-error. - Borders / dividers:
border-ui-border-base,border-ui-border-strong,border-ui-border-loud. - Shadows / focus:
shadow-elevation-card-rest,shadow-borders-focus.
Apply tokens via Tailwind utilities; clx (re-exported from @medusajs/ui) is the canonical helper for conditional class merging.
Typography
- Headings:
<Heading>for section titles,<Heading level="h2">for sidebar sections; never style with raw<h*>elements. - Body text:
<Text size="small" leading="compact">for table-row text and section rows;<Text size="xsmall">for chips and breadcrumb segments; combine withweight="plus"for emphasized labels. - Hints:
<Hint>(variantinfoby default,errorforForm.ErrorMessage). - Subtle copy:
<Text className="text-ui-fg-subtle">/text-ui-fg-muted. Never roll your own<p className="text-gray-500">.
Spacing
- Section row vertical rhythm:
px-6 py-4. Cluster gaps:gap-x-2,gap-x-3,gap-x-4. Outer page stack:gap-y-3. Form body stack:gap-y-4(drawers) /gap-y-8(focus modals). Two-column field grid:grid grid-cols-1 gap-4 md:grid-cols-2. - Buttons inside compact toolbars and footers:
size="small". Variants:primary(default save),secondary(cancel / nav),transparent(icon-only or inline link triggers).
Status badges
Use StatusBadge with the helper color/label utilities in pages/<domain>/common/utils.ts (getIsActiveProps, getIsInternalProps, etc.). Place badges in the section header row to the right of the title, before the ActionMenu.
Skeletons
Use Skeleton (components/common/skeleton) for placeholders. For detail pages, the corresponding TwoColumnPageSkeleton mirrors the section count so the layout doesn't jump.
Test ids
Every interactive element in a list, header, action, form, or modal should carry data-testid (e.g. category-create-form-name-input, sidebar-header-dropdown-trigger). Use kebab-case scoped to the page/section. New components must add ids in the same pattern.
Extension model
Consumers extend the dashboards without forking by:
- Drop-in routes —
apps/<host>/src/routes/**/page.tsxis scanned by@mercurjs/dashboard-sdkand merged into the route map (seeget-route-map.tsx::mergeRoutes). - Compound overrides — every page exports
Object.assign(Root, { Header, HeaderTitle, HeaderActions, ... }). Custom pages can re-render the page with their own children:<CategoryListPage> <CategoryListPage.Header> <CategoryListPage.HeaderTitle /> <MyCustomActions /> </CategoryListPage.Header> <CategoryListPage.DataTable /> </CategoryListPage> - Blocks — installable feature packages via
mercurjs add; declareadmin_ui/vendor_uientry points inblocks.json. - Public exports — the canonical primitives consumers should import:
- From
@mercurjs/dashboard-shared:TabbedForm,useTabbedForm,defineTabMeta,TabDefinition,Form,SwitchBox,FileUpload,ChipInput,DataTable,useDataTable,Filter,SingleColumnPage,TwoColumnPage,RouteFocusModal,RouteDrawer,ActionMenu,NoResults,NoRecords,SectionRow,Skeleton,queryKeysFactory,TQueryKey,UseQueryOptionsWrapper. - From
@mercurjs/admin: same primitives are re-exported plusNotificationsandPRODUCT_DETAIL_FIELDS/PRODUCT_DETAIL_QUERY. - From
@mercurjs/vendor:TabbedForm,useTabbedForm,TabDefinition,Notifications.
- From
When adding shared primitives, place them in @mercurjs/dashboard-shared and re-export from the dashboard packages only when there is a useful default to bake in.
Page-authoring checklist
When adding a new dashboard page (admin or vendor), conform to these rules in order:
- Folder shape —
src/pages/<domain>/<domain>-{list,detail,create,edit}/withindex.ts,<page>.tsx, and acomponents/subfolder for any non-trivial subcomponent. (Vendor_components/and[id]/variants are accepted; prefer the admin shape for new code.) - Layout — pick
SingleColumnPage(lists, simple settings) orTwoColumnPage(detail with sidebar). Wrap every section in<Container className="divide-y p-0">. Section header isflex items-center justify-between px-6 py-4with<Heading>+ actions. - Compound export — define
Rootand assembleObject.assign(Root, { ... }). UseChildren.count(children) > 0 ? children : <Defaults />so the page renders defaults but accepts overrides. - Forms — React Hook Form +
zodResolver. Wrap every field inForm.Field→Form.Item→Form.Label/Form.Control/Form.ErrorMessage. UseKeyboundFormfor keyboard submit. Run nullable values throughtransformNullableFormData. - Create —
RouteFocusModalhost +TabbedForm. Each tab carries_tabMetaviadefineTabMetawithid,labelKey,validationFields. Body padding:p-16→max-w-[720px] gap-y-8. - Edit —
RouteDrawerhost +RouteDrawer.Form+KeyboundForm. Body usesflex flex-col gap-y-4. Footer: secondary Cancel + primary Save withisLoading={isPending}. - Data — pull data via hooks in
src/hooks/api/<domain>.tsx, callingsdk.admin.*(admin) orsdk.vendor.*(vendor). Always invalidatelists()/details()/detail(id)keys in mutations. Throw onisErrorsoErrorBoundarycatches it. UseSkeleton/TwoColumnPageSkeletonwhile loading. - Tables —
DataTable+useDataTable. Page size 20. Add anactionscolumn rendering<ActionMenu>. Empty states useNoRecords/NoResults. - Destructive actions — extract to
pages/<domain>/common/hooks/use-delete-<entity>-action.tsx. AlwaysusePrompt()then toast. - Strings — every visible string uses
t("...")with keys placed under the domain's namespace. Add new keys tosrc/i18n/translations/en.jsonfirst. - Icons — only from
@medusajs/icons. - Colors / typography / spacing — only Medusa UI tokens (
text-ui-fg-*,bg-ui-bg-*,border-ui-border-*,shadow-elevation-*) and the spacing scale documented above. - Test ids — kebab-case
data-testidon every interactive element, headings, inputs, buttons, dropdown items.
When in doubt, mirror an existing page in the same family (lists → category-list, detail → category-detail, create wizards → product-create, drawer edits → category-edit) — those are the canonical references for both dashboards.
Where to put new code
| You are adding… | Put it in |
|---|---|
| A new operator (admin) page | packages/admin/src/pages/<domain>/... |
| A new seller (vendor) page | packages/vendor/src/pages/<domain>/... |
| A new TanStack Query hook | packages/<dashboard>/src/hooks/api/<domain>.tsx |
| A reusable UI primitive used by both dashboards | packages/dashboard-shared/src/components/... |
| A reusable hook used by both dashboards | packages/dashboard-shared/src/hooks/... |
| A page-specific subcomponent | pages/<domain>/<page>/components/... (admin) or _components/... (vendor) |
| A delete / destructive-action hook | pages/<domain>/common/hooks/use-delete-<entity>-action.tsx |
| A new translation key | packages/<dashboard>/src/i18n/translations/en.json first, then other locales |
| Helpers used by multiple pages in the same dashboard | packages/<dashboard>/src/lib/... |
If the same primitive would land in both packages/admin and packages/vendor, prefer landing it once in @mercurjs/dashboard-shared and importing it from the consuming dashboards.