{"id":17571,"library":"devexpress-dashboard-cli","title":"DevExpress Dashboard CLI","description":"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.","status":"active","version":"25.2.6","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","devexpress","dashboard","cli","themebuilder","theme","application"],"install":[{"cmd":"npm install devexpress-dashboard-cli","lang":"bash","label":"npm"},{"cmd":"yarn add devexpress-dashboard-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add devexpress-dashboard-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for core dashboard functionality and theme generation targets.","package":"devexpress-dashboard","optional":false},{"reason":"Essential for generating custom theme metadata which the CLI processes.","package":"devextreme-themebuilder","optional":false},{"reason":"Provides core analytics functionality that DevExpress Dashboard relies upon.","package":"@devexpress/analytics-core","optional":false},{"reason":"Provides complementary CLI functionality for analytics components.","package":"@devexpress/analytics-core-cli","optional":false}],"imports":[{"note":"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`.","wrong":"import { buildTheme } from 'devexpress-dashboard-cli';","symbol":"dev-dashboard","correct":"npx devexpress-dashboard-cli <command> [options]"},{"note":"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.","wrong":"devexpress-dashboard-cli build-theme","symbol":"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\""},{"note":"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`.","wrong":"npx devexpress-dashboard-cli help","symbol":"Help","correct":"npx devexpress-dashboard-cli --help"}],"quickstart":{"code":"{\n  \"name\": \"my-dashboard-app\",\n  \"version\": \"1.0.0\",\n  \"description\": \"DevExpress Dashboard application with custom theme\",\n  \"scripts\": {\n    \"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\",\n    \"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'\"\n  },\n  \"keywords\": [],\n  \"author\": \"\",\n  \"license\": \"MIT\"\n}\n\n// To run this quickstart:\n// 1. Save the above JSON as package.json in an empty directory.\n// 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).\n// 3. Open your terminal in the directory and run:\n//    npm run install-deps\n//    npm run build-custom-theme\n// This will generate 'src/dx-dashboard.custom.css' based on the theme metadata.","lang":"javascript","description":"Demonstrates how to install the CLI's peer dependencies and use the `build-theme` command to generate a custom CSS theme file from metadata."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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`.","message":"`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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<25.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=25.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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.","cause":"The .NET CLI is unable to find DevExpress project templates because the NuGet package source is either not configured or disabled.","error":"NU1101: Unable to find package DevExpress. <Product>.ProjectTemplates"},{"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.","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.","error":"SyntaxError: Unexpected token 'export' (in Jest tests involving DevExtreme/Angular)"},{"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.","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.","error":"Dashboard works locally but fails on production server (e.g., connection errors)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}