Web Widget Build

Detailed usage guide for widget build command for web platform.

Overview

The xcons web build command compiles, optimizes and prepares web platform TypeScript widget projects for distribution. Using a Webpack-based build system, it converts TypeScript code to JavaScript, processes templates and styles, manages external libraries and adds platform-specific wrappers.

Command Syntax

bash

xcons web build [source] [options]
npx @xcons/cli web build [source] [options]

# Short syntax (web is default)
xcons widget build [source] [options]

Options

Option	Shorthand	Type	Default	Description
`[source]`	-	string	`.` (current dir)	Widget project directory
`--production`	`-p`	flag	false	Production build (minified)
`--debug`	`-d`	flag	false	Show debug output

Usage Examples

1. Build from Current Directory

Simplest usage - in the root directory of the widget project:

bash

cd my-widget
xcons web build

Output:

Building widget...
Project directory: /Users/dev/my-widget
  ✓ Valid XCon widget project
  Widget Type: latest
  Provider: web
  Entry: widget.ts
  Output: widget.js

Build options:
  Production: false
  Debug: false

[BUILD] Starting widget build process...
[BUILD] Reading project configuration...
[BUILD] Processing widget with XCon Widget Processor Plugin...
[WIDGET] Processing widget file: /Users/dev/my-widget/src/widget.ts
[WIDGET] Using web wrapper
[PACK] Checking dependencies...
[PACK] All dependencies are already installed
[PACK] Build successful
[PACK] Compiled 5 TypeScript modules
[WIDGET] Applying web wrapper to built widget...
[WIDGET] Widget processing completed successfully
Build completed successfully!
Output: /Users/dev/my-widget/dist/widget.js (45.23 KB)
Build time: 3542ms

2. Production Build

Minified and optimized build:

bash

xcons web build --production

Output:

Building widget...
Project directory: /Users/dev/my-widget

Build options:
  Production: true
  Debug: false

[BUILD] Starting widget build process...
[PACK] Build successful
[WIDGET] Widget processing completed successfully
Build completed successfully!
Output: /Users/dev/my-widget/dist/widget.min.js (12.45 KB)
Build time: 4821ms

Production optimizations:

Minification with Terser
Dead code elimination
Tree shaking
Console.log removal
No source map

3. Debug Build

Build with detailed output:

bash

xcons web build --debug

Output:

Building widget...
Project directory: /Users/dev/my-widget

Project Status:
  ✓ Valid XCon widget project
  Widget Type: latest
  ✓ Entry file exists
  ✓ External libraries configured
    External libraries will be loaded from global scope at runtime
  ⚠ Output file not found (run build first)

Build options:
  Production: false
  Debug: true

[BUILD] Starting widget build process...
[BUILD] Project information:
[BUILD] Widget Type: latest
[BUILD] Provider: web
[BUILD] Entry: widget.ts
[BUILD] Output: widget.js
[BUILD] External Libraries: configured
[XCON-LOADER] Processing: widget.ts
[XCON-LOADER] Replacing templateUrl with template (523 chars)
[XCON-LOADER] Replacing styleUrls with styles (1247 chars)
[XCON-LOADER] Processing resources
[XCON-LOADER] Final resources count: 3
[PACK] Build successful
[PACK] Processed 5 TypeScript modules
[PACK] External modules processed: 2
[BUILD] Build time: 3542ms
[BUILD] Output size: 45.23 KB

4. Build from Specific Directory

Building widget from a different directory:

bash

xcons web build ./my-widget --production

bash

# Or absolute path
xcons web build /Users/dev/projects/my-widget

5. Build with NPX

Without global installation:

bash

npx @xcons/cli web build --production

6. Production + Debug

Both production and detailed output:

bash

xcons web build --production --debug

Detailed Steps

1. Validation

bash

[BUILD] Starting widget build process...
[BUILD] Validating project directory...
[BUILD] Checking .xcon/config.json...

Checked:

.xcon/config.json existence
Provider: must be "web"
Entry file existence
Build configuration

2. XCon Webpack Loader

bash

[XCON-LOADER] Processing: widget.ts
[XCON-LOADER] Replacing templateUrl with template (523 chars)
[XCON-LOADER] Replacing styleUrls with styles (1247 chars)

Operations:

templateUrl → template:

typescript

// Before
@Widget({
  templateUrl: './widget.html'
})

// After (automatic)
@Widget({
  template: "<div class=\"widget-container\"><h1>{{title}}</h1></div>"
})

styleUrls → styles:

typescript

// Before
@Widget({
  styleUrls: ['./widget.css']
})

// After (automatic)
@Widget({
  styles: [".widget-container{padding:10px;background:#fff}"]
})

3. Resources Processing

bash

[XCON-LOADER] Processing resources
[XCON-LOADER] Final resources count: 3

Automatically added XCONS libraries:

typescript

resources: [
  {
    id: "xcons-common",
    name: "XCONS Common Library",
    type: "js",
    extension: true,
    url: "https://unpkg.com/@xcons/common@latest/core.js",
    order: 1
  },
  {
    id: "xcons-widget",
    name: "XCONS Widget Core Library",
    type: "js",
    extension: true,
    url: "https://unpkg.com/@xcons/widget@latest/core.js",
    order: 2
  }
]

4. External Library Handling

bash

[PACK] External modules processed: 2

.xcon/config.json:

json

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

Webpack output:

javascript

// lodash NOT INCLUDED in bundle
// Expected as window._ at runtime

Configuration

Build Configuration (.xcon/config.json)

Minimal Web Build Config

json

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

Production Build Config

json

{
  "configurations": {
    "provider": "web",
    "id": "production-widget"
  },
  "build": {
    "debug": false,
    "entry": "widget.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.min.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json",
    "externals": {
      "@xcons/common": "XConsCommon",
      "@xcons/widget": "XConWidgetCore",
      "lodash": "_",
      "chart.js": "Chart"
    }
  },
  "projectType": "widget",
  "version": "1.0"
}

Development Build Config

json

{
  "configurations": {
    "provider": "web",
    "id": "dev-widget"
  },
  "build": {
    "debug": true,
    "entry": "widget.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json"
  },
  "projectType": "widget",
  "version": "1.0"
}

External Library Management

Include in Bundle (Default)

Config (NO external):

json

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

Build output:

widget.min.js → ~70KB (including lodash)

Mark as External

Config:

json

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

Build output:

widget.min.js → ~5KB (EXCLUDING lodash)

Multiple External Libraries

json

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

Build Output

Development Build

File structure:

my-widget/
├── dist/
│   ├── widget.js              # Development build (~45 KB)
│   └── widget.js.map          # Source map (optional)

Features:

Readable code
Console.log preserved
Easy debugging
Source map available (optional)

Production Build

File structure:

my-widget/
├── dist/
│   └── widget.min.js          # Production build (~12 KB)

Features:

Minified code
Console.log removed
Dead code eliminated
No source map

Build Output Comparison

Feature	Development	Production
File name	widget.js	widget.min.js
Size	~45 KB	~12 KB
Minified	✗	✓
Source Map	✓	✗
Console.log	✓	✗
Debug Info	✓	✗
Build Time	~3s	~5s

Debugging

Build Errors

Entry File Not Found

Error:

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

Solution 1 - Check file path:

bash

ls -la src/widget.ts

Solution 2 - Check config:

json

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

TypeScript Compilation Error

Error:

[PACK] Webpack build errors:
  - TS2307: Cannot find module 'lodash'

Solution - npm install:

bash

npm install lodash
npm install --save-dev @types/lodash

External Library Undefined

Error (Runtime):

ReferenceError: _ is not defined

Solution 1 - Define resources:

typescript

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

Solution 2 - Check global variable:

json

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

Webpack Memory Error

Error:

FATAL ERROR: Ineffective mark-compacts near heap limit

Solution:

bash

# Increase memory limit
NODE_OPTIONS="--max-old-space-size=4096" xcons web build

Missing Dependencies

Error:

[PACK] Installing missing dependencies: webpack, ts-loader, terser

Automatic solution: CLI automatically installs missing dependencies.

Manual solution:

bash

npm install --save-dev webpack webpack-cli ts-loader terser terser-webpack-plugin reflect-metadata

Build Validation

Pre-Build Checks

bash

xcons web build --debug

Checked:

[x] .xcon/config.json existence
[x] Provider: "web"
[x] Entry file existence
[x] TypeScript config
[x] npm dependencies
[x] Output directory writable

Post-Build Validation

Runtime test:

html

<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/@xcons/common@latest/core.js"></script>
  <script src="https://unpkg.com/@xcons/widget@latest/core.js"></script>
  <script src="dist/widget.min.js"></script>
</head>
<body>
  <div id="widget-container"></div>
  <script>
    // Widget test
    console.log('Widget loaded:', typeof XConWidget);
  </script>
</body>
</html>

Best Practices

1. Build Workflow

Development cycle:

bash

# Initial build
xcons web build

# After code changes
xcons web build

# Production test
xcons web build --production

# Deploy
# Upload dist/widget.min.js file to platform

2. External Library Strategy

Use external for large libraries:

json

{
  "build": {
    "externals": {
      "chart.js": "Chart",    // ~200KB
      "moment": "moment",      // ~70KB
      "lodash": "_"            // ~70KB
    }
  }
}

Bundle small utilities:

typescript

// Small (<10KB) utilities can be included in bundle
import { debounce } from './utils/debounce';  // Included in bundle

3. Build Environment

package.json scripts:

json

{
  "scripts": {
    "dev": "vite",
    "build": "xcons web build",
    "build:prod": "xcons web build --production",
    "build:debug": "xcons web build --debug"
  }
}

Performance Tips

1. Build Speed Optimization

TypeScript transpileOnly:

json

// tsconfig.json
{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

Webpack cache: Build system automatically uses cache.

2. Bundle Size Reduction

Checklist:

[x] Use external libraries
[x] Make production build
[x] Remove unnecessary imports
[x] Tree shaking enabled
[x] Dead code elimination

3. Build Time Comparison

Development Build:  ~3 seconds
Production Build:   ~5 seconds
With --debug:       ~4 seconds

Troubleshooting

Build Too Slow

Problem: Build takes 30+ seconds

Solution 1 - Clear cache:

bash

npm cache clean --force
rm -rf node_modules
npm install

Solution 2 - Increase memory:

bash

NODE_OPTIONS="--max-old-space-size=4096" xcons web build

Output File Too Large

Problem: widget.min.js > 500KB

Solution - External libraries:

json

{
  "build": {
    "externals": {
      "@xcons/common": "XConsCommon",
      "@xcons/widget": "XConWidgetCore",
      "lodash": "_"
    }
  }
}

Problem: Widget uploaded to platform but not working

Checklist:

Is provider correct? ("web")
Are resources defined?
Are external libraries loading?
Are there errors in console?

Debug:

bash

# Make debug build
xcons web build --debug

# Check console
# Browser DevTools → Console

Command Output Examples

Successful Build (Development)

bash

$ xcons web build

Building widget...
Project directory: /Users/dev/my-widget
  ✓ Valid XCon widget project
  Widget Type: latest
  Provider: web
  Entry: widget.ts
  Output: widget.js

Build options:
  Production: false
  Debug: false

[BUILD] Starting widget build process...
[BUILD] Reading project configuration...
[WIDGET] Processing widget file: /Users/dev/my-widget/src/widget.ts
[WIDGET] Using web wrapper
[PACK] Build successful
[PACK] Compiled 5 TypeScript modules
[WIDGET] Widget processing completed successfully

Build completed successfully!
Output: /Users/dev/my-widget/dist/widget.js (45.23 KB)
Build time: 3542ms
Processed files: Multiple TypeScript files with decorators
Data injection: Styles, templates, resources, and metadata injected into bundle

Successful Build (Production)

bash

$ xcons web build --production

Building widget...
Project directory: /Users/dev/my-widget

Build options:
  Production: true
  Debug: false

[BUILD] Starting widget build process...
[PACK] Build successful
[WIDGET] Widget processing completed successfully

Build completed successfully!
Output: /Users/dev/my-widget/dist/widget.min.js (12.45 KB)
Build time: 4821ms

Failed Build

bash

$ xcons web build

Building widget...
Project directory: /Users/dev/my-widget

Build requirements not met:
  - Entry file not found: src/widget.ts

Widget build failed:
  Build requirements not satisfied

Frequently Asked Questions

Q: Does build recompile all code every time? A: No, Webpack uses a cache system. Only changed files are recompiled.

Q: What is the difference between production and development build? A: Production build is minified, optimized and without console.log. Development build is readable for debugging.

Q: How to add external library? A: Add to build.externals in .xcon/config.json file and define resources in widget.

Q: Where is the build output? A: In the build.outputPath folder in .xcon/config.json file (default: dist/).

Q: How can I see TypeScript errors? A: Use the --debug flag: xcons web build --debug

Q: Can widget consist of multiple files? A: Yes, webpack automatically includes all imports in the bundle.

Web widget build is ready! You can deploy.

Web Widget Build ​

Overview ​

Command Syntax ​

Options ​

Usage Examples ​

1. Build from Current Directory ​

2. Production Build ​

3. Debug Build ​

4. Build from Specific Directory ​

5. Build with NPX ​

6. Production + Debug ​

Detailed Steps ​

1. Validation ​

2. XCon Webpack Loader ​

3. Resources Processing ​

4. External Library Handling ​

Configuration ​

Build Configuration (.xcon/config.json) ​

Minimal Web Build Config ​

Production Build Config ​

Development Build Config ​

External Library Management ​

Include in Bundle (Default) ​

Mark as External ​

Multiple External Libraries ​

Build Output ​

Development Build ​

Production Build ​

Build Output Comparison ​

Debugging ​

Build Errors ​

Entry File Not Found ​

TypeScript Compilation Error ​

External Library Undefined ​

Webpack Memory Error ​

Missing Dependencies ​

Build Validation ​

Pre-Build Checks ​

Post-Build Validation ​

Best Practices ​

1. Build Workflow ​

2. External Library Strategy ​

3. Build Environment ​

Performance Tips ​

1. Build Speed Optimization ​

2. Bundle Size Reduction ​

3. Build Time Comparison ​

Troubleshooting ​

Build Too Slow ​

Output File Too Large ​

Widget Not Working at Runtime ​

Command Output Examples ​

Successful Build (Development) ​

Successful Build (Production) ​

Failed Build ​

Frequently Asked Questions ​

Overview

Command Syntax

Options

Usage Examples

1. Build from Current Directory

2. Production Build

3. Debug Build

4. Build from Specific Directory

5. Build with NPX

6. Production + Debug

Detailed Steps

1. Validation

2. XCon Webpack Loader

3. Resources Processing

4. External Library Handling

Configuration

Build Configuration (.xcon/config.json)

Minimal Web Build Config

Production Build Config

Development Build Config

External Library Management

Include in Bundle (Default)

Mark as External

Multiple External Libraries

Build Output

Development Build

Production Build

Build Output Comparison

Debugging

Build Errors

Entry File Not Found

TypeScript Compilation Error

External Library Undefined

Webpack Memory Error

Missing Dependencies

Build Validation

Pre-Build Checks

Post-Build Validation

Best Practices

1. Build Workflow

2. External Library Strategy

3. Build Environment

Performance Tips

1. Build Speed Optimization

2. Bundle Size Reduction

3. Build Time Comparison

Troubleshooting

Build Too Slow

Output File Too Large

Widget Not Working at Runtime

Command Output Examples

Successful Build (Development)

Successful Build (Production)

Failed Build

Frequently Asked Questions