DevExpress Dashboard CLI

25.2.6 verified Thu Apr 23 auth: no javascript

The `devexpress-dashboard-cli` package provides command-line interface tools specifically designed to streamline development with DevExpress Dashboards. Its primary functions include building custom themes for the Web Dashboard using metadata from the DevExtreme ThemeBuilder and generating new application projects that integrate DevExpress Dashboard controls. The current stable version is 25.2.6, aligning with DevExpress's consistent twice-per-year major release cadence. This CLI is an essential tool for developers working within the DevExpress ecosystem, enabling automated theme generation and project setup, differentiating it from generic CLIs by its deep integration with DevExpress components and design patterns. It handles the conversion of customized DevExtreme ThemeBuilder resource files into Web Dashboard themes and assists in the initial scaffolding of DevExpress-enabled applications, particularly in client-server architectures like Angular with ASP.NET Core backends.

Common errors

error NU1101: Unable to find package DevExpress. <Product>.ProjectTemplates ↓

cause The .NET CLI is unable to find DevExpress project templates because the NuGet package source is either not configured or disabled.

fix

Configure your DevExpress NuGet Feed as a package source. First, obtain your personal NuGet feed URL from nuget.devexpress.com (requires a registered user account). Then, register it using dotnet nuget add source <source-url> -n DevExpress or enable it with dotnet nuget enable source <source-name> if it's already listed but disabled.

error SyntaxError: Unexpected token 'export' (in Jest tests involving DevExtreme/Angular) ↓

cause Jest, running in CommonJS (CJS) mode, is attempting to parse an ECMAScript Module (ESM) bundle from a DevExtreme-related dependency (e.g., `@preact/signals-core`), which CJS cannot directly import.

fix

Configure Jest's transformIgnorePatterns to transpile DevExtreme and its ESM-only dependencies (e.g., @preact/signals-core) from ESM to CJS during testing. Alternatively, explore Jest presets for Angular that handle ESM modules or migrate to a test runner that natively supports ESM.

error Dashboard works locally but fails on production server (e.g., connection errors) ↓

cause The dashboard application cannot establish a database connection on the production server due to incorrect connection strings, insufficient database permissions for the web server's identity (e.g., IUSR), or firewall restrictions.

fix

Verify the database connection string in your production environment. Ensure the identity under which your web application runs on the server has the necessary permissions to access the database. Check server firewalls and database security settings. Utilize server-side logging or DevExpress's ASPxDashboard.ConnectionError event and HandleServerErrors property to get detailed error information.

Warnings

breaking All DevExpress npm packages, including `devexpress-dashboard-cli`, and corresponding client-side scripts/server-side libraries, must use matching major.minor version numbers. Mismatched versions can lead to runtime errors and unexpected behavior. ↓

fix Ensure all DevExpress-related packages in your `package.json` (e.g., `devexpress-dashboard`, `devextreme`, `@devexpress/analytics-core`) and server-side components explicitly specify the exact same version (e.g., `25.2.6`). Use `npm install --save-exact` or update `package.json` manually and reinstall.

gotcha `devexpress-dashboard-cli` lists several packages as peer dependencies, which npm versions 3+ do not automatically install. These must be manually installed and updated alongside the CLI to ensure full functionality. ↓

fix Manually install all peer dependencies listed in the `package.json` for `devexpress-dashboard-cli` (e.g., `devexpress-dashboard`, `devextreme-themebuilder`, `@devexpress/analytics-core`, `@devexpress/analytics-core-cli`) using `npm install <package-name>@<version> --save-exact`.

gotcha Older versions (e.g., v23.1.5) of `devexpress-dashboard-cli` had reported moderate severity vulnerabilities in transient dependencies like `less` and `request`. While DevExpress indicated these might not be exploitable in common usage scenarios for theme building, it highlights the importance of regular security audits. ↓

fix Always use the latest stable version of `devexpress-dashboard-cli` (currently 25.2.6) and regularly run `npm audit` to check for and address any reported vulnerabilities in direct or transient dependencies. Update affected packages if fixes are available.

gotcha When building Angular applications that use DevExtreme components (which often accompany DevExpress Dashboards) with `--prod` (AOT compilation), `SyntaxError: Unexpected token 'export'` errors may occur at runtime. This can be related to how bundlers and test runners (like Jest) handle ESM/CJS modules from DevExtreme's dependencies. ↓

fix For testing environments (e.g., Jest), configure your test runner to correctly handle ECMAScript Modules (ESM) that DevExtreme packages (or their dependencies like `@preact/signals-core`) might ship. This often involves transforming ESM to CommonJS for Jest or updating Jest's module resolution. Consult DevExtreme/Angular documentation for specific setup guides.

gotcha The `devexpress-dashboard-cli` package is focused on client-side asset generation (themes) and project scaffolding. It does not provide a backend for dashboards. A separate ASP.NET Core or ASP.NET MVC application is required to serve as the backend (server-side) for the Web Dashboard. ↓

fix When developing a Web Dashboard application, ensure you also set up a compatible DevExpress Dashboard backend project using ASP.NET Core or ASP.NET MVC. The client-side dashboard generated or themed by the CLI will communicate with this backend for data operations.

Install

npm install devexpress-dashboard-cli

yarn add devexpress-dashboard-cli

pnpm add devexpress-dashboard-cli

Imports

dev-dashboard
wrong
```
import { buildTheme } from 'devexpress-dashboard-cli';
```
correct
```
npx devexpress-dashboard-cli <command> [options]
```
This package is a command-line interface tool and is invoked via `npx` or `npm run` scripts. It is not intended for direct JavaScript/TypeScript `import` into application code. Its functionality is exposed through subcommands like `build-theme` or `create`.
Build Theme
wrong
```
devexpress-dashboard-cli build-theme
```
correct
```
npx devexpress-dashboard-cli build-theme --input-file="./theme-metadata.json" --output-file="./dx-dashboard.custom-theme.css" --output-color-scheme="custom-scheme"
```
Always specify input and output files, and optionally a color scheme name, as this is the primary method for customizing dashboard themes. Requires a JSON metadata file generated by DevExtreme ThemeBuilder.
Help
wrong
```
npx devexpress-dashboard-cli help
```
correct
```
npx devexpress-dashboard-cli --help
```
Use the standard `--help` flag to view available commands and options for the CLI, or specific subcommands like `npx devexpress-dashboard-cli build-theme --help`.

Quickstart

Demonstrates how to install the CLI's peer dependencies and use the `build-theme` command to generate a custom CSS theme file from metadata.

{
  "name": "my-dashboard-app",
  "version": "1.0.0",
  "description": "DevExpress Dashboard application with custom theme",
  "scripts": {
    "install-deps": "npm install devexpress-dashboard@25.2.6 devextreme-themebuilder@25.2.6 @devexpress/analytics-core@25.2.6 @devexpress/analytics-core-cli@25.2.6 devextreme@25.2.6",
    "build-custom-theme": "npx devexpress-dashboard-cli build-theme --input-file='./src/custom-theme-metadata.json' --output-file='./src/dx-dashboard.custom.css' --output-color-scheme='light-yellow'"
  },
  "keywords": [],
  "author": "",
  "license": "MIT"
}

// To run this quickstart:
// 1. Save the above JSON as package.json in an empty directory.
// 2. Create a file named 'src/custom-theme-metadata.json'. (Content can be an empty JSON object {} for a default build, or actual metadata from DevExtreme ThemeBuilder).
// 3. Open your terminal in the directory and run:
//    npm run install-deps
//    npm run build-custom-theme
// This will generate 'src/dx-dashboard.custom.css' based on the theme metadata.