@vendure/dashboard

Vendure Dashboard

This is a React-based admin dashboard for Vendure. It is a standalone application that can be extended to suit the needs of any Vendure project.

The package consists of three main components:

• @vendure/dashboard: Dashboard source code
• @vendure/dashboard/vite: A Vite plugin that is used to compile the dashboard in your project
• @vendure/dashboard/plugin: A Vendure plugin that provides backend functionality used by the dashboard app.

DashboardPlugin

Basic usage - serving the Dashboard UI

import { DashboardPlugin } from '@vendure/dashboard-plugin';

const config: VendureConfig = {
  // Add an instance of the plugin to the plugins array
  plugins: [
    DashboardPlugin.init({ route: 'dashboard' }),
  ],
};

The Dashboard UI will be served at the /dashboard/ path.

Using only the metrics API

If you are building a stand-alone version of the Dashboard UI app and don't need this plugin to serve the Dashboard UI, you can still use the metricSummary query by adding the DashboardPlugin to the plugins array without calling the init() method:

import { DashboardPlugin } from '@vendure/dashboard-plugin';

const config: VendureConfig = {
  plugins: [
    DashboardPlugin, // <-- no call to .init()
  ],
  // ...
};

Custom Dashboard UI build

You can also provide a custom build of the Dashboard UI:

import { DashboardPlugin } from '@vendure/dashboard-plugin';

const config: VendureConfig = {
  plugins: [
    DashboardPlugin.init({ 
      route: 'dashboard',
      app: path.join(__dirname, 'custom-dashboard-build'),
    }),
  ],
};

API

DashboardPluginOptions

• route: string - The route at which the Dashboard UI will be served (default: 'dashboard')
• app?: string - Optional path to a custom build of the Dashboard UI

Development

Run npx vite to start Vite in dev mode.

Note on internal @/vdb imports

You will notice that the dashboard uses internal Vendure Dashboard imports prefixed with @/vdb. This is adapted from the convention of Shadcn which uses a @/* path alias for internal imports.

Why not just use relative imports?

The problem with using relative imports is that they are handled differently by Vite when compiling the dashboard. This manifests as things like React Context not working correctly. The underlying reason is that Vite will selectively pre-compile source code and mixing the imports between alias and relative can result in 2 "versions" of the same code being loaded, which causes issues with React Context and other things that rely on a single instance of a module.

For this reason, try to use the @/vdb alias for all internal Vendure Dashboard imports to the "src/lib" directory.

This is especially import for hooks (since many of them use React Context) and there is even a pre-commit hook that will run a script to ensure that you are not using relative imports for internal Vendure Dashboard code.

Type Safety for Consumers

Because we ship source code in the npm package, consumers need to tell TypeScript how to resolve these internal imports by adding the path alias to their tsconfig.json file.

{
    "compilerOptions": {
        "paths": {
            "@/vdb/*": [
                "./node_modules/@vendure/dashboard/src/lib/*"
            ]
        }
    }
}

Note: even without that path alias, the vite compilation will still work, but TypeScript types will not resolve correctly when developing dashboard extensions.

Testing

Run npm run test to run tests once, or npx vitest to run tests in watch mode

Changelog

<small>3.4.2 (2025-09-11)</small>

Fixes

• core Correctly implement SettingsStore validation & argument order (#3808) (d8cdd62), closes #3808
• core Emit CollectionEvent after moving a collection (#3801) (d80e28f), closes #3801
• core Fix logic for calculating interval (394fb05)
• core Handle foreign key violations during order merge (#3795) (c00a044), closes #3795
• core Log warning when attempting to persist invalid custom fields (#3793) (eefbd9c), closes #3793
• core Handle stale locks on scheduled tasks (#3708) (4492850), closes #3708
• create Fix resolving path in repos using hoisted node_modules (#3802) (fd971a5), closes #3802
• dashboard Add initial value to reduce call (9261f03)
• dashboard Allow column selection on recent orders (182c0b7)
• dashboard Derive breadcrumbs from path/basepath to match sidebar (#3784) (562cc54), closes #3784
• dashboard Ensure language is valid when switching channel (97d9a9d), closes #3780
• dashboard Ensure language is valid when switching channel (7473956)
• dashboard Fix api 'auto' options (#3807) (b597dfc), closes #3807
• dashboard Fix change detection in RichTextInput (1c18b41)
• dashboard Fix checkboxes on variant creation (4b69839)
• dashboard Fix data table date filter (225b774)
• dashboard Fix filtering in latest orders widget (b8ac456)
• dashboard Fix multi select on asset gallery (5826c7f)
• dashboard Fix navigation to Asset detail from gallery dialog (846ab24)
• dashboard Fix scroll behaviour on asset picker dialog (363043d)
• dashboard Improve facet list table (b76d1dc)
• dashboard Improve layout & rendering of order summary widget (cf72c72)
• dashboard Improve styling of metrics widget, add refresh (e8f8d99)
• dashboard Make long table column dropdowns scrollable (f878e24)
• dashboard Show “Create” for new entities, “Update” for edits (#3805) (fdece02), closes #3805
• dashboard Update channel switcher when Channel added/updated (1cd7652)

Note: In this release, the SettingsStoreService methods have been revised to put the ctx argument in the first position, as is standard across Vendure APIs. Existing code with the ctx last will still work, but you are advised to update it.

- SettingsStoreService.get<T>(key, ctx)       
- SettingsStoreService.getMany(keys, ctx)     
- SettingsStoreService.set<T>(key, value, ctx)
- SettingsStoreService.setMany(values, ctx)

+ SettingsStoreService.get<T>(ctx, key)       
+ SettingsStoreService.getMany(ctx, keys)     
+ SettingsStoreService.set<T>(ctx, key, value)
+ SettingsStoreService.setMany(ctx, values)   

Features

• dashboard Add manage variants screen (cdfd4ca)