Previewvendurehq/vendure/feat/4563-refund-destinations

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({ // [!code highlight]            // The route should correspond to the `base` setting // [!code highlight]            // in the vite.config.mts file // [!code highlight]            route: 'dashboard', // [!code highlight]            // This appDir should correspond to the `build.outDir` // [!code highlight]            // setting in the vite.config.mts file // [!code highlight]            appDir: './dist/dashboard', // [!code highlight]        }), // [!code highlight]      ],};

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. Both plugins can now be used simultaneously without any special configuration.