Public API & Imports

When building dashboard extensions, everything you need should be imported from @vendure/dashboard. This is the single most important convention to follow, and this page explains exactly what that means, why it matters, and the few exceptions to the rule.

Why a Single Import Source?

The Vendure Dashboard is built on top of several third-party libraries — Base UI, TanStack Router, TanStack Query, React Hook Form, and others. Over time, these libraries may be replaced, upgraded, or wrapped with custom behavior.

To protect your extensions from breaking when that happens, the @vendure/dashboard package re-exports everything you need from these libraries. As long as you import from @vendure/dashboard, your code is insulated from changes to the underlying implementation.

Here is a real-world example: the Dashboard originally used Radix UI primitives for its component library. In a later release, the underlying primitives were migrated to Base UI. Extensions that imported components from @vendure/dashboard continued to work without any changes. Extensions that had imported directly from @radix-ui/* packages broke.

What is Available from @vendure/dashboard?

The public API covers everything you should need to build dashboard extensions. The sections below highlight the most commonly used exports — for the full set, use your IDE's autocomplete on @vendure/dashboard imports.

UI Components

All design-system components (buttons, inputs, dialogs, cards, selectors, etc.) are available directly:

import { Button, Card, Input, Dialog, Select, Badge, Tabs } from '@vendure/dashboard';

These are the same components used internally by the Dashboard itself, styled with the Vendure design tokens.

Data Display & Input Components

Vendure-specific components for displaying and editing data:

import {    // Display    Money, DateTime, Boolean, Json,    // Input    TextInput, MoneyInput, RichTextInput, DatetimeInput,    BooleanInput, SelectWithOptions, RelationInput,} from '@vendure/dashboard';

Data Tables

Everything for building list views with sortable, filterable tables:

import { DataTable, DataTableColumnHeader, DataTablePagination } from '@vendure/dashboard';

Page Layout & Navigation

import {    Page, PageTitle, PageLayout, PageBlock,    DetailPage, ListPage, Link,} from '@vendure/dashboard';

Framework & Extension API

The core APIs for defining extensions, registering custom components, and integrating with the Dashboard framework:

import {    defineDashboardExtension,    useDetailPage, useExtendedDetailQuery, useExtendedListQuery,    detailPageRouteLoader,} from '@vendure/dashboard';

Hooks

All custom hooks for accessing Dashboard state and services:

import {    useAuth, useChannel, usePermissions, useServerConfig,    useLocalFormat, useTheme, useAlerts, usePage, usePageBlock,} from '@vendure/dashboard';

GraphQL Utilities

The api helper and gql.tada type utilities are available from @vendure/dashboard:

import { api, ResultOf, FragmentOf, VariablesOf, readFragment } from '@vendure/dashboard';

TanStack Query (Data Fetching)

Re-exported from @tanstack/react-query:

import {    useQuery, useMutation, useQueryClient,    useInfiniteQuery, useSuspenseQuery,    queryOptions, keepPreviousData,} from '@vendure/dashboard';import type { UseQueryOptions, UseMutationOptions, QueryClient } from '@vendure/dashboard';

TanStack Router (Routing)

Re-exported from @tanstack/react-router:

import {    Link, Outlet, useRouter, useNavigate,    useRouterState, useBlocker,} from '@vendure/dashboard';import type { AnyRoute, LinkProps, RouteOptions } from '@vendure/dashboard';

The AnyRoute type is commonly needed when typing custom route definitions.

TanStack Table (Table Types)

Re-exported from @tanstack/react-table:

import type {    ColumnDef, Column, Row, CellContext, HeaderContext,    SortingState, ColumnFiltersState, VisibilityState,    TableInstance, AccessorFnColumnDef, ColumnSort,    ExpandedState, RowSelectionState,} from '@vendure/dashboard';

React Hook Form

Re-exported from react-hook-form:

import {    useForm, useFormContext, useFieldArray, useWatch,    Controller, FormProvider,} from '@vendure/dashboard';import type { Control, UseFormReturn, FieldValues, FieldPath } from '@vendure/dashboard';

Toast Notifications

Re-exported from sonner:

import { toast } from '@vendure/dashboard';

Animations

Re-exported from motion/react:

import {    motion, AnimatePresence, LayoutGroup,    useSpring, useTransform, useMotionValue,    useAnimation, useInView,} from '@vendure/dashboard';import type { Variants, Transition, MotionProps } from '@vendure/dashboard';

Utility Functions

import {    cn, camelCaseToTitleCase, formatFileSize, normalizeString,    removeReadonlyAndLocalizedCustomFields,} from '@vendure/dashboard';

The removeReadonlyAndLocalizedCustomFields helper is particularly useful when building custom forms that work with custom fields — it strips read-only and localized fields before mutation submission.

Constants

import {    NEW_ENTITY_PATH, AUTHENTICATED_ROUTE_PREFIX,    DEFAULT_CHANNEL_CODE, SUPER_ADMIN_ROLE_CODE, CUSTOMER_ROLE_CODE,} from '@vendure/dashboard';

Exceptions — What to Import Directly

A small number of packages should be imported from their own modules because they are either not re-exported, or re-exporting them is not practical:

react

React itself is a peer dependency. Import hooks and utilities directly:

import { useState, useEffect, useCallback, useMemo } from 'react';

lucide-react

Icons are imported directly from lucide-react. There are thousands of icons and re-exporting them all would be impractical. The LucideIcon type is available from @vendure/dashboard if you need it for typing.

import { ShoppingCartIcon, UserIcon, SettingsIcon } from 'lucide-react';import type { LucideIcon } from '@vendure/dashboard'; // for typing icon props

@lingui/react/macro

The Lingui i18n macros (Trans, useLingui from the macro entry point) must be imported from their macro module because they are compile-time transforms:

import { Trans, useLingui } from '@lingui/react/macro';

@/gql

The graphql tagged template function must be imported from the @/gql path alias — not from @vendure/dashboard:

import { graphql } from '@/gql';

This is because gql.tada needs to be initialized against your project's GraphQL schema, which includes any custom fields, custom types, or API extensions defined by your plugins. The @/gql path points to the types that the Vendure Vite plugin generates from your specific schema during development.

If you were to import graphql from @vendure/dashboard, it would be initialized against the base Vendure schema only — your queries would compile, but the types would not reflect your custom schema extensions, leading to silent type errors.

All other GraphQL utilities (api, ResultOf, FragmentOf, VariablesOf, readFragment) are correctly imported from @vendure/dashboard.

Quick Reference

Common Mistakes

Importing UI components from the underlying library

// Wrong — imports directly from the underlying component libraryimport { Button } from '@base-ui/react';import { Dialog } from '@radix-ui/react-dialog';// Correctimport { Button, Dialog } from '@vendure/dashboard';

Importing TanStack hooks directly

// Wrong — bypasses the dashboard re-exportimport { useQuery } from '@tanstack/react-query';import { useNavigate } from '@tanstack/react-router';// Correctimport { useQuery, useNavigate } from '@vendure/dashboard';

Importing React Hook Form directly

// Wrongimport { useForm } from 'react-hook-form';// Correctimport { useForm } from '@vendure/dashboard';

Following these conventions keeps your extensions stable across Dashboard upgrades and ensures you always get the correctly configured versions of these utilities.