XCon Studio Vite Plugin

XCon Studio Vite Plugin is a Vite plugin designed to improve the debug and development experience during widget development. It automatically processes HTML templates, CSS style files, and resources to provide fast feedback during development.

⚠️ Note: This plugin is only used for development/debug purposes. A separate build system is used for production builds.

🚀 Installation

# with npm (as development dependency)
npm install @xcons/vite-plugin --save-dev

# with yarn  
yarn add @xcons/vite-plugin --dev

# with pnpm
pnpm add @xcons/vite-plugin --save-dev

🎯 Development Usage

Vite Configuration (For Debug)

// vite.config.js - Debug/Development configuration
import { defineConfig } from 'vite';
import { xconVitePlugin } from '@xcons/vite-plugin';

export default defineConfig({
    plugins: [
        xconVitePlugin({
            // Optimized settings for debug
            minifyTemplates: false,      // Minification off during debug
            minifyStyles: false,         // Keep CSS readable
            sourceMap: true,             // Source maps active for debug
            showProcessedFiles: true,    // Show processed files
            logger: {
                logLevel: 'debug'          // Detailed logs
            },
            watchFiles: true             // Watch file changes
        })
    ],
    server: {
        port: 4201,                    // Development server port
        open: true                     // Auto-open browser
    }
});

TypeScript Configuration (Debug)

// vite.config.ts - TypeScript configuration for debug
import { defineConfig } from 'vite';
import { xconVitePlugin, XConVitePluginOptions } from '@xcons/vite-plugin';

const debugOptions: XConVitePluginOptions = {
    // Debug-friendly settings
    minifyTemplates: false,
    minifyStyles: false,
    removeComments: false,         // Keep comments during debug
    preserveWhitespace: true,      // Preserve whitespaces
    sourceMap: true,               // Source maps active

    // Detailed logging
    logger: {
        logLevel: 'debug'
    },
    showProcessedFiles: true,

    // Development optimizations
    watchFiles: true,              // File watching for HMR
    development: true              // Development mode
};

export default defineConfig({
    plugins: [
        xconVitePlugin(debugOptions)
    ],
    server: {
        port: 4201,
        host: true,                  // For network access
        open: '/index.html'          // Open test page
    }
});

🗃️ Debug Features

1. Template Debug Processing

During development, templates are processed in a readable format:

Widget (widget.ts):

@Widget({
    selector: 'my-widget',
    templateUrl: './widget.html',
    styleUrls: ['./widget.css']
})
export class MyWidget {
    // Widget implementation
}

Debug output (Minification off):

@Widget({
    selector: 'my-widget',
    template: `
    <div class="widget-container" x:class:active="isActive">
      <h1 x:text="title">My Widget</h1>
      <p x:text="'Current count: ' + count">Count display</p>
      <button x:on:click="increment" x:attr:disabled="count >= 10">Increment</button>
      <button x:on:click="reset">Reset</button>
      <!-- XCon bindings preserved for debugging -->
      <div class="debug-info">
        <span x:text="'Debug: Active=' + isActive"></span>
      </div>
    </div>
  `,
    styles: [`
    .widget-container {
      padding: 20px;
      background-color: #f5f5f5;
      border-radius: 8px;
      transition: all 0.3s ease;
    }
    .widget-container.active {
      background-color: #e3f2fd;
      border: 2px solid #2196f3;
    }
    .debug-info {
      margin-top: 10px;
      font-size: 12px;
      color: #666;
    }
  `]
})
export class MyWidget {
    // Widget implementation
}

2. Hot Module Replacement (HMR)

Reflects file changes instantly in the development server:

# Template change
[XCon Plugin] 📄 Template changed: ./widget.html
[XCon Plugin] 🔧 Reloading widget: MyWidget

# Style change  
[XCon Plugin] 🎨 Style changed: ./widget.css
[XCon Plugin] 🔧 Hot-reloading styles

3. Debug Logging

Detailed development logs:

export default defineConfig({
  plugins: [
    xconVitePlugin({
      logger: {
        logLevel: 'debug'
      },
      showProcessedFiles: true
    })
  ]
});

Log output:

[XCon Plugin] 🚀 XCon Vite Plugin started (Development Mode)
[XCon Plugin] 🔧 Source maps enabled for debugging
[XCon Plugin] 🔧 File watching enabled for HMR
[XCon Plugin] 📝 Processing: src/components/my-widget/my-widget.ts
[XCon Plugin] 📄 Loaded template: ./widget.html (245 chars)
[XCon Plugin] 🎨 Loaded style: ./widget.css (180 chars)
[XCon Plugin] ✅ Widget processed successfully

⚙️ Debug Configuration Options

Development-Optimized Settings

interface XConVitePluginOptions {
  // Debug settings
  development?: boolean;          // Development mode (default: false)
  sourceMap?: boolean;           // Source maps (default: true)
  preserveWhitespace?: boolean;  // Preserve whitespace (default: false)
  removeComments?: boolean;      // Remove comments (default: true)
  
  // Minification (off for debug)
  minifyTemplates?: boolean;     // Template minification (default: true)
  minifyStyles?: boolean;        // Style minification (default: true)
  useTerser?: boolean;          // Use Terser (default: true)
  
  // Debug logging
  showProcessedFiles?: boolean;  // Show processed files
  logger?: {
    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
  };
  
  // HMR settings
  watchFiles?: boolean;          // File watching (default: true)
}

Debug Configuration Example

// vite.config.ts - Optimized for debug
export default defineConfig({
  plugins: [
    xconVitePlugin({
      // Debug mode
      development: true,
      
      // Turn off minification
      minifyTemplates: false,
      minifyStyles: false,
      useTerser: false,
      
      // Debug settings
      preserveWhitespace: true,
      removeComments: false,
      sourceMap: true,
      
      // Detailed logging
      logger: {
        logLevel: 'debug'
      },
      showProcessedFiles: true,
      
      // HMR
      watchFiles: true
    })
  ],
  
  // Development server settings
  server: {
    port: 4201,
    host: '0.0.0.0',              // Access from all interfaces
    open: true,                   // Auto-open browser
    cors: true                    // CORS support
  },
  
  // Build settings (for debug)
  build: {
    sourcemap: true,              // Source maps
    minify: false,                // Minification off
    target: 'esnext'              // Modern target
  }
});

🗂️ Development File Structure

Supported structure during debug process:

project/
├── src/
│   ├── components/
│   │   ├── my-widget/
│   │   │   ├── my-widget.ts      # Widget class
│   │   │   ├── my-widget.html    # HTML template
│   │   │   ├── my-widget.css     # CSS styles
│   │   │   └── index.ts          # Export
│   │   └── debug-widget/
│   │       ├── debug-widget.ts
│   │       ├── debug-widget.html
│   │       └── debug-widget.scss
│   └── test/
│       └── test-page.html        # Debug test page
├── index.html                    # Main test page
├── vite.config.ts               # Debug configuration
└── package.json

🚀 Development Workflow

1. Starting Development Server

# Start development server
npm run dev

# Or with specific port
npm run dev -- --port 4202

# With network access
npm run dev -- --host

2. Debug Test Page

<!-- index.html - Widget test page -->
<!DOCTYPE html>
<html>
<head>
  <title>XCon Widget Debug</title>
  <style>
    body { font-family: Arial, sans-serif; margin: 20px; }
    .debug-container { border: 1px solid #ccc; padding: 20px; margin: 10px 0; }
    .section { margin: 15px 0; padding: 15px; border: 1px solid #eee; }
    .controls { margin-top: 10px; }
    .controls label { margin-right: 15px; }
    .status-box { 
      padding: 10px; 
      border: 2px solid #ccc; 
      margin: 10px 0;
      transition: all 0.3s;
    }
    .status-box.active { background-color: #e8f5e8; border-color: #4caf50; }
    .status-box.error { background-color: #ffebee; border-color: #f44336; }
    .status-box.loading { background-color: #fff3e0; border-color: #ff9800; }
  </style>
</head>
<body>
  <h1>XCon Widget Debug</h1>
  
  <div class="debug-container">
    <h2>Counter Widget</h2>
    <counter-widget></counter-widget>
  </div>
  
  <div class="debug-container">
    <h2>Binding Examples</h2>
    <binding-example-widget></binding-example-widget>
  </div>
  
  <script type="module" src="/src/main.ts"></script>
</body>
</html>

3. Live Debugging

Instant changes during development:

# Template change detected
[Vite] hmr update /src/components/my-widget/my-widget.html
[XCon Plugin] 📄 Processing template change
[XCon Plugin] 🔧 Widget reloaded: MyWidget

# Style change detected
[Vite] hmr update /src/components/my-widget/my-widget.css  
[XCon Plugin] 🎨 Processing style change
[XCon Plugin] 🔧 Styles updated

🛠 Debug and Troubleshooting

Debug Logging Levels

export default defineConfig({
  plugins: [
    xconVitePlugin({
      logger: {
        logLevel: 'debug'  // Most detailed logs
      }
    })
  ]
});

Debug Log Examples

# Startup
[XCon Plugin] 🚀 XCon Vite Plugin started (Development Mode)
[XCon Plugin] 🔧 Configuration: minify=false, sourceMap=true, watch=true

# File processing
[XCon Plugin] 📝 Processing file: my-widget.ts
[XCon Plugin] 📄 Template found: ./widget.html
[XCon Plugin] 📏 Template size: 245 chars
[XCon Plugin] 🎨 Style found: ./widget.css  
[XCon Plugin] 📏 Style size: 180 chars

# HMR
[XCon Plugin] 👀 Watching: /src/components/my-widget/widget.html
[XCon Plugin] 📄 File changed, reprocessing...
[XCon Plugin] ✅ HMR update completed

Common Debug Issues

1. Template changes not reflecting:

// Make sure watchFiles is active
xconVitePlugin({
  watchFiles: true,
  development: true
})

2. Source maps not working:

// Make sure magic-string is installed
npm install magic-string --save-dev

// Source maps active
xconVitePlugin({
  sourceMap: true
})

3. HMR too slow:

// Exclude unnecessary files
xconVitePlugin({
  excludeFiles: ['*.spec.ts', '*.test.ts', '*.d.ts']
})

🔧 Debug Tools Integration

VS Code Debug Configuration

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Widget in Browser",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:4201",
      "webRoot": "${workspaceFolder}/src",
      "sourceMapPathOverrides": {
        "webpack:///./src/*": "${webRoot}/*"
      }
    }
  ]
}

Browser DevTools

TypeScript debug in browser thanks to source maps:

// Breakpoint in original TypeScript code
@Widget({
  selector: 'my-widget',
  templateUrl: './widget.html'
})
export class MyWidget {
  onClick() {
    debugger; // Stops in browser
    console.log('Debug: Button clicked');
  }
}

⚡ Performance (Development)

HMR Optimization

export default defineConfig({
    plugins: [
        xconVitePlugin({
            // Process only changed files
            watchFiles: true,

            // Exclude large files
            excludeFiles: ['*.spec.ts', '*.test.ts'],

            // Source maps only in debug
            sourceMap: true
        })
    ],

    server: {
        // HMR optimization
        hmr: {
            port: 24678
        }
    }
});

🚫 Production Notes

This plugin is for development only:

// ❌ Don't use in production
export default defineConfig(({ mode }) => ({
    plugins: [
        // Plugin active only in development
        ...(mode === 'development' ? [xconVitePlugin()] : [])
    ]
}));

A separate build system is used for production build (webpack, rollup, etc.).

---

💡 Debug Tip: During development, you can see how widgets are processed by following [XCon Plugin] logs in the browser console. Monitor plugin activities in F12 → Console.