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.
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.
Always import from @vendure/dashboard first. If it is exported from this package, that is where you get it.
Do not import the same thing directly from a third-party package.
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.
All design-system components (buttons, inputs, dialogs, cards, selectors, etc.) are available directly:
These are the same components used internally by the Dashboard itself, styled with the Vendure design tokens.
Vendure-specific components for displaying and editing data:
Everything for building list views with sortable, filterable tables:
The core APIs for defining extensions, registering custom components, and integrating with the Dashboard framework:
All custom hooks for accessing Dashboard state and services:
The api helper and gql.tada type utilities are available from @vendure/dashboard:
The graphql tagged template function is not something you should import from @vendure/dashboard.
See the @/gql exception below for why.
Re-exported from @tanstack/react-query:
Re-exported from @tanstack/react-router:
The AnyRoute type is commonly needed when typing custom route definitions.
Re-exported from @tanstack/react-table:
The TanStack Table Table type is re-exported as TableInstance to avoid a naming conflict
with the Dashboard's own Table UI component. If you are following TanStack Table documentation,
replace Table with TableInstance in your imports.
Re-exported from react-hook-form:
Re-exported from zod. Used for form validation with zodResolver:
The dashboard accepts both Zod v3 and v4 (^3.25.0 || ^4.0.0). If your extension already imports
z from zod directly, it will continue to work — zodResolver handles both versions at runtime.
However, importing from @vendure/dashboard is recommended to stay insulated from future changes.
Re-exported from sonner:
Re-exported from motion/react:
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.
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 itself is a peer dependency. Import hooks and utilities directly:
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.
The Lingui i18n macros (Trans, useLingui from the macro entry point) must be imported
from their macro module because they are compile-time transforms:
The non-macro useLingui hook is re-exported from @vendure/dashboard, but the macro version
from @lingui/react/macro is what you should use in practice since it provides the t tagged template function.
The graphql tagged template function must be imported from the @/gql path alias — not from
@vendure/dashboard:
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.
| What you need | Import from |
|---|---|
| UI components (Button, Dialog, Card, ...) | @vendure/dashboard |
| Data components (TextInput, MoneyInput, ...) | @vendure/dashboard |
| Hooks (useAuth, useChannel, useLocalFormat, ...) | @vendure/dashboard |
| Extension API (defineDashboardExtension, ...) | @vendure/dashboard |
| GraphQL utilities (api, ResultOf, FragmentOf, ...) | @vendure/dashboard |
| TanStack Query (useQuery, useMutation, ...) | @vendure/dashboard |
| TanStack Router (Link, useNavigate, AnyRoute, ...) | @vendure/dashboard |
| TanStack Table types (ColumnDef, TableInstance, ...) | @vendure/dashboard |
| React Hook Form (useForm, Controller, ...) | @vendure/dashboard |
| Zod (z, zodResolver, ZodType, ...) | @vendure/dashboard |
| Toast (toast) | @vendure/dashboard |
| Animations (motion, AnimatePresence, ...) | @vendure/dashboard |
| Utility functions (cn, ...) | @vendure/dashboard |
| Constants | @vendure/dashboard |
| React hooks (useState, useEffect, ...) | react |
| Icons (ShoppingCartIcon, ...) | lucide-react |
| i18n macros (Trans, useLingui) | @lingui/react/macro |
graphql tagged template function | @/gql |
Following these conventions keeps your extensions stable across Dashboard upgrades and ensures you always get the correctly configured versions of these utilities.
Architecture reviews, custom plugin work, migrations, ongoing support. Get a hand from the team that builds Vendure.
Talk to the team