Deployment

The Vendure Dashboard offers flexible deployment options. You can either serve it directly through your Vendure Server using the DashboardPlugin, or host it independently as a static site.

Deployment Options

Option 1: Serve with DashboardPlugin

The DashboardPlugin integrates seamlessly with your Vendure Server by:

Serving the React dashboard as static files
Handling routing for the dashboard UI
Providing a unified deployment experience

Option 2: Standalone Hosting

The Vendure Dashboard can be hosted independently as a static site, since the build produces standard web assets (index.html, CSS, and JS files). This approach offers maximum flexibility for deployment on any static hosting service.

Serving with DashboardPlugin

To configure the DashboardPlugin, follow these steps:

1. Configure Vite Base Path

Update your vite.config.mts to set the base path where the dashboard will be served:

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', // [!code highlight]    build: {        outDir: join(__dirname, 'dist/dashboard'), // [!code highlight]    },    plugins: [        vendureDashboardPlugin({            vendureConfigPath: pathToFileURL('./src/vendure-config.ts'),            // When served by DashboardPlugin in production, the dashboard can            // derive the API URL from the same origin that served the app.            api: process.env.NODE_ENV === 'production'                ? { host: 'auto', port: 'auto' }                : { host: 'http://localhost', port: 3000 },            gqlOutputPath: './src/gql',        }),    ],    resolve: {        alias: {            '@/gql': resolve(__dirname, './src/gql/graphql.ts'),        },    },});

2. Add DashboardPlugin to Vendure Config

Angular Admin UI compatibility

If you want to use the Angular Admin UI and the Dashboard together, both plugins can now be used simultaneously without any special configuration.

Add the DashboardPlugin to your vendure-config.ts:

src/vendure-config.ts

import { VendureConfig } from '@vendure/core';import { DashboardPlugin } from '@vendure/dashboard/plugin';import path from 'path';const IS_DEV = process.env.APP_ENV === 'dev';export const config: VendureConfig = {    // ... other config    plugins: [        // ... other plugins        DashboardPlugin.init({            // Important: This must match the base path from vite.config.mts (without slashes) // [!code highlight]            route: 'dashboard', // [!code highlight]            // Path to the Vite build output directory            appDir: IS_DEV                ? path.join(__dirname, '../dist/dashboard')                : path.join(__dirname, 'dashboard'), // [!code highlight]        }),    ],};

Building for Production

Before deploying your Vendure application, build the dashboard:

npx vite build

This command creates optimized production files in the dist/dashboard directory that the DashboardPlugin will serve.

Accessing the Dashboard

Once configured and built, your dashboard will be accessible at:

http://your-server-url/dashboard/

Configuration Options

DashboardPlugin Options

Option	Type	Description
`route`	`string`	The URL path where the dashboard will be served (must match Vite's base path)
`appDir`	`string`	Path to the directory containing the built dashboard files

Best Practices

Consistent Paths: Always ensure the route in DashboardPlugin matches the base in your Vite config
Build Before Deploy: Add the Vite build step to your deployment pipeline
Production Builds: Use npx vite build for optimized production builds

Example Deployment Script

package.json

{    "scripts": {        "build": "npm run build:server && npm run build:dashboard",        "build:server": "tsc",        "build:dashboard": "vite build",        "start:prod": "node ./dist/index.js"    }}

Standalone Hosting

The dashboard can be hosted independently from your Vendure Server on any static hosting service (Netlify, Vercel, AWS S3, etc.).

Configuration

When hosting standalone, you must configure the dashboard to connect to your Admin API endpoint:

vite.config.mts

import { vendureDashboardPlugin } from '@vendure/dashboard/vite';import path from 'path';import { pathToFileURL } from 'url';import { defineConfig } from 'vite';export default defineConfig({    build: {        outDir: path.join(__dirname, 'dist/dashboard'),    },    plugins: [        vendureDashboardPlugin({            vendureConfigPath: pathToFileURL('./src/vendure-config.ts'),            api: { // [!code highlight]                host: process.env.VENDURE_API_HOST || 'https://api.mystore.com', // [!code highlight]                port: parseInt(process.env.VENDURE_API_PORT || '443'), // [!code highlight]            }, // [!code highlight]            gqlOutputPath: './src/gql',        }),    ],});

Build-Time Variables

Environment variables are resolved at build time and embedded as static strings in the final bundles. Ensure these variables are available during the build process, not just at runtime.

Build and Deploy

Build the dashboard:
npx vite build
Deploy the contents of the dist/dashboard directory to your hosting service

CORS Configuration

When hosting the dashboard separately, configure CORS on your Vendure Server:

src/vendure-config.ts

import { VendureConfig } from '@vendure/core';export const config: VendureConfig = {    apiOptions: {        cors: {            origin: ['https://dashboard.mystore.com'],            credentials: true,        },    },    // ... other config};

Troubleshooting

Dashboard Not Loading (DashboardPlugin)

Verify the route matches the base path in Vite config
Check that the build output exists in the specified appDir
Ensure the DashboardPlugin is properly initialized in your plugins array

404 Errors on Dashboard Routes

Confirm the base path includes trailing slashes where needed
Verify the server is running and the plugin is loaded

Connection Issues (Standalone)

Verify the API host and port are correct
Check CORS configuration on your Vendure Server
Ensure environment variables were available during build

Was this chapter helpful?

Report Issue

Edited May 26, 2026·Edit this page