***

title: 'Deployment'
metaTitle: "Deploying the Vendure Dashboard"
metaDescription: "Deploy the Vendure Dashboard via the DashboardPlugin or as a standalone static site. Covers Vite build configuration, CORS setup, and production best practices."
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

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:

```typescript title="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

:::info\[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`:

```typescript title="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:

```bash
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

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

## Example Deployment Script

```json title="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:

```typescript title="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',
        }),
    ],
});
```

:::warning\[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

1. **Build the dashboard:**
   ```bash
   npx vite build
   ```

2. **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:

```typescript title="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