XCon Studio

Appearance

@xcons/cli - Installation Guide ​

Installation steps and configuration options for the XCONS CLI tool.

System Requirements ​

Minimum Requirements ​

  • Node.js: 18.0.0 or higher
  • NPM: 9.0.0 or higher
  • Modern web browser (for development)

Platform Compatibility ​

  • Windows: 10/11 (PowerShell support)
  • macOS: 10.15 and above
  • Linux: Ubuntu 18.04+, CentOS 7+, other distributions

Installation Methods ​

1. Direct Usage with NPX (Recommended) ​

Run directly without global installation:

bash
# Widget creation
npx @xcons/cli widget create my-widget

# .NET Widget creation
npx @xcons/cli dotnet create my-dotnet-widget

# Interactive mode (name is asked)
npx @xcons/cli widget create

# Non-interactive mode
npx @xcons/cli widget create simple-widget --no-interaction

Advantages:

  • Always uses the latest version
  • Does not require global installation
  • Saves disk space

2. Global Installation ​

Global installation for frequent use:

bash
# Global installation
npm install -g @xcons/cli

# Verify installation
xcons --version

# Use commands directly
xcons widget create my-widget
xcons dotnet create my-dotnet-widget

Advantages:

  • Fast command access
  • Easier IDE integration

Installation Issues and Solutions ​

Node.js Version Issue ​

Problem: Engine node is incompatible with this module

Solution:

bash
# Check Node.js version
node --version  # Should be 18.0.0+

# Update:
# Windows/macOS: Download from nodejs.org
# Linux Ubuntu/Debian:
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

NPM Permission Issue (Linux/macOS) ​

Problem: EACCES: permission denied

Solution 1 - NPM configuration (Recommended):

bash
# Change NPM global directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Global installation
npm install -g @xcons/cli

Solution 2 - Use NPX:

bash
# Use npx instead of global installation
npx @xcons/cli widget create my-widget

Template Download Issues ​

Problem: Failed to download template: ETIMEDOUT

Solution:

bash
# Check network 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
npx @xcons/cli widget create my-widget

Windows PowerShell Execution Policy ​

Problem: cannot be loaded because running scripts is disabled

Solution:

powershell
# Open PowerShell as administrator
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# Try installation again
npm install -g @xcons/cli

Widget Development Workflow ​

TypeScript Widget ​

bash
# 1. Create widget
xcons widget create temperature-monitor

# 2. Navigate to directory
cd temperature-monitor

# 3. Start development
npm run dev  # http://localhost:4201

# 4. Edit code
# src/widget.ts - Widget logic
# src/widget.html - Template
# src/widget.css - Styles

# 5. Production build
npm run build  # dist/widget.min.js

.NET Widget ​

bash
# 1. Create .NET widget
xcons dotnet create dashboard-widget

# 2. Navigate to directory
cd dashboard-widget

# 3. Install dependencies (automatically asked)
dotnet restore
npm install

# 4. Start development
npm run dev

# 5. Edit code
# dashboard-widget/src/widget.ts
# dashboard-widget/Controllers/
# dashboard-widget/Models/

# 6. Production build
npm run build

IDE Integration ​

Visual Studio Code ​

When you create a widget, the .vscode/ folder is automatically created:

my-widget/
├── .vscode/
│   ├── launch.json      # Debug configuration
│   ├── tasks.json       # Build tasks
│   └── extensions.json  # Recommended extensions

Usage:

  • F5 - Start debug
  • Ctrl+Shift+B - Run build task

IntelliJ IDEA / WebStorm ​

The .idea/ folder is automatically created:

my-widget/
├── .idea/
│   ├── workspace.xml    # Workspace settings
│   ├── modules.xml      # Module configuration
│   └── my-widget.iml    # Project file

Usage:

  • Run/Debug Configurations come ready
  • Shift+F10 - Run
  • Shift+F9 - Debug

Visual Studio 2022 (.NET Widgets) ​

You can open .NET widgets directly with Visual Studio 2022:

my-dotnet-widget/
├── my-dotnet-widget.sln     # Solution file
├── my-dotnet-widget/
│   ├── my-dotnet-widget.csproj
│   └── .xcon/config.json

Build System ​

Webpack Configuration ​

Widget build includes these steps:

  1. TypeScript Compilation - TypeScript → JavaScript
  2. XCon Webpack Loader - Template, style and resource injection
  3. Webpack Bundling - Optimized bundle
  4. Platform Wrapper - Adding ThingsBoard/Web wrapper
  5. Minification - Optimization with Terser

External Libraries ​

Define external libraries in .xcon/config.json file:

json
{
  "build": {
    "externals": {
      "lodash": "_",
      "moment": "moment"
    }
  }
}

These libraries are not included in the bundle, they are loaded from global scope at runtime.

Update ​

Global Installation Update ​

bash
# Check current version
xcons --version

# Update to latest version
npm update -g @xcons/cli

# Or reinstall
npm install -g @xcons/cli@latest

NPX Automatic Update ​

NPX always uses the latest version:

bash
# Always latest version
npx @xcons/cli@latest widget create my-widget

Uninstall ​

bash
# Uninstall global package
npm uninstall -g @xcons/cli

# Clear cache
npm cache clean --force

Performance Tips ​

Node.js Memory Settings ​

Increase memory limit for large projects:

bash
# Linux/macOS - ~/.bashrc
export NODE_OPTIONS="--max-old-space-size=4096"

# Windows - Environment Variables
NODE_OPTIONS=--max-old-space-size=4096

# Temporary usage
NODE_OPTIONS="--max-old-space-size=4096" xcons widget build

NPM Cache ​

bash
# Check cache size
npm cache verify

# Move cache directory to SSD
npm config set cache /path/to/fast/storage/.npm

Frequently Used Commands ​

bash
# Widget creation
xcons widget create my-widget
xcons dotnet create my-dotnet-widget

# Build commands
xcons widget build                     # Development build
xcons widget build --production        # Production build
xcons widget build --debug            # Debug output
xcons widget build ./path --production # Specific directory

# Help
xcons --help
xcons widget --help
xcons dotnet --help

Troubleshooting ​

Widget Creation Issues ​

Problem: Directory 'my-widget' already exists

bash
# Delete existing directory
rm -rf my-widget

# Or use different name
xcons widget create my-widget-v2

Port Conflict ​

Problem: Port 4201 is already in use

bash
# Find and kill process using port
lsof -ti:4201 | xargs kill -9

# Different port is automatically used
npm run dev

Build Errors ​

Problem: Build failed: Entry file not found

bash
# Check .xcon/config.json file
cat .xcon/config.json

# Check entry file existence
ls -la src/widget.ts

# Check build requirements
xcons widget build --debug

Next Steps ​

After installation is complete:

  1. Create First Widget - xcons widget create my-first-widget
  2. Start Development - cd my-first-widget && npm run dev
  3. Develop Widget - Edit files in src/ folder
  4. Build - npm run build
  5. Deploy - Upload dist/widget.min.js file to platform

Installation complete! You can start developing widgets.