@xcons/cli - Configuration Guide

Configuration of XCON widget projects via the .xcon/config.json file.

Overview

Every XCON widget project contains a .xcon/config.json file in the root directory. This file controls the widget's build process, platform integration, and behavior.

File Location

my-widget/
├── .xcon/
│   └── config.json          # Main configuration file
├── src/
│   └── widget.ts
├── package.json
└── tsconfig.json

Basic Structure

Minimal Configuration

json

{
  "configurations": {
    "provider": "web",
    "id": "my-widget",
    "type": "latest",
    "fqn": "com.example.MyWidget"
  },
  "build": {
    "entry": "widget.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.min.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json"
  },
  "projectType": "widget",
  "version": "1.0"
}

Full Configuration (All Features)

json

{
  "configurations": {
    "provider": "web",
    "id": "advanced-widget",
    "type": "latest",
    "fqn": "com.example.AdvancedWidget"
  },
  "build": {
    "debug": true,
    "entry": "app.bootstrap.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.app.json",
    "externals": {
      "@xcons/common": "XConsCommon",
      "@xcons/core": "XConsCore",
      "@xcons/widget": "XConWidgetCore",
      "lodash": "_",
      "moment": "moment"
    }
  },
  "data": {
    "dataKeys": [
      {
        "name": "temperature",
        "label": "Temperature",
        "type": "timeseries",
        "settings": {
          "unit": "°C",
          "decimals": 1
        }
      }
    ],
    "dataKeysFunction": "",
    "latestDataKeys": [
      {
        "name": "status",
        "label": "Status",
        "type": "attribute",
        "settings": {
          "dataKeyType": "status"
        }
      }
    ],
    "latestDataKeysFunction": "",
    "additionalTypeParameters": {
      "maxDatasources": 1,
      "embedTitlePanel": true
    },
    "defaultConfig": {
      "title": "My Widget",
      "backgroundColor": "#ffffff",
      "showLegend": true
    }
  },
  "projectType": "widget",
  "version": "1.0"
}

Configuration Sections

1. configurations (Required)

Widget's platform integration and identity information.

`provider` (string, required)

The platform where the widget will run.

Supported values:

"web" - Web platform (recommended)
"thingsboard" - ThingsBoard platform

json

{
  "configurations": {
    "provider": "web"
  }
}

`id` (string, optional)

Widget's unique identifier.

Rules:

Use lowercase and hyphens
Do not use special characters
Must not contain spaces

json

{
  "configurations": {
    "id": "temperature-monitor"
  }
}

`type` (string, optional)

Widget type identifier.

Default: "latest"

json

{
  "configurations": {
    "type": "latest"
  }
}

`fqn` (string, optional)

Fully Qualified Name - Widget's fully qualified name.

Format: com.company.WidgetName

json

{
  "configurations": {
    "fqn": "com.xcon.TemperatureMonitor"
  }
}

2. build (Required)

Settings that control the build process.

`debug` (boolean, optional)

Enables debug mode.

Default: false

Debug mode features:

Console logs are preserved
Source map is generated
Code is not minified
Detailed error messages

json

{
  "build": {
    "debug": true
  }
}

`entry` (string, required)

Path to the main entry file (relative to sourceRoot).

json

{
  "build": {
    "entry": "widget.ts"           // Simple project
    // OR
    "entry": "app.bootstrap.ts"    // Project using bootstrap
  }
}

`sourceRoot` (string, required)

Directory containing the source code.

json

{
  "build": {
    "sourceRoot": "src"
  }
}

`outputFilename` (string, required)

Name of the compiled widget file.

json

{
  "build": {
    "outputFilename": "widget.min.js"  // Production
    // OR
    "outputFilename": "widget.js"      // Development
  }
}

`outputPath` (string, required)

Directory where compiled files will be written.

json

{
  "build": {
    "outputPath": "dist"
  }
}

`tsConfig` (string, required)

Path to the TypeScript configuration file.

json

{
  "build": {
    "tsConfig": "tsconfig.json"        // Default
    // OR
    "tsConfig": "tsconfig.app.json"    // Custom config
  }
}

`externals` (object, optional)

Mapping for excluding external libraries from the bundle.

Format: { "package-name": "GlobalVariable" }

Important: Libraries marked as external:

Reduce bundle size
Are loaded from global scope at runtime
Must be defined in the widget's resources array

json

{
  "build": {
    "externals": {
      "@xcons/common": "XConsCommon",
      "@xcons/core": "XConsCore",
      "@xcons/widget": "XConWidgetCore",
      "lodash": "_",
      "moment": "moment",
      "chart.js": "Chart"
    }
  }
}

Example usage:

config.json:

json

{
  "build": {
    "externals": {
      "lodash": "_"
    }
  }
}

widget.ts:

typescript

import _ from 'lodash'; // Not included in bundle

@Widget({
  resources: [
    {
      id: 'lodash-lib',
      name: 'Lodash',
      type: 'js',
      extension: true,
      url: 'https://cdn.jsdelivr.net/npm/lodash@4.17.21/lodash.min.js',
      order: 1
    }
  ]
})
export class MyWidget {
  onInit() {
    console.log(_.chunk([1,2,3,4], 2)); // Works at runtime
  }
}

3. data (Optional)

Widget data integration and platform-specific settings.

`dataKeys` (array, optional)

Data keys that the widget will use.

json

{
  "data": {
    "dataKeys": [
      {
        "name": "temperature",
        "label": "Temperature",
        "type": "timeseries",
        "settings": {
          "unit": "°C",
          "decimals": 1,
          "color": "#FF5722"
        }
      },
      {
        "name": "humidity",
        "label": "Humidity",
        "type": "timeseries",
        "settings": {
          "unit": "%",
          "decimals": 0,
          "color": "#2196F3"
        }
      }
    ]
  }
}

`dataKeysFunction` (string, optional)

JavaScript function for dynamic data keys.

Note: Overrides the dataKeys array when defined.

json

{
  "data": {
    "dataKeysFunction": "function() { return [{name: 'temp', label: 'Temperature', type: 'timeseries'}]; }"
  }
}

4. projectType (Required)

Specifies the project type.

Supported values:

"widget" - TypeScript widget project
"dotnet" - .NET widget project

json

{
  "projectType": "widget"
}

5. version (Required)

Configuration schema version.

json

{
  "version": "1.0"
}

Build Profiles

Development Profile

json

{
  "build": {
    "debug": true,
    "entry": "widget.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json"
  }
}

Features:

Debug mode active
Source map generated
Console logs preserved
No minification

Production Profile

json

{
  "build": {
    "debug": false,
    "entry": "widget.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.min.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json"
  }
}

Features:

Debug mode off
No source map generated
Console logs removed
Minified with Terser

Externals Management

Including Library in Bundle

Default behavior (NO external):

json

{
  "build": {
    "externals": {}
  }
}

typescript

import _ from 'lodash';  // INCLUDED in bundle (~70KB)

Marking Library as External

External definition:

json

{
  "build": {
    "externals": {
      "lodash": "_"
    }
  }
}

typescript

import _ from 'lodash';  // NOT included in bundle

@Widget({
  resources: [
    {
      id: 'lodash',
      name: 'Lodash',
      type: 'js',
      extension: true,
      url: 'https://cdn.jsdelivr.net/npm/lodash@4.17.21/lodash.min.js',
      order: 1
    }
  ]
})

Multiple External Libraries

json

{
  "build": {
    "externals": {
      "@xcons/common": "XConsCommon",
      "@xcons/widget": "XConWidgetCore",
      "lodash": "_",
      "moment": "moment",
      "chart.js": "Chart",
      "jquery": "$"
    }
  }
}

Widget resources definition:

typescript

@Widget({
  resources: [
    {
      id: 'xcons-common',
      name: 'XCONS Common',
      type: 'js',
      extension: true,
      url: 'https://unpkg.com/@xcons/common@latest/core.js',
      order: 1
    },
    {
      id: 'xcons-widget',
      name: 'XCONS Widget',
      type: 'js',
      extension: true,
      url: 'https://unpkg.com/@xcons/widget@latest/core.js',
      order: 2
    },
    {
      id: 'lodash',
      name: 'Lodash',
      type: 'js',
      extension: true,
      url: 'https://cdn.jsdelivr.net/npm/lodash@4.17.21/lodash.min.js',
      order: 3
    }
  ]
})

Validation and Error Management

Required Fields

The CLI automatically validates the following fields:

json

{
  "configurations": {
    "provider": "...",  // REQUIRED
    "id": "..."         // REQUIRED
  },
  "build": {
    "entry": "...",           // REQUIRED
    "sourceRoot": "...",      // REQUIRED
    "outputFilename": "...",  // REQUIRED
    "outputPath": "...",      // REQUIRED
    "tsConfig": "..."         // REQUIRED
  },
  "projectType": "...",  // REQUIRED
  "version": "..."       // REQUIRED
}

Error Messages

Missing provider:

Error: Missing configurations.provider

Invalid provider:

Error: Provider 'invalid' not supported. Use 'web' or 'thingsboard'

Missing entry:

Error: Missing build.entry

Entry file not found:

Error: Entry file not found: src/widget.ts

Upgrade and Migration

From 1.0 to New Version

json

// Old format (1.0)
{
  "configurations": {
    "provider": "web"
  },
  "build": {
    "entry": "widget.ts"
  }
}

// New format (future version)
{
  "configurations": {
    "provider": "web",
    "version": "2.0"
  },
  "build": {
    "entry": "widget.ts",
    "optimization": {
      "treeshake": true,
      "minify": true
    }
  }
}

Best Practices

1. Provider Selection

Web: For general web applications
ThingsBoard: For IoT and dashboard projects

2. Debug Mode

Development:

json

{"build": {"debug": true}}

Production:

json

{"build": {"debug": false}}

4. Output Filename

Naming convention:

widget.min.js        // Production
widget.js           // Development
widget-v1.2.3.js    // Versioned

Troubleshooting

Build Error: Entry Not Found

Problem:

Error: Entry file not found: src/widget.ts

Solution:

json

{
  "build": {
    "entry": "widget.ts",        // Check file name
    "sourceRoot": "src"          // Check directory
  }
}

External Library Not Working

Problem: External library is undefined

Solution:

Verify global variable name
Check if it's defined in resources array
Check loading order

json

{
  "build": {
    "externals": {
      "lodash": "_"  // Is global variable name correct?
    }
  }
}

TypeScript Config Not Found

Problem:

Error: tsconfig.json not found

Solution:

json

{
  "build": {
    "tsConfig": "tsconfig.json"  // Does the file exist?
  }
}

Advanced Features

Conditional Configuration

Config management for different environments:

config.json (base):

json

{
  "configurations": {
    "provider": "web"
  }
}

Override in build command:

bash

# Development
xcons widget build --debug

# Production
xcons widget build --production

Separate config for each widget:

project/
├── widget1/
│   └── .xcon/config.json
├── widget2/
│   └── .xcon/config.json

References

Your config file is ready! For build process:

bash

xcons widget build --production

@xcons/cli - Configuration Guide ​

Overview ​

File Location ​

Basic Structure ​

Minimal Configuration ​

Full Configuration (All Features) ​

Configuration Sections ​

1. configurations (Required) ​

provider (string, required) ​

id (string, optional) ​

type (string, optional) ​

fqn (string, optional) ​

2. build (Required) ​

debug (boolean, optional) ​

entry (string, required) ​

sourceRoot (string, required) ​

outputFilename (string, required) ​

outputPath (string, required) ​

tsConfig (string, required) ​

externals (object, optional) ​

3. data (Optional) ​

dataKeys (array, optional) ​

dataKeysFunction (string, optional) ​

4. projectType (Required) ​

5. version (Required) ​

Build Profiles ​

Development Profile ​

Production Profile ​

Externals Management ​

Including Library in Bundle ​

Marking Library as External ​

Multiple External Libraries ​

Validation and Error Management ​

Required Fields ​

Error Messages ​

Upgrade and Migration ​

From 1.0 to New Version ​

Best Practices ​

1. Provider Selection ​

2. Debug Mode ​

4. Output Filename ​

Troubleshooting ​

Build Error: Entry Not Found ​

External Library Not Working ​

TypeScript Config Not Found ​

Advanced Features ​

Conditional Configuration ​

Multi-Widget Projects ​

References ​

@xcons/cli - Configuration Guide

Overview

File Location

Basic Structure

Minimal Configuration

Full Configuration (All Features)

Configuration Sections

1. configurations (Required)

`provider` (string, required)

`id` (string, optional)

`type` (string, optional)

`fqn` (string, optional)

2. build (Required)

`debug` (boolean, optional)

`entry` (string, required)

`sourceRoot` (string, required)

`outputFilename` (string, required)

`outputPath` (string, required)

`tsConfig` (string, required)

`externals` (object, optional)

3. data (Optional)

`dataKeys` (array, optional)

`dataKeysFunction` (string, optional)

4. projectType (Required)

5. version (Required)

Build Profiles

Development Profile

Production Profile

Externals Management

Including Library in Bundle

Marking Library as External

Multiple External Libraries

Validation and Error Management

Required Fields

Error Messages

Upgrade and Migration

From 1.0 to New Version

Best Practices

1. Provider Selection

2. Debug Mode

4. Output Filename

Troubleshooting

Build Error: Entry Not Found

External Library Not Working

TypeScript Config Not Found

Advanced Features

Conditional Configuration

Multi-Widget Projects

References