Getting Started

info

From Vendure v3.5.0, the @vendure/dashboard package and configuration comes as standard with new projects that are started with the npx @vendure/create command.

This guide serves mainly for those adding the Dashboard to existing project set up prior to v3.5.0.

Installation & Setup

note

This guide assumes an existing project based on the @vendure/create folder structure. If you have a different setup (e.g. an Nx monorepo), you may need to adapt the instructions accordingly.

First install the @vendure/dashboard package:

npm install @vendure/dashboard

Then create a vite.config.mts file in the root of your project (on the same level as your package.json) with the following content:

vite.config.mts

import { vendureDashboardPlugin } from '@vendure/dashboard/vite';
import { join, resolve } from 'path';
import { pathToFileURL } from 'url';
import { defineConfig } from 'vite';

export default defineConfig({
    base: '/dashboard',
    build: {
        outDir: join(__dirname, 'dist/dashboard'),
    },
    plugins: [
        vendureDashboardPlugin({
            // The vendureDashboardPlugin will scan your configuration in order
            // to find any plugins which have dashboard extensions, as well as
            // to introspect the GraphQL schema based on any API extensions
            // and custom fields that are configured.
            vendureConfigPath: pathToFileURL('./src/vendure-config.ts'),
            // Points to the location of your Vendure server.
            api: { host: 'http://localhost', port: 3000 },
            // When you start the Vite server, your Admin API schema will
            // be introspected and the types will be generated in this location.
            // These types can be used in your dashboard extensions to provide
            // type safety when writing queries and mutations.
            gqlOutputPath: './src/gql',
        }),
    ],
    resolve: {
        alias: {
            // This allows all plugins to reference a shared set of
            // GraphQL types.
            '@/gql': resolve(__dirname, './src/gql/graphql.ts'),
        },
    },
});

You should also add the following to your existing tsconfig.json file to exclude the dashboard extensions and Vite config from your build, and reference a new tsconfig.dashboard.json that will have compiler settings for the Dashboard code.

tsconfig.json

{
    // ... existing options
    "exclude": [
        "node_modules",
        "migration.ts",
        "src/plugins/**/ui/*",
        "admin-ui",
        "src/plugins/**/dashboard/*",
        "src/gql/*",
        "vite.*.*ts"
    ],
    "references": [
        {
            "path": "./tsconfig.dashboard.json"
        }
    ]
}

Now create a new tsconfig.dashboard.json to allow your IDE to correctly resolve imports of GraphQL types & interpret JSX in your dashboard extensions:

tsconfig.dashboard.json

{
    "compilerOptions": {
        "composite": true,
        "module": "ESNext",
        "moduleResolution": "bundler",
        "jsx": "react-jsx",
        "paths": {
            // Import alias for the GraphQL types
            // Please adjust to the location that you have set in your `vite.config.mts`
            "@/gql": [
                "./src/gql/graphql.ts"
            ],
            // This line allows TypeScript to properly resolve internal
            // Vendure Dashboard imports, which is necessary for
            // type safety in your dashboard extensions.
            // This path assumes a root-level tsconfig.json file.
            // You may need to adjust it if your project structure is different.
            "@/vdb/*": [
                "./node_modules/@vendure/dashboard/src/lib/*"
            ]
        }
    },
    "include": [
        "src/plugins/**/dashboard/*",
        "src/gql/**/*.ts"
    ]
}

Monorepo Setup

If your project uses a monorepo structure, such as with Nx or Turborepo, then you'll need to make some adjustments to the paths given above:

If each Vendure plugin is its own "package", outside the main Vendure server app, then it would need its own tsconfig for each plugin package. You might run into errors like:

Error loading Vendure config: Cannot find module

In this case, you'll need to configure a PathAdapter.

You should also put your vite.config.mts file into the Vendure app directory rather than the root.

The DashboardPlugin

In your vendure-config.ts file, you should also import and configure the DashboardPlugin.

src/vendure-config.ts

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

const config: VendureConfig = {
    plugins: [
        // ... existing plugins
        DashboardPlugin.init({
            // The route should correspond to the `base` setting
            // in the vite.config.mts file
            route: 'dashboard',
            // This appDir should correspond to the `build.outDir`
            // setting in the vite.config.mts file
            appDir: './dist/dashboard',
        }),
    ],
};

The DashboardPlugin adds the following features that enhance the use of the Dashboard:

• It exposes a set of queries which power the Insights page metrics.
• It registers SettingsStore entries that are used to store your personal display settings on the server side, which allow administrators to enjoy a consistent experience across browsers and devices.
• It serves the dashboard with a static server at the /dashboard route (by default), meaning you do not need to set up a separate web server.

Running the Dashboard

Once the above is set up, you can run npm run dev to start your Vendure server, and then visit

http://localhost:3000/dashboard

which will display a developer placeholder until you start the Vite dev server using

npx vite

To stop the running dashboard, type q and hit enter.

Compatibility with the legacy Admin UI

If you still need to run the legacy Angular-based Admin UI in parallel with the Dashboard, this is totally possible.

You just need to make sure to set the compatibilityMode setting in the AdminUiPlugin's init options.

AdminUiPlugin.init({
  // ...
  compatibilityMode: true,  
})