Web Widget Create

Detailed usage guide for creating a new widget project for the web platform.

Overview

The xcons widget create command creates a ready-to-use TypeScript widget project for the web platform. It automatically sets up the project structure, IDE configurations, and build system.

Command Syntax

bash

xcons widget create [options]
npx @xcons/cli widget create [options]

Options

Option	Shortcut	Type	Default	Description
`--name <name>`	`-n`	string	-	Widget project name
`--description <desc>`	`-d`	string	-	Widget description
`--no-interaction`	-	flag	false	No interactive questions asked

Usage Examples

1. Interactive Mode (Recommended)

Simplest usage - the command asks for required information interactively:

bash

xcons widget create

Interaction:

? Widget name: temperature-monitor
? Widget description: Real-time temperature monitoring widget
? Do you want to run npm install now? Yes

2. With Name Parameter

Provide the widget name as a parameter:

bash

xcons widget create -n temperature-monitor

Interaction:

? Widget description: Real-time temperature monitoring widget
? Do you want to run npm install now? Yes

3. Fully Parameterized

Provide all parameters on the command line:

bash

xcons widget create -n temperature-monitor -d "Real-time temperature monitoring widget"

Interaction:

? Do you want to run npm install now? Yes

4. Non-Interactive Mode

For CI/CD or script usage:

bash

xcons widget create -n temperature-monitor --no-interaction

Behavior:

Widget name: temperature-monitor
Description: "temperature-monitor widget" (automatic)
npm install: Skipped
No questions asked

5. Directly with NPX

Without global installation:

bash

npx @xcons/cli widget create -n my-widget

Generated Project Structure

Directory Structure

my-widget/
├── .idea/                          # IntelliJ IDEA / WebStorm config
│   ├── workspace.xml
│   ├── modules.xml
│   └── my-widget.iml
├── .vscode/                        # VS Code config
│   ├── launch.json                 # Debug configuration
│   ├── tasks.json                  # Build tasks
│   └── extensions.json             # Recommended extensions
├── .xcon/                          # XCON configuration
│   └── config.json                 # Widget build config
├── src/                            # Widget source code
│   ├── widget.ts                   # Main widget logic
│   ├── widget.html                 # Widget template
│   └── widget.css                  # Widget styles
├── dist/                           # Build output (created on build)
│   └── widget.min.js
├── package.json                    # NPM dependencies
├── tsconfig.json                   # TypeScript config
├── vite.config.ts                  # Vite build config
├── .gitignore
└── README.md

Auto-Generated Files

1. .xcon/config.json

json

{
  "configurations": {
    "provider": "web",
    "id": ""
  },
  "projectType": "widget",
  "version": "1.0"
}

Note: Provider and ID fields are left empty, should be filled by the developer.

2. package.json

Contains basic dependencies and scripts:

json

{
  "name": "my-widget",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "devDependencies": {
    "@xcons/widget": "latest",
    "typescript": "~5.5.2",
    "vite": "^5.0.0"
  }
}

3. VS Code Launch Configuration (.vscode/launch.json)

json

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "Launch Widget",
      "url": "http://localhost:4201",
      "webRoot": "${workspaceFolder}"
    }
  ]
}

Usage: Launch the widget in debug mode with the F5 key.

4. IntelliJ IDEA Configuration

.iml file is automatically created based on the widget name:

xcon-web-cli.iml → renamed to my-widget.iml
modules.xml file is updated
workspace.xml is cleaned

Workflow

bash

# Create project
xcons widget create -n temperature-monitor

# Navigate to directory
cd temperature-monitor

2. Installing Dependencies

Automatic installation (recommended):

bash

xcons widget create -n my-widget
# "Do you want to run npm install now?" → Yes

Manual installation:

bash

npm install

3. Development

Start development server:

bash

npm run dev
# Opens at http://localhost:4201

Make code changes:

bash

# With VS Code
code .

# With IntelliJ IDEA / WebStorm
idea .

4. Build

Development build:

bash

xcons widget build

Production build:

bash

xcons widget build --production

5. Deploy

Upload the build output to the platform:

bash

# Build file
dist/widget.min.js

Configuration Steps

1. Setting Provider

Edit the .xcon/config.json file:

json

{
  "configurations": {
    "provider": "web",              // "web" or "thingsboard"
    "id": "temperature-monitor"     // Widget ID
  },
  "projectType": "widget",
  "version": "1.0"
}

2. Build Settings

Full build configuration:

json

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

3. External Libraries

Using external libraries like Chart.js:

.xcon/config.json:

json

{
  "build": {
    "externals": {
      "chart.js": "Chart"
    }
  }
}

src/widget.ts:

typescript

import Chart from 'chart.js';

@Widget({
  resources: [
    {
      id: 'chartjs',
      name: 'Chart.js',
      type: 'js',
      extension: true,
      url: 'https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js',
      order: 1
    }
  ]
})
export class MyWidget {
  onInit() {
    const chart = new Chart(ctx, config);
  }
}

IDE Usage

VS Code

Launch debug:

Open project in VS Code: code .
Press F5
Widget opens automatically in browser

Build task:

Ctrl+Shift+B
Select "Build Widget"
See build output in terminal

Recommended extensions:

TypeScript
Vetur (Vue syntax)
ESLint
Prettier

IntelliJ IDEA / WebStorm

Run/Debug:

Open project: idea .
Run configurations load automatically
Shift+F10 - Run
Shift+F9 - Debug

Build:

Build menu → Build Project
Or terminal: npm run build

Custom Scenarios

bash

xcons widget create -n chart-widget -d "Interactive chart widget"
cd chart-widget

.xcon/config.json:

json

{
  "configurations": {
    "provider": "web",
    "id": "chart-widget"
  },
  "build": {
    "entry": "widget.ts",
    "sourceRoot": "src",
    "outputFilename": "chart.min.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json",
    "externals": {
      "chart.js": "Chart"
    }
  },
  "data": {
    "dataKeys": [
      {
        "name": "value",
        "label": "Value",
        "type": "timeseries"
      }
    ],
    "defaultConfig": {
      "title": "Chart Widget",
      "chartType": "line"
    }
  },
  "projectType": "widget",
  "version": "1.0"
}

bash

xcons widget create -n map-widget -d "Interactive map widget"
cd map-widget

.xcon/config.json:

json

{
  "configurations": {
    "provider": "web",
    "id": "map-widget"
  },
  "build": {
    "externals": {
      "leaflet": "L"
    }
  },
  "data": {
    "dataKeys": [
      {"name": "latitude", "label": "Latitude", "type": "timeseries"},
      {"name": "longitude", "label": "Longitude", "type": "timeseries"}
    ]
  },
  "projectType": "widget",
  "version": "1.0"
}

bash

xcons widget create -n dashboard-widget -d "Multi-component dashboard"
cd dashboard-widget

Multi-component structure:

dashboard-widget/
├── src/
│   ├── widget.ts                    # Main widget
│   ├── components/
│   │   ├── chart.component.ts       # Chart component
│   │   ├── table.component.ts       # Table component
│   │   └── gauge.component.ts       # Gauge component
│   ├── widget.html
│   └── widget.css

Troubleshooting

Issue: Directory already exists

Error:

Error: Directory 'my-widget' already exists and is not empty

Solution 1 - Different name:

bash

xcons widget create -n my-widget-v2

Solution 2 - Delete directory:

bash

rm -rf my-widget
xcons widget create -n my-widget

Issue: Template download failed

Error:

Error: Failed to download template: ETIMEDOUT

Solution - Network check:

bash

# Test connection
ping github.com

# Proxy settings (if needed)
npm config set proxy http://proxy:8080
npm config set https-proxy http://proxy:8080

# Try again
xcons widget create -n my-widget

Issue: npm install failed

Error:

Warning: npm install failed: EACCES

Solution 1 - Manual installation:

bash

cd my-widget
npm install

Solution 2 - Change NPM global directory:

bash

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Issue: .idea files not updated

Issue: IntelliJ IDEA shows old project name

Solution - Manual update:

bash

cd my-widget/.idea
# xcon-web-cli.iml → my-widget.iml
mv xcon-web-cli.iml my-widget.iml

# modules.xml update
# Replace xcon-web-cli.iml references with my-widget.iml

Best Practices

Correct:

bash

xcons widget create -n temperature-monitor
xcons widget create -n device-tracker
xcons widget create -n real-time-chart

Wrong:

bash

xcons widget create -n "Temperature Monitor"  # No spaces
xcons widget create -n temp_monitor           # Dash instead of underscore
xcons widget create -n TemperatureMonitor     # Not camel case

2. Description

Good description:

bash

xcons widget create -n temp-monitor -d "Real-time temperature monitoring with alerts"

Bad description:

bash

xcons widget create -n temp-monitor -d "widget"  # Too short

3. Dependency Management

npm install - Automatic:

bash

xcons widget create -n my-widget
# "Do you want to run npm install now?" → Yes (recommended)

Manual - For CI/CD:

bash

xcons widget create -n my-widget --no-interaction
cd my-widget
npm ci  # For CI/CD environments

4. IDE Selection

VS Code users:

bash

xcons widget create -n my-widget
code my-widget
# .vscode/launch.json loads automatically

IntelliJ IDEA users:

bash

xcons widget create -n my-widget
idea my-widget
# .idea/ configuration loads automatically

Command Output

Successful Creation

bash

$ xcons widget create -n temperature-monitor

Creating widget project...
Downloading and extracting template from GitHub...
  Downloading ZIP file...
  Extracting files directly to widget directory...
Template downloaded and extracted successfully
Creating .xcon configuration...
.xcon/config.json created successfully
Updating .idea configuration files...
  Renamed xcon-web-cli.iml to temperature-monitor.iml
  Updated modules.xml to reference temperature-monitor.iml
  Cleared PropertiesComponent and RecentsManager in workspace.xml
.idea configuration files updated successfully
Widget project 'temperature-monitor' created successfully!
Location: /Users/dev/projects/temperature-monitor

? Do you want to run npm install now? Yes
Running npm install...
npm install completed successfully

Next steps:
cd temperature-monitor
npm run build
Develop your widget

Non-Interactive Mode Output

bash

$ xcons widget create -n my-widget --no-interaction

Creating widget project...
Downloading and extracting template from GitHub...
Template downloaded and extracted successfully
Creating .xcon configuration...
.xcon/config.json created successfully
Updating .idea configuration files...
.idea configuration files updated successfully
Widget project 'my-widget' created successfully!
Location: /Users/dev/projects/my-widget
  Skipping npm install due to --no-interaction flag

Next steps:
cd my-widget
npm install
npm run build
Develop your widget

Frequently Asked Questions

Q: Can I change the widget name later? A: Yes, but manually:

Change directory name
Update package.json name field
Update .xcon/config.json id field
Rename .idea/*.iml file
Update .idea/modules.xml references

Q: I skipped npm install, how do I install later? A: Go to the project directory and run npm install:

bash

cd my-widget
npm install

Q: Can I customize the template? A: Yes, you can fork from GitHub and use your own template:

bash

# Your own template URL
# (requires CLI code modification)

Q: Which IDE should I use? A:

VS Code: Lightweight, fast, extension support
IntelliJ IDEA/WebStorm: Powerful refactoring, TypeScript support
Both are automatically configured

Q: Why are the provider and id fields in .xcon/config.json empty? A: The developer should decide which platform (web/thingsboard) to create the widget for and make the appropriate settings.

Next Steps

After creating the widget:

Widget Build - Compile the widget
Web Configuration - Customize configuration

Widget creation ready! You can start developing.

bash

xcons widget create -n my-awesome-widget
cd my-awesome-widget
npm run dev

Web Widget Create ​

Overview ​

Command Syntax ​

Options ​

Usage Examples ​

1. Interactive Mode (Recommended) ​

2. With Name Parameter ​

3. Fully Parameterized ​

4. Non-Interactive Mode ​

5. Directly with NPX ​

Generated Project Structure ​

Directory Structure ​

Auto-Generated Files ​

1. .xcon/config.json ​

2. package.json ​

3. VS Code Launch Configuration (.vscode/launch.json) ​

4. IntelliJ IDEA Configuration ​

Workflow ​

1. Widget Creation ​

2. Installing Dependencies ​

3. Development ​

4. Build ​

5. Deploy ​

Configuration Steps ​

1. Setting Provider ​

2. Build Settings ​

3. External Libraries ​

IDE Usage ​

VS Code ​

IntelliJ IDEA / WebStorm ​

Custom Scenarios ​

1. Creating Chart Widget ​

2. Creating Map Widget ​

3. Creating Dashboard Widget ​

Troubleshooting ​

Issue: Directory already exists ​

Issue: Template download failed ​

Issue: npm install failed ​

Issue: .idea files not updated ​

Best Practices ​

1. Widget Naming ​

2. Description ​

3. Dependency Management ​

4. IDE Selection ​

Command Output ​

Successful Creation ​

Non-Interactive Mode Output ​

Frequently Asked Questions ​

Next Steps ​

Overview

Command Syntax

Options

Usage Examples

1. Interactive Mode (Recommended)

2. With Name Parameter

3. Fully Parameterized

4. Non-Interactive Mode

5. Directly with NPX

Generated Project Structure

Directory Structure

Auto-Generated Files

1. .xcon/config.json

2. package.json

3. VS Code Launch Configuration (.vscode/launch.json)

4. IntelliJ IDEA Configuration

Workflow

1. Widget Creation

2. Installing Dependencies

3. Development

4. Build

5. Deploy

Configuration Steps

1. Setting Provider

2. Build Settings

3. External Libraries

IDE Usage

VS Code

IntelliJ IDEA / WebStorm

Custom Scenarios

1. Creating Chart Widget

2. Creating Map Widget

3. Creating Dashboard Widget

Troubleshooting

Issue: Directory already exists

Issue: Template download failed

Issue: npm install failed

Issue: .idea files not updated

Best Practices

1. Widget Naming

2. Description

3. Dependency Management

4. IDE Selection

Command Output

Successful Creation

Non-Interactive Mode Output

Frequently Asked Questions

Next Steps