DevExtreme Angular - DevExtreme CLI

DevExtreme CLI is a set of command-line tools to be used with the DevExtreme controls library.

Requirements

  • Node.js v12.6.0 or later
  • npm v6.2.0 or later

Installation

npm i -g devextreme-cli

Alternatively, you can use npx to execute DevExtreme CLI commands without installing the CLI globally. Examples in this article illustrate both approaches.

Add DevExtreme to an Existing Application

Angular
devextreme add devextreme-angular
// ===== or without installing the DevExtreme CLI =====
npx -p devextreme-cli devextreme add devextreme-angular

This command does the following:

These steps are explained in the Add DevExtreme to an Angular CLI Application article.

Once the command is executed, import DevExtreme modules.

Vue
devextreme add devextreme-vue
// ===== or without installing the DevExtreme CLI =====
npx -p devextreme-cli devextreme add devextreme-vue

This command does the following:

These steps are explained in the Add DevExtreme to a Vue Application article.

Once the command is executed, import DevExtreme components.

React
devextreme add devextreme-react
// ===== or without installing the DevExtreme CLI =====
npx -p devextreme-cli devextreme add devextreme-react

This command does the following:

These steps are explained in the Add DevExtreme to an React Application article.

Once the command is executed, import DevExtreme components.

DevExtreme Application

Create a New Application

Angular

Create a new DevExtreme Angular application that uses the DevExtreme layout template:

devextreme new angular-app app-name [--layout][--empty]
// ===== or without installing the DevExtreme CLI =====
npx -p devextreme-cli devextreme new angular-app app-name [--layout][--empty]
Vue

Create a new DevExtreme Vue application that uses the DevExtreme layout template:

devextreme new vue-app app-name [--layout][--empty][--version]
// ===== or without installing the DevExtreme CLI =====
npx -p devextreme-cli devextreme new vue-app app-name [--layout][--empty][--version]
React

Create a new DevExtreme React application that uses the DevExtreme layout template:

devextreme new react-app app-name [--layout][--empty]
// ===== or without installing the DevExtreme CLI =====
npx -p devextreme-cli devextreme new react-app app-name [--layout][--empty]

Arguments:

  • --layout
    Specifies the DevExtreme layout to add. Available values:

    • side-nav-outer-toolbar (default)
    • side-nav-inner-toolbar

    Both layouts are illustrated in the Layouts article.

  • --empty
    Specifies whether to skip sample views generation (default: false).

  • --version, -v (Vue only)
    Specifies whether to generate a Vue 2 or Vue 3 application. Available values: 2 (default) and 3.

Add the DevExtreme Layout to an Existing Application

Add the DevExtreme layout template to an existing Angular application:

devextreme add angular-template [--layout][--empty][--resolve-conflicts]
// ===== or =====
npx -p devextreme-cli devextreme add angular-template [--layout][--empty][--resolve-conflicts]

Arguments:

  • --layout
    Specifies the DevExtreme layout to add. Available values:

    • side-nav-outer-toolbar (default)
    • side-nav-inner-toolbar

    Both layouts are illustrated in the Layouts article.

  • --empty
    Specifies whether to skip sample views generation (default: false).

  • --resolve-conflicts
    Specifies whether to override the existing app.component or create a component with another name. Available values:

    • createNew (default)
    • override (NOTE: all changes in the overridden files will be lost)

    If you created a new component, register it in app.module.ts:

    app.module.ts
    // ...
    import { AppComponent } from './app1.component';
    // ...
NOTE
This command is not supported for Vue and React.

Add a View to the Application

The following command adds a view to an application that uses the DevExtreme layout template for Angular, Vue, or React:

devextreme add view view-name [--icon]
// ===== or =====
npx -p devextreme-cli devextreme add view view-name [--icon]

Arguments:

ThemeBuilder

The ThemeBuilder UI is a tool that allows you to create custom themes in the browser; its CLI counterpart allows you to do the same with commands.

IMPORTANT

If your application uses npm v7 or later, open package.json and ensure the following:

  • The devextreme package is listed in dependencies.
  • The devextreme-themebuilder package is listed in devDependencies.
  • Both packages have the same version.

If these conditions are not met, run the following commands to install the packages:

npm i devextreme@21.1 --save --save-exact
npm i devextreme-themebuilder@21.1 --save-dev --save-exact

Build a Custom Color Scheme

devextreme build-theme [--base-theme][--input-file][--make-swatch][--output-file][--version][--widgets][--assetsBasePath][--output-color-scheme][--help]
// ===== or without installing the DevExtreme CLI =====
npx -p devextreme-cli devextreme build-theme [--base-theme][--input-file][--make-swatch][--output-file][--version][--widgets][--assetsBasePath][--output-color-scheme]

Export Theme Variables

The following command exports theme variables as a .less or .scss file:

devextreme export-theme-vars [--base-theme][--input-file][--output-format][--output-file][--version][--base][--help]
// ===== or =====
npx -p devextreme-cli devextreme export-theme-vars [--base-theme][--input-file][--output-format][--output-file][--version][--base]

Export Theme Metadata

Theme metadata is a JSON object that describes the theme. It is used to export or import a theme in the ThemeBuilder UI. Below is an example of theme metadata.

{
    "items": [
        {
            "key": "$base-text-color",
            "value": "rgba(94, 33, 33, 0.87)"
        },
        {
            "key": "$base-accent",
            "value": "rgba(64, 156, 199, 1)"
        }
    ],
    "baseTheme": "material.blue.light.compact",
    "outputColorScheme": "custom-scheme",
    "makeSwatch": true,
    "version": "21.1.11",
    "widgets": ["datagrid","treelist","selectbox"],
    "assetsBasePath": "../../../node_modules/devextreme/dist/css/"
}

The metadata object contains the following properties:

  • items
    An array that describes customized theme variables.

    • key
      A theme variable's name.
    • value
      The theme variable's value.
  • baseTheme
    A predefined DevExtreme theme which the custom theme is based on.

  • outputColorScheme
    The custom theme's color scheme.

  • makeSwatch
    A flag that indicates whether the theme is a color swatch.

  • version
    The target DevExtreme version.

  • widgets
    A list of UI components whose styles are included in the resulting CSS file.

  • assetsBasePath
    A path to the folder that contains the DevExtreme icons and fonts folders. This property is used only if the icons and fonts are not in the same folder as your custom theme.

Run the following command to export the metadata as a .json file:

devextreme export-theme-meta [--base-theme][--input-file][--output-file][--base][--help]
// ===== or =====
npx -p devextreme-cli devextreme export-theme-meta [--base-theme][--input-file][--output-file][--base]

Command-Line Arguments

  • --base-theme
    Specifies a base theme's name (default: generic.light).

  • --input-file
    Specifies the name of the file that contains input data (a .json file with metadata or a .less or .scss file with Bootstrap variables).

  • --output-file
    Specifies the output file name.

  • --output-format
    Specifies the format of the output variables: less or scss (default: less or the extension extracted from the --output-file value (if it contains any)).

  • --output-color-scheme
    Specifies the custom color scheme name (default: custom-scheme).

  • --make-swatch
    When present, creates a color swatch, i.e., adds a CSS scope to each CSS rule (.dx-swatch-xxx, where xxx is the value from the --output-color-scheme parameter).

  • --base
    Exports only base variables used to produce derived variables.

  • --version
    Specifies the target DevExtreme version or a tag that points to it (the default value is latest).

  • --widgets
    Specifies a comma-separated list of UI components whose styles should be included in the resulting CSS file. If this argument is not specified, styles of all UI components are included. Syntax example:

    --widgets=datagrid,treelist,selectbox
  • --assetsBasePath
    Specifies a path to the folder that contains the DevExtreme icons and fonts folders. Use this argument if the icons and fonts are not in the same folder as your custom theme.

  • --remove-external-resources
    When present, removes links to external resources, such as fonts. The theme will use local fallbacks instead.

  • --bootstrap-version (available since v21.1.5) Specifies Bootstrap version 4 or 5 if --input-file is a .scss file (default: 4).

Examples

Generate a new custom color swatch that uses Generic Dark as a base theme:

npx -p devextreme-cli devextreme build-theme --base-theme="generic.dark" --make-swatch --output-color-scheme="custom"

Generate a new pink color scheme based on the Material Blue Light theme, use constants from the pink.json file:

npx -p devextreme-cli devextreme build-theme --base-theme="material.blue.light" --input-file="pink.json" --output-color-scheme="pink"

Export base variables for the Generic Carmine theme in LESS format:

npx -p devextreme-cli devextreme export-theme-vars --base-theme="generic.carmine" --output-format="less" --base