feat(dashboard): Default dashboard page & dx improvements (#3859)

docs/docs/reference/core-plugins/dashboard-plugin/dashboard-plugin-options.md

@@ -0,0 +1,40 @@
+---
+title: "DashboardPluginOptions"
+isDefaultIndex: false
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+import MemberInfo from '@site/src/components/MemberInfo';
+import GenerationInfo from '@site/src/components/GenerationInfo';
+import MemberDescription from '@site/src/components/MemberDescription';
+
+
+## DashboardPluginOptions
+
+<GenerationInfo sourceFile="packages/dashboard/plugin/dashboard.plugin.ts" sourceLine="27" packageName="@vendure/dashboard" />
+
+Configuration options for the <a href='/reference/core-plugins/dashboard-plugin/#dashboardplugin'>DashboardPlugin</a>.
+
+```ts title="Signature"
+interface DashboardPluginOptions {
+    route: string;
+    appDir: string;
+}
+```
+
+<div className="members-wrapper">
+
+### route
+
+<MemberInfo kind="property" type={`string`} default={`'dashboard'`}   />
+
+The route to the Dashboard UI.
+### appDir
+
+<MemberInfo kind="property" type={`string`}   />
+
+The path to the dashboard UI app dist directory. By default, the built-in dashboard UI
+will be served. This can be overridden with a custom build of the dashboard.
+
+
+</div>

docs/docs/reference/core-plugins/dashboard-plugin/index.md

@@ -0,0 +1,102 @@
+---
+title: "DashboardPlugin"
+isDefaultIndex: false
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+import MemberInfo from '@site/src/components/MemberInfo';
+import GenerationInfo from '@site/src/components/GenerationInfo';
+import MemberDescription from '@site/src/components/MemberDescription';
+
+
+## DashboardPlugin
+
+<GenerationInfo sourceFile="packages/dashboard/plugin/dashboard.plugin.ts" sourceLine="101" packageName="@vendure/dashboard" />
+
+This plugin serves the static files of the Vendure Dashboard and provides the
+GraphQL extensions needed for the order metrics on the dashboard index page.
+
+## Installation
+
+`npm install @vendure/dashboard`
+
+## Usage
+
+First you need to set up compilation of the Dashboard, using the Vite configuration
+described in the [Dashboard Getting Started Guide](/guides/extending-the-dashboard/getting-started/)
+
+Once set up, you run `npx vite build` to build the production version of the dashboard app.
+
+The built app files will be output to the location specified by `build.outDir` in your Vite
+config file. This should then be passed to the `appDir` init option, as in the example below:
+
+*Example*
+
+```ts
+import { DashboardPlugin } from '@vendure/dashboard/plugin';
+
+const config: VendureConfig = {
+  // Add an instance of the plugin to the plugins array
+  plugins: [
+    DashboardPlugin.init({
+      route: 'dashboard',
+      appDir: './dist/dashboard',
+    }),
+  ],
+};
+```
+
+## Metrics
+
+This plugin defines a `metricSummary` query which is used by the Dashboard UI to
+display the order metrics on the dashboard.
+
+If you are building a stand-alone version of the Dashboard UI app, and therefore
+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,
+but without calling the `init()` method:
+
+*Example*
+
+```ts
+import { DashboardPlugin } from '@vendure/dashboard-plugin';
+
+const config: VendureConfig = {
+  plugins: [
+    DashboardPlugin, // <-- no call to .init()
+  ],
+  // ...
+};
+```
+
+```ts title="Signature"
+class DashboardPlugin implements NestModule {
+    constructor(processContext: ProcessContext)
+    init(options: DashboardPluginOptions) => Type<DashboardPlugin>;
+    configure(consumer: MiddlewareConsumer) => ;
+}
+```
+* Implements: <code>NestModule</code>
+
+
+
+<div className="members-wrapper">
+
+### constructor
+
+<MemberInfo kind="method" type={`(processContext: <a href='/reference/typescript-api/common/process-context#processcontext'>ProcessContext</a>) => DashboardPlugin`}   />
+
+
+### init
+
+<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/dashboard-plugin/dashboard-plugin-options#dashboardpluginoptions'>DashboardPluginOptions</a>) => Type&#60;<a href='/reference/core-plugins/dashboard-plugin/#dashboardplugin'>DashboardPlugin</a>&#62;`}   />
+
+Set the plugin options
+### configure
+
+<MemberInfo kind="method" type={`(consumer: MiddlewareConsumer) => `}   />
+
+
+
+
+</div>

docs/docs/reference/dashboard/extensions-api/navigation.md

@@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## DashboardNavSectionDefinition
 
-<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/navigation.ts" sourceLine="57" packageName="@vendure/dashboard" since="3.4.0" />
+<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/navigation.ts" sourceLine="73" packageName="@vendure/dashboard" since="3.4.0" />
 
 Defines a custom navigation section in the dashboard sidebar.
 

docs/docs/reference/dashboard/extensions-api/routes.md

@@ -21,6 +21,8 @@ interface DashboardRouteDefinition {
     path: string;
     navMenuItem?: Partial<NavMenuItem> & { sectionId: string };
     loader?: RouteOptions['loader'];
+    validateSearch?: RouteOptions['validateSearch'];
+    authenticated?: boolean;
 }
 ```
 
@@ -53,6 +55,19 @@ have been defined using the `navSections` extension property.
 Optional loader function to fetch data before the route renders.
 The value is a Tanstack Router
 [loader function](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#route-loaders)
+### validateSearch
+
+<MemberInfo kind="property" type={`RouteOptions['validateSearch']`}   />
+
+Optional search parameter validation function.
+The value is a Tanstack Router
+[validateSearch function](https://tanstack.com/router/latest/docs/framework/react/guide/search-params#search-param-validation)
+### authenticated
+
+<MemberInfo kind="property" type={`boolean`} default={`true`}   />
+
+Define if the route should be under the authentication context, i.e have the authenticated route
+as a parent.
 
 
 </div>

docs/docs/reference/dashboard/form-components/date-time-input.md

@@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## DateTimeInput
 
-<GenerationInfo sourceFile="packages/dashboard/src/lib/components/data-input/datetime-input.tsx" sourceLine="22" packageName="@vendure/dashboard" />
+<GenerationInfo sourceFile="packages/dashboard/src/lib/components/data-input/datetime-input.tsx" sourceLine="41" packageName="@vendure/dashboard" />
 
 A component for selecting a date and time.
 

docs/docs/reference/dashboard/form-components/translatable-form-field-wrapper.md

@@ -68,7 +68,7 @@ type TranslatableFormFieldProps<TFieldValues extends TranslatableEntity | Transl
     name: TFieldValues extends TranslatableEntity
         ? keyof Omit<NonNullable<TFieldValues['translations']>[number], 'languageCode'>
         : TFieldValues extends TranslatableEntity[]
-          ? keyof Omit<NonNullable<TFieldValues[number]['translations']>[number], 'languageCode'>
-          : never;
+            ? keyof Omit<NonNullable<TFieldValues[number]['translations']>[number], 'languageCode'>
+            : never;
 }
 ```

docs/docs/reference/dashboard/hooks/use-display-locale.md

@@ -0,0 +1,36 @@
+---
+title: "UseDisplayLocale"
+isDefaultIndex: false
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+import MemberInfo from '@site/src/components/MemberInfo';
+import GenerationInfo from '@site/src/components/GenerationInfo';
+import MemberDescription from '@site/src/components/MemberDescription';
+
+
+## useDisplayLocale
+
+<GenerationInfo sourceFile="packages/dashboard/src/lib/hooks/use-display-locale.ts" sourceLine="27" packageName="@vendure/dashboard" />
+
+Returns information about the current display language & region.
+
+*Example*
+
+```tsx
+const {
+  bcp47Tag,
+  humanReadableLanguageAndLocale,
+  humanReadableLanguage,
+  isRTL,
+} = useDisplayLocale();
+
+console.log(bcp47Tag) // "en-GB"
+console.log(humanReadableLanguage) // "English"
+console.log(humanReadableLanguageAndLocale) // "British English"
+console.log(isRTL) // false
+```
+
+```ts title="Signature"
+function useDisplayLocale(): void
+```

docs/docs/reference/dashboard/hooks/use-local-format.md

@@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## useLocalFormat
 
-<GenerationInfo sourceFile="packages/dashboard/src/lib/hooks/use-local-format.ts" sourceLine="26" packageName="@vendure/dashboard" />
+<GenerationInfo sourceFile="packages/dashboard/src/lib/hooks/use-local-format.ts" sourceLine="27" packageName="@vendure/dashboard" />
 
 This hook is used to format numbers and currencies using the configured language and
 locale of the dashboard app.

docs/docs/reference/dashboard/hooks/use-paginated-list.md

@@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## usePaginatedList
 
-<GenerationInfo sourceFile="packages/dashboard/src/lib/components/shared/paginated-list-data-table.tsx" sourceLine="175" packageName="@vendure/dashboard" since="3.4.0" />
+<GenerationInfo sourceFile="packages/dashboard/src/lib/components/shared/paginated-list-data-table.tsx" sourceLine="179" packageName="@vendure/dashboard" since="3.4.0" />
 
 Returns the context for the paginated list data table. Must be used within a PaginatedListDataTable.
 

docs/docs/reference/dashboard/hooks/use-ui-language-loader.md

@@ -0,0 +1,22 @@
+---
+title: "UseUiLanguageLoader"
+isDefaultIndex: false
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+import MemberInfo from '@site/src/components/MemberInfo';
+import GenerationInfo from '@site/src/components/GenerationInfo';
+import MemberDescription from '@site/src/components/MemberDescription';
+
+
+## useUiLanguageLoader
+
+<GenerationInfo sourceFile="packages/dashboard/src/lib/hooks/use-ui-language-loader.ts" sourceLine="15" packageName="@vendure/dashboard" />
+
+Loads the UI translations for the given locale and activates it
+with the Lingui I18nProvider. Generally this is used internally
+when the display language is set via the user > language dialog.
+
+```ts title="Signature"
+function useUiLanguageLoader(): void
+```

docs/docs/reference/dashboard/list-views/paginated-list-data-table.md

@@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## PaginatedListDataTable
 
-<GenerationInfo sourceFile="packages/dashboard/src/lib/components/shared/paginated-list-data-table.tsx" sourceLine="347" packageName="@vendure/dashboard" since="3.4.0" />
+<GenerationInfo sourceFile="packages/dashboard/src/lib/components/shared/paginated-list-data-table.tsx" sourceLine="351" packageName="@vendure/dashboard" since="3.4.0" />
 
 A wrapper around the <a href='/reference/dashboard/list-views/data-table#datatable'>DataTable</a> component, which automatically configures functionality common to
 list queries that implement the `PaginatedList` interface, which is the common way of representing lists
@@ -130,7 +130,7 @@ Parameters
 
 ## PaginatedListDataTableProps
 
-<GenerationInfo sourceFile="packages/dashboard/src/lib/components/shared/paginated-list-data-table.tsx" sourceLine="198" packageName="@vendure/dashboard" since="3.4.0" />
+<GenerationInfo sourceFile="packages/dashboard/src/lib/components/shared/paginated-list-data-table.tsx" sourceLine="202" packageName="@vendure/dashboard" since="3.4.0" />
 
 Props to configure the <a href='/reference/dashboard/list-views/paginated-list-data-table#paginatedlistdatatable'>PaginatedListDataTable</a> component.
 

docs/sidebars.js

@@ -286,6 +286,12 @@ const sidebars = {
                     link: { type: 'doc', id: 'reference/core-plugins/asset-server-plugin/index' },
                     items: [{ type: 'autogenerated', dirName: 'reference/core-plugins/asset-server-plugin' }],
                 },
+                {
+                    type: 'category',
+                    label: 'DashboardPlugin',
+                    link: { type: 'doc', id: 'reference/core-plugins/dashboard-plugin/index' },
+                    items: [{ type: 'autogenerated', dirName: 'reference/core-plugins/dashboard-plugin' }],
+                },
                 {
                     type: 'category',
                     label: 'ElasticsearchPlugin',

packages/dashboard/plugin/dashboard.plugin.ts

@@ -1,6 +1,7 @@
 import { MiddlewareConsumer, NestModule } from '@nestjs/common';
 import { Type } from '@vendure/common/lib/shared-types';
 import {
+    createProxyHandler,
     Logger,
     PluginCommonModule,
     ProcessContext,
@@ -10,12 +11,13 @@ import {
 } from '@vendure/core';
 import express from 'express';
 import { rateLimit } from 'express-rate-limit';
-import fs from 'fs-extra';
-import path from 'path';
+import * as fs from 'node:fs';
+import * as http from 'node:http';
+import * as path from 'node:path';
 
 import { adminApiExtensions } from './api/api-extensions.js';
 import { MetricsResolver } from './api/metrics.resolver.js';
-import { DEFAULT_APP_PATH, loggerCtx, manageDashboardGlobalViews } from './constants.js';
+import { loggerCtx, manageDashboardGlobalViews } from './constants.js';
 import { MetricsService } from './service/metrics.service.js';
 
 /**
@@ -34,10 +36,18 @@ export interface DashboardPluginOptions {
     route: string;
     /**
      * @description
-     * The path to the dashboard UI app dist directory. By default, the built-in dashboard UI
-     * will be served. This can be overridden with a custom build of the dashboard.
+     * The path to the dashboard UI app dist directory.
      */
     appDir: string;
+    /**
+     * @description
+     * The port on which to check for a running Vite dev server.
+     * If a Vite dev server is detected on this port, requests will be proxied to it
+     * instead of serving static files from appDir.
+     *
+     * @default 5173
+     */
+    viteDevServerPort?: number;
 }
 
 /**
@@ -54,10 +64,16 @@ export interface DashboardPluginOptions {
  * First you need to set up compilation of the Dashboard, using the Vite configuration
  * described in the [Dashboard Getting Started Guide](/guides/extending-the-dashboard/getting-started/)
  *
- * Once set up, you run `npx vite build` to build the production version of the dashboard app.
+ * ## Development vs Production
  *
- * The built app files will be output to the location specified by `build.outDir` in your Vite
- * config file. This should then be passed to the `appDir` init option, as in the example below:
+ * When developing, you can run `npx vite` (or `npm run dev`) to start the Vite development server.
+ * The plugin will automatically detect if Vite is running on the default port (5173) and proxy
+ * requests to it instead of serving static files. This enables hot module replacement and faster
+ * development iterations.
+ *
+ * For production, run `npx vite build` to build the dashboard app. The built app files will be
+ * output to the location specified by `build.outDir` in your Vite config file. This should then
+ * be passed to the `appDir` init option, as in the example below:
  *
  * @example
  * ```ts
@@ -69,6 +85,8 @@ export interface DashboardPluginOptions {
  *     DashboardPlugin.init({
  *       route: 'dashboard',
  *       appDir: './dist/dashboard',
+ *       // Optional: customize Vite dev server port (defaults to 5173)
+ *       viteDevServerPort: 3000,
  *     }),
  *   ],
  * };
@@ -149,17 +167,17 @@ export class DashboardPlugin implements NestModule {
             return;
         }
         if (!DashboardPlugin.options) {
-            Logger.info(
+            Logger.warn(
                 `DashboardPlugin's init() method was not called. The Dashboard UI will not be served.`,
                 loggerCtx,
             );
             return;
         }
-        const { route, appDir } = DashboardPlugin.options;
-        const dashboardPath = appDir || this.getDashboardPath();
+        const { route, appDir, viteDevServerPort = 5173 } = DashboardPlugin.options;
+
+        Logger.verbose('Creating dashboard middleware', loggerCtx);
 
-        Logger.info('Creating dashboard middleware', loggerCtx);
-        consumer.apply(this.createStaticServer(dashboardPath)).forRoutes(route);
+        consumer.apply(this.createDynamicHandler(route, appDir, viteDevServerPort)).forRoutes(route);
 
         registerPluginStartupMessage('Dashboard UI', route);
     }
@@ -173,10 +191,7 @@ export class DashboardPlugin implements NestModule {
         });
 
         const dashboardServer = express.Router();
-        // This is a workaround for a type mismatch between express v5 (Vendure core)
-        // and express v4 (several transitive dependencies). Can be removed once the
-        // ecosystem has more significantly shifted to v5.
-        dashboardServer.use(limiter as any);
+        dashboardServer.use(limiter);
         dashboardServer.use(express.static(dashboardPath));
         dashboardServer.use((req, res) => {
             res.sendFile('index.html', { root: dashboardPath });
@@ -185,26 +200,174 @@ export class DashboardPlugin implements NestModule {
         return dashboardServer;
     }
 
-    private getDashboardPath(): string {
-        // First, try to find the dashboard dist directory in the @vendure/dashboard package
+    private async checkViteDevServer(port: number): Promise<boolean> {
+        return new Promise(resolve => {
+            const req = http.request(
+                {
+                    hostname: 'localhost',
+                    port,
+                    path: '/',
+                    method: 'HEAD',
+                    timeout: 1000,
+                },
+                (res: http.IncomingMessage) => {
+                    resolve(res.statusCode !== undefined && res.statusCode < 400);
+                },
+            );
+
+            req.on('error', () => {
+                resolve(false);
+            });
+
+            req.on('timeout', () => {
+                req.destroy();
+                resolve(false);
+            });
+
+            req.end();
+        });
+    }
+
+    private checkBuiltFiles(appDir: string): boolean {
         try {
-            const dashboardPackageJson = require.resolve('@vendure/dashboard/package.json');
-            const dashboardPackageRoot = path.dirname(dashboardPackageJson);
-            const dashboardDistPath = path.join(dashboardPackageRoot, 'dist');
+            const indexPath = path.join(appDir, 'index.html');
+            return fs.existsSync(indexPath);
+        } catch {
+            return false;
+        }
+    }
+
+    private createDefaultPage() {
+        const limiter = rateLimit({
+            windowMs: 60 * 1000,
+            limit: process.env.NODE_ENV === 'production' ? 500 : 2000,
+            standardHeaders: true,
+            legacyHeaders: false,
+        });
+
+        const defaultPageServer = express.Router();
+        defaultPageServer.use(limiter);
 
-            if (fs.existsSync(dashboardDistPath)) {
-                Logger.info(`Found dashboard UI at ${dashboardDistPath}`, loggerCtx);
-                return dashboardDistPath;
+        defaultPageServer.use((req, res) => {
+            try {
+                const htmlPath = path.join(__dirname, 'default-page.html');
+                const defaultHtml = fs.readFileSync(htmlPath, 'utf8');
+                res.setHeader('Content-Type', 'text/html');
+                res.send(defaultHtml);
+            } catch (error) {
+                res.status(500).send(
+                    `Unable to load default page: ${error instanceof Error ? error.message : String(error)}`,
+                );
             }
-        } catch (e) {
-            // Dashboard package not found, continue to fallback
-        }
+        });
 
-        // Fallback to default path
-        Logger.warn(
-            `Could not find @vendure/dashboard dist directory. Falling back to default path: ${DEFAULT_APP_PATH}`,
-            loggerCtx,
+        return defaultPageServer;
+    }
+
+    private createDynamicHandler(route: string, appDir: string, viteDevServerPort: number) {
+        const limiter = rateLimit({
+            windowMs: 60 * 1000,
+            limit: process.env.NODE_ENV === 'production' ? 500 : 2000,
+            standardHeaders: true,
+            legacyHeaders: false,
+        });
+
+        // Pre-create handlers to avoid recreating them on each request
+        const proxyHandler = createProxyHandler({
+            label: 'Dashboard Vite Dev Server',
+            route,
+            port: viteDevServerPort,
+            basePath: route,
+        });
+
+        const staticServer = this.createStaticServer(appDir);
+        const defaultPage = this.createDefaultPage();
+
+        // Track current mode to log changes
+        let currentMode: 'vite' | 'built' | 'default' | null = null;
+
+        const dynamicRouter = express.Router();
+        dynamicRouter.use(limiter);
+
+        // Add status endpoint for polling (localhost only for security)
+        dynamicRouter.get(
+            '/__status',
+            (req, res, next) => {
+                const clientIp = req.ip || req.connection.remoteAddress || req.socket.remoteAddress;
+                const isLocalhost =
+                    clientIp === '127.0.0.1' ||
+                    clientIp === '::1' ||
+                    clientIp === '::ffff:127.0.0.1' ||
+                    clientIp === 'localhost';
+
+                if (!isLocalhost) {
+                    return res.status(403).json({ error: 'Access denied' });
+                }
+
+                next();
+            },
+            async (req, res) => {
+                try {
+                    const isViteRunning = await this.checkViteDevServer(viteDevServerPort);
+                    const hasBuiltFiles = this.checkBuiltFiles(appDir);
+                    const mode = isViteRunning ? 'vite' : hasBuiltFiles ? 'built' : 'default';
+                    res.json({
+                        viteRunning: isViteRunning,
+                        hasBuiltFiles,
+                        mode,
+                    });
+                } catch (error) {
+                    res.status(500).json({
+                        error: `Status check failed: ${error instanceof Error ? error.message : String(error)}`,
+                    });
+                }
+            },
         );
-        return DEFAULT_APP_PATH;
+
+        dynamicRouter.use(async (req, res, next) => {
+            try {
+                // Check for Vite dev server first (highest priority)
+                const isViteRunning = await this.checkViteDevServer(viteDevServerPort);
+                const hasBuiltFiles = this.checkBuiltFiles(appDir);
+
+                // Determine new mode
+                const staticMode = hasBuiltFiles ? 'built' : 'default';
+                const newMode: 'vite' | 'built' | 'default' = isViteRunning ? 'vite' : staticMode;
+
+                // Log mode change
+                if (currentMode !== newMode) {
+                    const modeDescriptions = {
+                        vite: 'Vite dev server (with HMR)',
+                        built: 'built static files',
+                        default: 'default getting-started page',
+                    };
+
+                    if (currentMode !== null) {
+                        Logger.info(
+                            `Dashboard mode changed: ${currentMode} → ${newMode} (serving ${modeDescriptions[newMode]})`,
+                            loggerCtx,
+                        );
+                    }
+                    currentMode = newMode;
+                }
+
+                // Route to appropriate handler
+                if (isViteRunning) {
+                    return proxyHandler(req, res, next);
+                }
+
+                if (hasBuiltFiles) {
+                    return staticServer(req, res, next);
+                }
+
+                // Fall back to default page
+                return defaultPage(req, res, next);
+            } catch (error) {
+                Logger.error(`Dashboard dynamic handler error: ${String(error)}`, loggerCtx);
+                res.status(500).send('Dashboard unavailable');
+            }
+        });
+
+        return dynamicRouter;
     }
 }

packages/dashboard/plugin/default-page.html

@@ -0,0 +1,188 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Vendure Dashboard</title>
+    <style>
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            background: #000;
+            color: #fafafa;
+            min-height: 100vh;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+        }
+
+        .container {
+            max-width: 480px;
+            width: 90%;
+            text-align: center;
+        }
+
+        .logo {
+            margin: 40px 80px;
+        }
+
+        h1 {
+            font-size: 32px;
+            font-weight: 600;
+            margin-bottom: 16px;
+            letter-spacing: -0.5px;
+        }
+
+        .subtitle {
+            font-size: 16px;
+            color: #888;
+            margin-bottom: 48px;
+            line-height: 1.5;
+        }
+
+        .commands {
+            display: flex;
+            flex-direction: column;
+            gap: 12px;
+            margin-bottom: 48px;
+        }
+
+        .command {
+            background: #111;
+            border: 1px solid #333;
+            border-radius: 8px;
+            padding: 16px 20px;
+            text-align: left;
+            transition: border-color 0.2s ease;
+        }
+
+        .command:hover {
+            border-color: #555;
+        }
+
+        .command-title {
+            font-family: 'SF Mono', Monaco, 'Cascadia Code', monospace;
+            font-size: 14px;
+            color: #fafafa;
+            font-weight: 500;
+            margin-bottom: 4px;
+        }
+
+        .command-desc {
+            font-size: 13px;
+            color: #888;
+        }
+
+        .footer {
+            font-size: 14px;
+            color: #666;
+        }
+
+        .footer a {
+            color: #fafafa;
+            text-decoration: none;
+            border-bottom: 1px solid transparent;
+            transition: border-color 0.2s ease;
+        }
+
+        .footer a:hover {
+            border-bottom-color: #fafafa;
+        }
+
+        @media (max-width: 640px) {
+            h1 {
+                font-size: 28px;
+            }
+
+            .subtitle {
+                font-size: 15px;
+            }
+        }
+    </style>
+    <link rel="icon" type="image/png" href="data:image/webp;base64,UklGRiwDAABXRUJQVlA4WAoAAAAQAAAAPwAAPwAAQUxQSLUBAAABkMP///lFn2zbtj3bbrdr7tFUZ681XfZ4trlZW7bt+gy/ft/v5/v9j3dDREwA/IuuRaclh35BZ74+jUFhd5GBBLEDO7jdH0MRO7iDO0PxotyvzKFy9pIbj/uVOVTOX/MUYV79E9V/VJqzmFf/RPXftRZUuunPjpD16Emq7lm66c+OkPX4RaYeSWjnJvJu3PZT+HduIO9mdxiB+zck3C1TlO0i4Xd3vtgNvuOX2QYK/cwXx3wbsQTrXH/qLUHVovY317q4hRtewOxxbV6u3ZEE4I4f2pHn5GOxIRAaFL4/keWuHRDb3pGlBawsKCysoEWeK29y9Hn0c95ckakTt/ui2aL7trFTpg5EnLnopuZ2cQYRO0RtciF+rzBTmFV8RyXbJoHHZwI8epyqq5v6+AgJPrrzgdvFWT7E9cHBdVRlmT7vCqTRfdt87GpbPZFArZ/7+kTc8ctsPRBo1fhX1J96SxDsfWupma558YYXiNeK8oBOmk5wj9QCSa/SXAWJbZtG+UabbGUCCGxfZVttDwTZdRLvH6gd3E/UAQ00Lfly1pcSE9BQ55YpxKkWZ9DgiLa2CPjPIQBWUDggUAEAAPAJAJ0BKkAAQAA+jTaVR6UioiEz9N1QoBGJbADOopB+JPKVbU7gH5V3gHmA/gH+S6gHnmdQBz6HsN/uz6S4WB8YK0m3PqfJR8HfqDbB/vlze73BWCg4nAAA/vz4SH/+WDUxM452z3gMx/GuN+7OSD//LCMf/F5Ab5IIDfnWJfU9of/l1cF1H99n//121P/sQ2heGdHI//mL32lEkXNWj6LBhm60ZcgI57R3irC6d/UBmF2HLkHqkpFFGQSGJQUknhOGJeYUlhhNIRy755E+/Al/87y+4t//9cV8xbRIJo9EKQbihU4uLE2PTm9P6yNXTr8O7QFKmSLOh7YHA0+fEidpzooIeFIkMfmzvkh3tWesZNZJjFKs2rHULUUqeMNNkwDLdC4x6UpA9AqbCJYHEj9V6L7eLS2J/teV0a3WWaXoQcRjVkTLy1bsxSowIKAAAA==" />
+</head>
+<body>
+    <div class="container">
+        <svg viewBox="0 0 539 100" fill="none" xmlns="http://www.w3.org/2000/svg">
+            <path d="M198.715 29.7044C198.311 29.1369 197.638 28.7809 196.916 28.7809H189.317C188.393 28.7809 187.547 29.3774 187.239 30.2431L174.3 67.6252L161.16 30.2239C160.862 29.3581 160.034 28.7617 159.082 28.7617H151.261C150.54 28.7617 149.886 29.108 149.462 29.6852C149.058 30.2527 148.962 31.0031 149.183 31.6764L167.817 82.9974C168.115 83.8632 168.942 84.4404 169.866 84.4404H178.139C179.062 84.4404 179.889 83.8728 180.188 82.9974L198.927 31.6764C199.177 31.0031 199.081 30.2623 198.648 29.6852L198.696 29.714L198.715 29.7044Z" fill="#17C1FF"/>
+            <path d="M252.778 58.3518C252.855 57.5342 252.903 56.4086 252.903 54.9465C252.903 49.7807 251.729 45.0286 249.43 40.8055C247.131 36.5825 243.88 33.1771 239.839 30.7145C235.77 28.2518 231.143 26.982 226.15 26.982C220.85 26.982 216.031 28.2711 211.836 30.8107C207.642 33.3503 204.343 36.9288 201.995 41.4212C199.667 45.8655 198.494 50.9639 198.494 56.553C198.494 62.142 199.696 67.2404 202.044 71.7135C204.42 76.2156 207.767 79.7941 211.99 82.3241C216.213 84.8636 221.081 86.1527 226.458 86.1527C232.23 86.1527 237.329 84.9887 241.619 82.6511C245.89 80.3135 249.392 77.0621 252.008 72.9834C252.633 71.9925 252.354 70.6746 251.383 70.0012L245.438 66.0476C244.938 65.7205 244.341 65.5955 243.735 65.7205C243.158 65.8456 242.639 66.2207 242.34 66.7113C240.792 69.299 238.695 71.3384 236.145 72.8006C233.596 74.2435 230.277 74.9842 226.256 74.9842C221.456 74.9842 217.791 73.4162 215.04 70.1648C212.644 67.327 211.163 64.0755 210.595 60.2469H250.613C251.739 60.2469 252.691 59.4004 252.787 58.2845V58.3326L252.778 58.3518ZM211.355 49.8288C212.25 46.7986 213.78 44.2397 215.925 42.0753C218.57 39.4395 221.899 38.1505 226.122 38.1505C230.345 38.1505 233.846 39.2664 236.318 41.5558C238.339 43.4413 239.791 46.231 240.59 49.8095H211.336L211.365 49.8384L211.355 49.8288Z" fill="#17C1FF"/>
+            <path d="M305.417 36.6883C303.396 33.5042 300.645 31.0512 297.25 29.4062C293.931 27.819 290.227 26.9917 286.331 26.9917C282.108 26.9917 278.337 28.0114 275.086 30.0026C273.758 30.8203 272.537 31.7919 271.44 32.8885V30.9261C271.44 29.7333 270.468 28.7425 269.237 28.7425H261.743C260.541 28.7425 259.54 29.714 259.54 30.9261V82.2471C259.54 83.4399 260.512 84.4308 261.743 84.4308H269.237C270.439 84.4308 271.44 83.4592 271.44 82.2471V56.5722C271.44 50.7811 272.642 46.1348 275.009 42.8064C277.231 39.6704 280.559 38.1312 285.129 38.1312C292.978 38.1312 296.624 42.2773 296.624 51.2044V82.2471C296.624 83.4399 297.596 84.4308 298.827 84.4308H306.321C307.523 84.4308 308.524 83.4592 308.524 82.2471V47.9241C308.524 43.653 307.504 39.8724 305.503 36.6883H305.426H305.417Z" fill="#17C1FF"/>
+            <path d="M368.839 0.4702H361.374C360.172 0.4702 359.171 1.44179 359.171 2.66349V32.9655C357.748 31.7149 356.17 30.6279 354.496 29.7525C351.081 27.944 347.253 27.0494 343.183 27.0494C337.893 27.0494 333.073 28.3384 328.869 30.8684C324.675 33.408 321.376 36.9577 319.038 41.4308C316.71 45.8559 315.536 50.9254 315.536 56.5433C315.536 62.1612 316.729 67.3462 319.086 71.8001C321.462 76.2925 324.81 79.8806 329.033 82.4202C333.246 84.9502 338.075 86.2393 343.405 86.2393C347.426 86.2393 351.197 85.3254 354.573 83.4976C356.228 82.6126 357.767 81.5641 359.171 80.3232V82.2856C359.171 83.4784 360.153 84.4692 361.374 84.4692H368.868C370.07 84.4692 371.071 83.4977 371.071 82.2856V2.65386C371.071 1.46102 370.099 0.460571 368.868 0.460571L368.839 0.4702ZM359.171 56.5914C359.171 60.1988 358.469 63.4599 357.074 66.2881C355.699 69.097 353.852 71.2133 351.399 72.7525C348.975 74.2916 346.281 75.0419 343.164 75.0419C340.047 75.0419 337.469 74.3012 335.093 72.7525C332.688 71.2133 330.841 69.0681 329.466 66.2688C328.061 63.431 327.369 60.1507 327.369 56.4663C327.369 52.782 328.071 49.6364 329.466 46.8563C330.841 44.0762 332.688 41.9791 335.093 40.4207C337.46 38.8816 340.115 38.1312 343.164 38.1312C346.214 38.1312 348.984 38.872 351.399 40.4207C353.794 41.931 355.699 44.1147 357.074 46.8851C358.479 49.7133 359.171 52.9744 359.171 56.5818V56.601V56.5914Z" fill="#17C1FF"/>
+            <path d="M428.077 28.752H420.583C419.381 28.752 418.381 29.7237 418.381 30.9357V56.5818C418.381 62.3728 417.178 67.0191 414.812 70.3476C412.589 73.4836 409.261 75.0227 404.692 75.0227C396.852 75.0227 393.196 70.8766 393.196 61.9496V30.9069C393.196 29.714 392.225 28.7232 390.993 28.7232H383.5C382.297 28.7232 381.297 29.6948 381.297 30.9069V65.2299C381.297 69.501 382.316 73.2815 384.317 76.4657C386.337 79.6498 389.089 82.1124 392.484 83.7478C395.832 85.335 399.507 86.1623 403.403 86.1623C407.626 86.1623 411.397 85.1426 414.648 83.1513C415.976 82.3337 417.197 81.3909 418.323 80.2654V82.2278C418.323 83.4207 419.294 84.4115 420.526 84.4115H428.019C429.222 84.4115 430.222 83.4399 430.222 82.2278V30.9357C430.222 29.7429 429.251 28.752 428.019 28.752H428.068H428.077Z" fill="#17C1FF"/>
+            <path d="M473.049 27.8863C471.221 27.3187 469.297 27.0205 467.325 27.0205C463.054 27.0205 459.177 28.2134 455.762 30.599C454.291 31.6187 452.915 32.8404 451.636 34.2545V30.9742C451.636 29.7814 450.664 28.7905 449.433 28.7905H441.939C440.737 28.7905 439.736 29.7621 439.736 30.9742V82.2952C439.736 83.488 440.708 84.4789 441.939 84.4789H449.433C450.635 84.4789 451.636 83.5073 451.636 82.2952V57.7362C451.636 53.5612 452.386 49.9346 453.887 46.9044C455.358 43.9511 457.311 41.6809 459.687 40.1417C462.063 38.6026 464.555 37.8523 467.306 37.8523C468.826 37.8523 470.182 38.1505 471.433 38.7469C472.106 39.074 472.905 39.0163 473.53 38.6219C474.155 38.2274 474.55 37.5252 474.55 36.7845V29.9738C474.55 29.031 473.924 28.1845 473.03 27.9151L473.059 27.8863H473.049Z" fill="#17C1FF"/>
+            <path d="M527.14 58.3518C527.217 57.5342 527.266 56.4375 527.266 54.9465C527.266 49.7807 526.092 45.0093 523.822 40.8055C521.523 36.5825 518.271 33.1771 514.231 30.7145C510.162 28.2518 505.535 27.0109 500.542 27.0109C495.242 27.0109 490.422 28.2999 486.228 30.8395C482.034 33.3791 478.734 36.9577 476.387 41.45C474.069 45.8943 472.885 50.9928 472.885 56.5818C472.885 62.1708 474.088 67.2692 476.435 71.7424C478.811 76.2444 482.159 79.8229 486.401 82.3529C490.624 84.8925 495.492 86.1815 500.869 86.1815C506.641 86.1815 511.739 85.0176 516.03 82.68C520.301 80.3424 523.802 77.091 526.419 73.0122C527.044 72.0214 526.765 70.7035 525.794 70.0301L519.849 66.0764C519.349 65.7494 518.752 65.6243 518.146 65.7494C517.569 65.8744 517.069 66.2496 516.751 66.7402C515.202 69.3279 513.105 71.3672 510.527 72.8294C507.978 74.2724 504.659 75.0131 500.638 75.0131C495.838 75.0131 492.173 73.4451 489.422 70.1936C487.026 67.3558 485.545 64.1044 484.977 60.2758H525.005C526.13 60.2758 527.083 59.4292 527.179 58.3133L527.15 58.3422L527.14 58.3518ZM485.718 49.8288C486.613 46.7986 488.142 44.2397 490.287 42.0753C492.933 39.4395 496.261 38.1505 500.484 38.1505C504.707 38.1505 508.199 39.2664 510.681 41.5558C512.701 43.4413 514.154 46.231 514.952 49.8095H485.699L485.728 49.8384L485.718 49.8288Z" fill="#17C1FF"/>
+            <path fill-rule="evenodd" clip-rule="evenodd" d="M530.142 14.8805C526.563 14.8805 523.658 17.7856 523.658 21.3642C523.658 24.9427 526.563 27.8478 530.142 27.8478C533.72 27.8478 536.626 24.9427 536.626 21.3642C536.626 17.7856 533.72 14.8805 530.142 14.8805ZM522.215 21.3642C522.215 16.9872 525.765 13.4375 530.142 13.4375C534.519 13.4375 538.069 16.9872 538.069 21.3642C538.069 25.7411 534.519 29.2908 530.142 29.2908C525.765 29.2908 522.215 25.7411 522.215 21.3642Z" fill="#17C1FF"/>
+            <path d="M529.699 20.71C530.142 20.71 530.469 20.6234 530.671 20.4503C530.863 20.2867 530.969 20.0078 530.969 19.623C530.969 19.2382 530.863 18.9688 530.671 18.8053C530.479 18.6418 530.152 18.5648 529.699 18.5648H528.786V20.7196H529.699V20.71ZM528.795 22.201V25.3756H526.631V16.9872H529.93C531.037 16.9872 531.845 17.17 532.354 17.5451C532.874 17.9107 533.124 18.4975 533.124 19.3055C533.124 19.8635 532.989 20.3156 532.73 20.6715C532.46 21.0178 532.066 21.2872 531.518 21.4507C531.816 21.5277 532.075 21.6816 532.316 21.9125C532.556 22.153 532.787 22.5089 533.028 22.9995L534.211 25.3756H531.912L530.883 23.2881C530.681 22.8744 530.469 22.5762 530.257 22.4319C530.046 22.278 529.757 22.1914 529.411 22.1914H528.805L528.795 22.201Z" fill="#17C1FF"/>
+            <path d="M34.4303 53.2726V82.7762C34.4303 83.3053 34.7189 83.8055 35.171 84.0652L61.4424 99.2355C62.3851 99.7742 63.5394 99.7742 64.4822 99.2355L90.7535 84.0652C91.2153 83.7959 91.4942 83.3053 91.4942 82.7762V53.2726C91.4942 52.1279 90.2533 51.4064 89.2625 51.9836L64.4822 66.2881C63.5394 66.8268 62.3851 66.8268 61.4424 66.2881L36.6621 51.9836C35.6712 51.4064 34.4303 52.1279 34.4303 53.2726Z" fill="#17C1FF"/>
+            <path d="M28.6392 15.2556L2.36781 30.4163C1.42508 30.955 0.8479 31.965 0.8479 33.0425V63.3733C0.8479 63.9024 1.13649 64.4026 1.58862 64.6623L27.1385 79.4189C28.1293 79.9961 29.3702 79.2746 29.3702 78.1299V49.5209C29.3702 48.4339 29.9474 47.4335 30.8902 46.8948L55.6705 32.5903C56.6613 32.0131 56.6613 30.5798 55.6705 30.0122L30.1206 15.2556C29.6588 14.9863 29.0913 14.9863 28.6295 15.2556H28.6392Z" fill="#17C1FF"/>
+            <path d="M97.2852 15.2268L123.556 30.3874C124.499 30.9261 125.076 31.9362 125.076 33.0136V63.3444C125.076 63.8735 124.788 64.3737 124.336 64.6335L98.7858 79.3901C97.795 79.9672 96.5541 79.2458 96.5541 78.101V49.4921C96.5541 48.4051 95.9769 47.4046 95.0342 46.8659L70.2539 32.5615C69.263 31.9843 69.263 30.5509 70.2539 29.9834L95.8037 15.2268C96.2655 14.9574 96.833 14.9574 97.2948 15.2268H97.2852Z" fill="#17C1FF"/>
+        </svg>
+        <p class="subtitle">Build your dashboard or run in development mode to get started.</p>
+
+        <div class="commands">
+            <div class="command">
+                <div class="command-title">npx vite</div>
+                <div class="command-desc">Start development server</div>
+            </div>
+            <div class="command">
+                <div class="command-title">npx vite build</div>
+                <div class="command-desc">Build for production</div>
+            </div>
+        </div>
+
+        <div class="footer">
+            <a href="https://docs.vendure.io/guides/extending-the-dashboard/getting-started/" target="_blank">Documentation</a>
+        </div>
+
+        <div id="status" style="margin-top: 24px; font-size: 12px; color: #666;">
+            Checking for dashboard availability...
+        </div>
+    </div>
+
+    <script>
+        let pollInterval;
+        let statusElement = document.getElementById('status');
+
+        function pollStatus() {
+            fetch('__status')
+                .then(response => response.json())
+                .then(data => {
+                    if (data.mode === 'vite') {
+                        statusElement.textContent = 'Vite dev server detected! Refreshing...';
+                        statusElement.style.color = '#4ade80';
+                        setTimeout(() => globalThis.location.reload(), 500);
+                    } else if (data.mode === 'built') {
+                        statusElement.textContent = 'Built dashboard detected! Refreshing...';
+                        statusElement.style.color = '#4ade80';
+                        setTimeout(() => globalThis.location.reload(), 500);
+                    } else {
+                        statusElement.textContent = 'Waiting for dashboard to build or dev server to start...';
+                        statusElement.style.color = '#666';
+                    }
+                })
+                .catch(error => {
+                    statusElement.textContent = 'Status check failed';
+                    statusElement.style.color = '#ef4444';
+                });
+        }
+
+        // Start polling every 2 seconds
+        pollInterval = setInterval(pollStatus, 2000);
+
+        // Initial check
+        pollStatus();
+
+        // Clean up interval when page unloads
+        globalThis.addEventListener('beforeunload', () => {
+            if (pollInterval) {
+                clearInterval(pollInterval);
+            }
+        });
+    </script>
+</body>
+</html>

packages/dashboard/scripts/build-plugin.js

@@ -14,8 +14,10 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 const sourcePackageJson = path.join(__dirname, '../plugin/package.json');
+const sourceHtmlFile = path.join(__dirname, '../plugin/default-page.html');
 const outputDir = path.join(__dirname, '../dist/plugin');
 const outputPackageJson = path.join(outputDir, 'package.json');
+const outputHtmlFile = path.join(outputDir, 'default-page.html');
 
 try {
     // Ensure output directory exists
@@ -33,6 +35,15 @@ try {
         process.exit(1);
     }
 
+    // Copy default-page.html
+    if (fs.existsSync(sourceHtmlFile)) {
+        fs.copyFileSync(sourceHtmlFile, outputHtmlFile);
+        console.log(`Copied default-page.html from ${sourceHtmlFile} to ${outputHtmlFile}`);
+    } else {
+        console.error(`Source default-page.html not found at: ${sourceHtmlFile}`);
+        process.exit(1);
+    }
+
     console.log('Plugin build completed successfully');
 } catch (error) {
     console.error('Plugin build failed:', error.message);

packages/dashboard/src/lib/components/data-table/my-views-button.tsx

@@ -1,23 +1,27 @@
-import { Bookmark } from 'lucide-react';
-import React, { useState, useMemo } from 'react';
-import { Button } from '../ui/button.js';
-import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/tooltip.js';
 import { Trans } from '@lingui/react/macro';
-import { UserViewsSheet } from './user-views-sheet.js';
+import { Bookmark } from 'lucide-react';
+import React, { useMemo, useState } from 'react';
 import { useSavedViews } from '../../hooks/use-saved-views.js';
 import { findMatchingSavedView } from '../../utils/saved-views-utils.js';
+import { Button } from '../ui/button.js';
+import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/tooltip.js';
 import { useDataTableContext } from './data-table-context.js';
+import { UserViewsSheet } from './user-views-sheet.js';
 
 export const MyViewsButton: React.FC = () => {
     const [sheetOpen, setSheetOpen] = useState(false);
-    const { userViews } = useSavedViews();
-    const { columnFilters, searchTerm, handleApplyView } = useDataTableContext();
+    const { userViews, savedViewsAreAvailable } = useSavedViews();
+    const { columnFilters, searchTerm } = useDataTableContext();
 
     // Find the active view using centralized utility
     const activeView = useMemo(() => {
         return findMatchingSavedView(columnFilters, searchTerm, userViews);
     }, [userViews, columnFilters, searchTerm]);
 
+    if (!savedViewsAreAvailable) {
+        return null;
+    }
+
     return (
         <>
             <div className="flex items-center gap-2">
@@ -35,11 +39,7 @@ export const MyViewsButton: React.FC = () => {
                         <Trans>My saved views</Trans>
                     </TooltipContent>
                 </Tooltip>
-                {activeView && (
-                    <span className="text-sm text-muted-foreground">
-                        {activeView.name}
-                    </span>
-                )}
+                {activeView && <span className="text-sm text-muted-foreground">{activeView.name}</span>}
             </div>
             <UserViewsSheet open={sheetOpen} onOpenChange={setSheetOpen} />
         </>

packages/dashboard/src/lib/components/data-table/save-view-button.tsx

@@ -13,7 +13,7 @@ interface SaveViewButtonProps {
 
 export const SaveViewButton: React.FC<SaveViewButtonProps> = ({ disabled }) => {
     const [dialogOpen, setDialogOpen] = useState(false);
-    const { userViews, globalViews } = useSavedViews();
+    const { userViews, globalViews, savedViewsAreAvailable } = useSavedViews();
     const { columnFilters, searchTerm } = useDataTableContext();
 
     const hasFilters = columnFilters.length > 0 || (searchTerm && searchTerm.length > 0);
@@ -24,6 +24,10 @@ export const SaveViewButton: React.FC<SaveViewButtonProps> = ({ disabled }) => {
         return null;
     }
 
+    if (!savedViewsAreAvailable) {
+        return null;
+    }
+
     return (
         <>
             <Button variant="outline" size="sm" onClick={() => setDialogOpen(true)} disabled={disabled}>

packages/dashboard/src/lib/hooks/use-saved-views.ts

@@ -3,6 +3,7 @@ import {
     getSettingsStoreValueDocument,
     setSettingsStoreValueDocument,
 } from '@/vdb/graphql/settings-store-operations.js';
+import { useUserSettings } from '@/vdb/hooks/use-user-settings.js';
 import { SavedView, SavedViewsStore, SaveViewInput, UpdateViewInput } from '@/vdb/types/saved-views.js';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import { ColumnFiltersState } from '@tanstack/react-table';
@@ -19,6 +20,7 @@ const generateId = () => {
 
 export function useSavedViews() {
     const queryClient = useQueryClient();
+    const { settingsStoreIsAvailable } = useUserSettings();
     const { pageId } = usePage();
     const pageBlock = usePageBlock({ optional: true });
     const blockId = pageBlock?.blockId || 'default';
@@ -38,6 +40,8 @@ export function useSavedViews() {
             const allUserViews = (result?.getSettingsStoreValue as SavedViewsStore) || {};
             return allUserViews[pageId]?.[blockId] || [];
         },
+        retry: false,
+        enabled: settingsStoreIsAvailable,
     });
 
     // Query for global views
@@ -48,6 +52,8 @@ export function useSavedViews() {
             const allGlobalViews = (result?.getSettingsStoreValue as SavedViewsStore) || {};
             return allGlobalViews[pageId]?.[blockId] || [];
         },
+        retry: false,
+        enabled: settingsStoreIsAvailable,
     });
 
     // Save user view mutation
@@ -217,6 +223,7 @@ export function useSavedViews() {
     const canManageGlobalViews = hasPermissions(['WriteDashboardGlobalViews']);
 
     return {
+        savedViewsAreAvailable: settingsStoreIsAvailable,
         userViews: userViewsData || [],
         globalViews: globalViewsData || [],
         isLoading: userViewsLoading || globalViewsLoading,

packages/dashboard/src/lib/providers/auth.tsx

@@ -1,4 +1,4 @@
-import { api } from '@/vdb/graphql/api.js';
+import { api, SELECTED_CHANNEL_TOKEN_KEY } from '@/vdb/graphql/api.js';
 import { graphql, ResultOf } from '@/vdb/graphql/graphql.js';
 import { useUserSettings } from '@/vdb/hooks/use-user-settings.js';
 import { useQuery, useQueryClient } from '@tanstack/react-query';
@@ -170,8 +170,7 @@ export function AuthProvider({ children }: Readonly<{ children: React.ReactNode
                     // Clear all cached queries to prevent stale data
                     queryClient.clear();
                     // Clear selected channel from localStorage
-                    localStorage.removeItem('vendure-selected-channel');
-                    localStorage.removeItem('vendure-selected-channel-token');
+                    localStorage.removeItem(SELECTED_CHANNEL_TOKEN_KEY);
                     setStatus('unauthenticated');
                     setIsLoginLogoutInProgress(false);
                     onLogoutSuccess?.();

packages/dashboard/src/lib/providers/user-settings.tsx

@@ -43,6 +43,12 @@ const defaultSettings: UserSettings = {
 };
 
 export interface UserSettingsContextType {
+    /**
+     * @description
+     * Whether the server-side SettingsStore is available to use
+     * (i.e. the Vendure instance has the DashboardPlugin configured)
+     */
+    settingsStoreIsAvailable: boolean;
     settings: UserSettings;
     setDisplayLanguage: (language: string) => void;
     setDisplayLocale: (locale: string | undefined) => void;
@@ -86,19 +92,38 @@ export const UserSettingsProvider: React.FC<UserSettingsProviderProps> = ({ quer
     };
 
     const [settings, setSettings] = useState<UserSettings>(loadSettings);
+    const [settingsStoreIsAvailable, setSettingsStoreIsAvailable] = useState<boolean>(true);
     const [serverSettings, setServerSettings] = useState<UserSettings | null>(null);
     const [isReady, setIsReady] = useState(false);
     const previousContentLanguage = useRef(settings.contentLanguage);
     const saveInProgressRef = useRef(false);
 
     // Load settings from server on mount
-    const { data: serverSettingsResponse, isSuccess: serverSettingsLoaded } = useQuery({
+    const {
+        data: serverSettingsResponse,
+        isSuccess: serverSettingsLoaded,
+        error,
+    } = useQuery({
         queryKey: ['user-settings', SETTINGS_STORE_KEY],
-        queryFn: () => api.query(getSettingsStoreValueDocument, { key: SETTINGS_STORE_KEY }),
+        queryFn: () => {
+            console.log('runnign query, settingsStoreAvailable:', settingsStoreIsAvailable);
+            return api.query(getSettingsStoreValueDocument, { key: SETTINGS_STORE_KEY });
+        },
         retry: false,
         staleTime: 0,
+        enabled: settingsStoreIsAvailable,
     });
 
+    useEffect(() => {
+        if (
+            settingsStoreIsAvailable &&
+            error?.message.includes('Settings store field not registered: vendure.dashboard.userSettings')
+        ) {
+            logSettingsStoreWarning();
+            setSettingsStoreIsAvailable(false);
+        }
+    }, [settingsStoreIsAvailable, error]);
+
     // Mutation to save settings to server
     const saveToServerMutation = useMutation({
         mutationFn: (settingsToSave: UserSettings) =>
@@ -152,7 +177,7 @@ export const UserSettingsProvider: React.FC<UserSettingsProviderProps> = ({ quer
 
     // Save to server when settings differ from server state
     useEffect(() => {
-        if (isReady && serverSettings && !saveInProgressRef.current) {
+        if (settingsStoreIsAvailable && isReady && serverSettings && !saveInProgressRef.current) {
             const serverDiffers = JSON.stringify(serverSettings) !== JSON.stringify(settings);
 
             if (serverDiffers) {
@@ -177,6 +202,7 @@ export const UserSettingsProvider: React.FC<UserSettingsProviderProps> = ({ quer
     };
 
     const contextValue: UserSettingsContextType = {
+        settingsStoreIsAvailable,
         settings,
         setDisplayLanguage: language => updateSetting('displayLanguage', language),
         setDisplayLocale: locale => updateSetting('displayLocale', locale),
@@ -201,3 +227,21 @@ export const UserSettingsProvider: React.FC<UserSettingsProviderProps> = ({ quer
 
     return <UserSettingsContext.Provider value={contextValue}>{children}</UserSettingsContext.Provider>;
 };
+
+function logSettingsStoreWarning() {
+    // eslint-disable-next-line no-console
+    console.warn(
+        [
+            `User settings could not be fetched from the Vendure server.`,
+            `This suggests that the DashboardPlugin is not configured.`,
+            `Check your VendureConfig and ensure the DashboardPlugin is in your plugins array.`,
+            ``,
+            `By setting up the DashboardPlugin, you can take advantage of:`,
+            ` - Persisted settings across browsers and devices`,
+            ` - Saved views on list pages`,
+            ` - Metrics on the Insights page`,
+            ``,
+            `https://docs.vendure.io/reference/core-plugins/dashboard-plugin/`,
+        ].join('\n'),
+    );
+}

scripts/docs/generate-typescript-docs.ts

@@ -65,6 +65,10 @@ const sections: DocsSectionConfig[] = [
         sourceDirs: ['packages/telemetry-plugin/src/'],
         outputPath: '',
     },
+    {
+        sourceDirs: ['packages/dashboard/plugin/'],
+        outputPath: '',
+    },
     {
         sourceDirs: ['packages/admin-ui/src/lib/', 'packages/ui-devkit/src/'],
         exclude: [/generated-types/],