@xcons/cli

XCON Widget Project Generator - Command line tool for platform-independent widget development. Create and build widget projects with full IDE support (VS Code, WebStorm/IntelliJ IDEA, Visual Studio) for any target platform in TypeScript and .NET environments.

Overview

XCON CLI is a comprehensive project creation and build tool that provides a platform-independent widget development experience. Develop widgets that work on multiple platforms with a single codebase. It supports TypeScript and .NET environments, offering automatic project configurations, full IDE support (VS Code, WebStorm/IntelliJ IDEA and Visual Studio), modern build tools, and platform-specific automatic wrapper generation features.

Platform Independence

XCON CLI is designed with the "write once, run everywhere" philosophy:

• Single Codebase: Develop your widget once
• Multiple Platforms: The same code runs on different platforms
• Automatic Wrapper: Required integration code is automatically added for each platform
• Flexible Deployment: Platform-specific optimizations as needed
• Extensible: Support for new platforms can be easily added

Supported Platforms

Currently supported target platforms:

• Web: For general web applications
• ThingsBoard: Custom integration for IoT platform

Features

Core Features

• Platform-Independent Development: Multi-platform support with a single codebase
• Multi-Language Support: TypeScript and .NET widget development
• Automatic Platform Wrappers: Automatic integration code for target platform
• Smart Build System: Webpack-based optimization with TypeScript support
• Full IDE Integration: Ready configurations for VS Code, WebStorm/IntelliJ IDEA and Visual Studio 2022
• Resource Management: Automatic processing of templates, styles, and external resources
• External Library Support: External library configuration with webpack externals
• Development Server: Live development with hot reload feature
• Production Optimization: Minification and optimization

Installation

# Direct usage with npx (recommended)
npx @xcons/cli widget create my-widget

# Or global installation
npm install -g @xcons/cli
xcons widget create my-widget

Usage

TypeScript Widget Projects

Creating a New Widget Project

# Create widget project with Q&A
npx @xcons/cli widget create

# Create with specific name
npx @xcons/cli widget create my-awesome-widget

# Skip interactive questions
npx @xcons/cli widget create my-widget --no-interaction

# Skip interactive questions + auto run npm install
npx @xcons/cli widget create my-widget --no-interaction --npm

Building Widget Project

# Build in development mode
npx @xcons/cli widget build

# Build for production
npx @xcons/cli widget build --production

# Build with debug output
npx @xcons/cli widget build --debug

# Build specific directory
npx @xcons/cli widget build ./my-widget-source

Platform-Specific Commands

Web Platform

# Create web widget
npx @xcons/cli web create my-web-widget

# Skip interactive questions + auto run npm install
npx @xcons/cli web create my-web-widget --no-interaction --npm

# Build web widget
npx @xcons/cli web build
npx @xcons/cli web build --production

ThingsBoard Platform

# Create ThingsBoard widget
npx @xcons/cli thingsboard create my-tb-widget

# Skip interactive questions + auto run npm install
npx @xcons/cli thingsboard create my-tb-widget --no-interaction --npm

# Build ThingsBoard widget
npx @xcons/cli thingsboard build
npx @xcons/cli thingsboard build --production

.NET Projects

Creating a New .NET Project

# Create .NET project with Q&A
npx @xcons/cli dotnet create

# Create with specific name
npx @xcons/cli dotnet create my-dotnet-widget

# Skip interactive questions
npx @xcons/cli dotnet create my-widget --no-interaction

# Skip interactive questions + auto run npm install
npx @xcons/cli dotnet create my-widget --no-interaction --npm

# Skip interactive questions + auto run dotnet restore
npx @xcons/cli dotnet create my-widget --no-interaction --dotnet

# Skip interactive questions + auto run both npm and dotnet
npx @xcons/cli dotnet create my-widget --no-interaction --npm --dotnet

Publishing .NET Project

.NET projects are published within Visual Studio:

• Open the solution in Visual Studio
• Right-click on the project and select "Publish"
• Configure the publish profile and publish

Alternatively from command line:

dotnet publish -c Release

Project Structure

TypeScript Widget Structure

my-widget/
├── src/
│   ├── widget.ts          # Main widget logic
│   ├── widget.html        # Widget template
│   └── widget.css         # Widget styles
├── .xcon/
│   └── config.json        # XCON configuration
├── .idea/                 # WebStorm/IntelliJ configuration
├── .vscode/               # VS Code configuration
├── webpack.config.js      # Webpack configuration
├── package.json
├── tsconfig.json
└── README.md

.NET Project Structure

my-dotnet-widget/
├── my-dotnet-widget/      # .NET project folder
│   ├── Controllers/       # API controllers
│   ├── Services/          # Business logic
│   ├── wwwroot/          # Static files
│   ├── .xcon/
│   │   └── config.json   # XCON configuration
│   ├── Program.cs
│   ├── package.json      # Node dependencies
│   └── my-dotnet-widget.csproj
├── .idea/                 # WebStorm/IntelliJ configuration (optional)
├── .vs/                   # Visual Studio configuration (optional)
├── my-dotnet-widget.sln   # Solution file
└── README.md

Configuration

XCON Configuration (.xcon/config.json)

The build system reads widget configuration using the .xcon/config.json file:

{
  "configurations": {
    "provider": "web",  // or "thingsboard" or another platform
    "id": "unique-widget-id",
    "type": "widget-type"
  },
  "build": {
    "entry": "widget.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json",
    "externals": {
      "rxjs": "rxjs",
      "lodash": "_"
    }
  },
  "projectType": "widget",
  "version": "1.0"
}

Build Features

Resource Injection

The build system automatically:

• Processes HTML templates
• Processes CSS styles
• Processes and includes widget resources
• Automatically adds required XCONS libraries

External Libraries

Configure external libraries in the .xcon/config.json file:

{
  "build": {
    "externals": {
      "library-name": "globalVariableName"
    }
  }
}

Platform Wrappers

The build system automatically wraps the widget according to the target platform:

• Special lifecycle methods are added for each platform
• Platform context and integration code are automatically generated
• Platform-specific optimizations are applied

Command Options

Create Commands

| Option | Description | Default | |--------|-------------|---------| | -n, --name <name> | Widget project name | Interactive question | | -d, --description <desc> | Widget description | Generated from name | | --no-interaction | Skip all interactive questions | false | | --npm | Auto run npm install without asking | false | | --dotnet | Auto run dotnet restore without asking (for .NET projects) | false |

Important Notes:

• --npm and --dotnet flags should be used with --no-interaction
• When --no-interaction is used alone, no dependency installation occurs
• --npm flag can be used for all project types (web, thingsboard, dotnet)
• --dotnet flag is only applicable for .NET projects

Build Commands

| Option | Description | Default | |--------|-------------|---------| | -p, --production | Build for production (minified) | false | | -d, --debug | Show debug output during build | false |

Development Workflow

TypeScript Widget Development

1. Create Project

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

2. Install Dependencies

   npm install

3. Configure Widget

   • Edit the .xcon/config.json file
   • Set the provider value according to your target platform
   • Configure external libraries if needed

4. Develop Widget

   • Edit source files in the src/ directory
   • Use the @Widget decorator for widget configuration
   • Templates and styles are automatically inlined

5. Build Widget

   npm run build
   # or for production
   npx @xcons/cli widget build --production

6. Deploy

   • Find the compiled widget in the dist/ directory
   • Upload to your target platform

.NET Widget Development

1. Create Project

   npx @xcons/cli dotnet create my-dotnet-widget
   cd my-dotnet-widget

2. Install Dependencies

   cd my-dotnet-widget
   npm install
   dotnet restore

3. Develop

   • Open the .sln file in Visual Studio
   • Edit .NET code in the project directory
   • Frontend assets in wwwroot/ directory
   • Alternatively, you can use VS Code or JetBrains Rider

4. Publish

   With Visual Studio:

   • Right-click on the project in Solution Explorer
   • Select "Publish" option
   • Configure the publish profile
   • Click the "Publish" button

   With command line:

   dotnet publish -c Release

IDE Support

VS Code

CLI creates complete VS Code workspace configuration:

• Debug configurations (debug with F5)
• Build tasks
• Extension recommendations
• Optimized settings

WebStorm/IntelliJ IDEA

Full IDE project setup:

• Run/Debug configurations
• Code style settings
• Inspection profiles
• File watchers

Visual Studio

Full integration for .NET projects:

• Solution and project files
• Debug configurations
• NuGet package management
• Build and publish profiles

Requirements

• Node.js 18+
• NPM 9+
• .NET SDK 6.0+ (for .NET widgets)
• IDE (optional): VS Code, WebStorm/IntelliJ IDEA or Visual Studio
• Modern browser for development

Troubleshooting

Build Errors

If you get a build error:

1. Check that the .xcon/config.json file is configured correctly
2. Make sure all dependencies are installed: npm install
3. Verify that the entry file is at the configured path
4. Use the --debug flag for detailed output

Missing Dependencies

The build system automatically installs required webpack dependencies:

• webpack
• webpack-cli
• ts-loader
• terser-webpack-plugin
• reflect-metadata

External Libraries Not Working

Make sure external libraries are:

1. Listed under build.externals in the .xcon/config.json file
2. Available in the global scope at runtime
3. Correctly mapped to global variable names

📄 License

MIT License - see LICENSE file for details.

XCon Studio Team | 🌐 Documentation

Made with ❤️ by XCon Studio Team