@xcons/vite-plugin

Development environment Vite plugin for XCon Studio widgets created with @xcons/widget package - Provides hot reload, debugging and breakpoint support

⚠️ Important Note

This plugin is designed for development environment only. It should not be used in production builds. The plugin's purpose is to provide:

• 🔥 Hot Module Replacement (HMR) - Auto-refresh on template and style changes
• 🐛 Debugging Support - Advanced debugging with source maps
• 🔍 Breakpoint Support - Set breakpoints in original source files
• ⚡ Fast Development - Instant code change preview

🚀 Quick Start

Requirements

This plugin is developed for widgets created with the @xcons/widget package:

# First install the widget package
npm install @xcons/widget

# Then install the development plugin
npm install @xcons/vite-plugin --save-dev

Basic Usage

vite.config.ts (Development Only)

import { defineConfig } from 'vite';
import xconVitePlugin from '@xcons/vite-plugin';

export default defineConfig({
  plugins: [
    xconVitePlugin({
      // Development settings
      development: true,
      sourceMap: true,          // For debugging
      watchFiles: true,         // For hot reload
      showProcessedFiles: true  // Show processed files
    })
  ]
});

Define Widget with @xcons/widget

import { Widget } from '@xcons/widget';

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

The plugin automatically:

• ✅ templateUrl → template (HTML content inlined)
• ✅ styleUrls → styles (CSS content inlined)
• ✅ Hot Reload - Auto-refresh on file changes
• ✅ Source Maps - Debugging and breakpoint support
• ✅ Watch Mode - Monitors template and style files

✨ Features

🔥 Hot Module Replacement (HMR)

• Template file changes → Auto widget refresh
• Style file changes → Instant style update
• Live preview without page reload

🐛 Advanced Debugging

• Source Maps - Access to original source files
• Breakpoint Support - Breakpoints in HTML/CSS files
• Stack Trace - Detailed stack trace for debugging
• Console Mapping - Logs show original file locations

⚡ Development Features

• 📄 HTML Template Processing - Converts .html files to inline templates
• 🎨 Style Processing - Converts CSS/SCSS/SASS/LESS files to inline styles array
• 🔍 File Watching - Auto-monitors template and style changes
• 🗺️ Source Map Support - Precise source map generation with magic-string
• 🔧 TypeScript Support - Full TypeScript support with strong type checking
• 📦 @xcons/widget Compatibility - Full integration with widget decorators

📋 Configuration Options

Basic Options

interface XConVitePluginOptions {
  // Processing options
  minifyTemplates?: boolean;        // Default: true
  minifyStyles?: boolean;           // Default: true
  removeComments?: boolean;         // Default: true
  watchFiles?: boolean;             // Default: true
  preserveWhitespace?: boolean;     // Default: false

  // Resource options
  resourceBaseUrl?: string;         // Default: ''
  processResources?: boolean;       // Default: true

  // Logging options
  showProcessedFiles?: boolean;     // Default: false
  logger?: Partial<LoggerConfig>;   // Logger configuration

  // File extension options
  fileExtensions?: string[];        // Default: ['.ts', '.js']
  templateExtensions?: string[];    // Default: ['.html']
  styleExtensions?: string[];       // Default: ['.css', '.scss', '.sass', '.less']

  // Minification options
  useTerser?: boolean;              // Default: true
  terserOptions?: TerserOptions;    // Terser configuration

  // Advanced options
  customProcessors?: ProcessorFunction[];
  excludeFiles?: string[];
  includeFiles?: string[];

  // Development options
  development?: boolean;            // Default: false
  sourceMap?: boolean;              // Default: true
}

Example Configurations

Development Environment (Recommended)

import xconVitePlugin from '@xcons/vite-plugin';

export default defineConfig({
  plugins: [
    xconVitePlugin({
      // Development features
      development: true,
      sourceMap: true,               // REQUIRED for debugging
      watchFiles: true,              // REQUIRED for hot reload
      
      // Minification off for readability
      minifyTemplates: false,
      minifyStyles: false,
      removeComments: false,
      
      // Detailed logging
      showProcessedFiles: true,
      logger: {
        enabled: true,
        level: 3,                    // DEBUG level
        timestamp: true,
        colors: true
      }
    })
  ]
});

⚠️ Do NOT Use for Production

This plugin is for development only. For production builds:

import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    // DO NOT use @xcons/vite-plugin
    // Widgets will be already inlined in production
  ],
  build: {
    // Normal Vite production settings
    minify: 'terser',
    sourcemap: false
  }
});

Customized Configuration

import xconVitePlugin from '@xcons/vite-plugin';

export default defineConfig({
  plugins: [
    xconVitePlugin({
      // Development features
      development: true,
      sourceMap: true,
      watchFiles: true,
      
      // File filtering
      includeFiles: ['widget', 'component'],
      excludeFiles: ['test', 'spec'],
      
      // Custom extensions
      templateExtensions: ['.html', '.htm'],
      styleExtensions: ['.css', '.scss', '.less'],
      
      // Detailed logging
      showProcessedFiles: true,
      logger: {
        enabled: true,
        level: 3,
        colors: true
      }
    })
  ]
});

🎯 Usage Examples

Using with @xcons/widget

my-widget.component.ts:

import { Widget } from '@xcons/widget';

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

my-widget.component.html:

<div class="widget-container">
  <h1>Hello Widget!</h1>
  <p>This is an XCon widget.</p>
</div>

After (Development Build - For Debugging):

import { Widget } from '@xcons/widget';

@Widget({
  selector: 'my-widget',
  template: `<div class="widget-container">
  <h1>Hello Widget!</h1>
  <p>This is an XCon widget.</p>
</div>`,
  styles: ['.widget-container{padding:20px;background:#f5f5f5}...']
})
export class MyWidget {}

// ✅ Thanks to source maps:
// - You can set breakpoints in the HTML file
// - Error messages show the original file
// - Changes reflect instantly with hot reload

Hot Reload Example

While Development Server is Running:

npm run dev

1. Edit my-widget.component.html file:

<div class="widget-container">
  <h1>Updated Title!</h1>  <!-- Change -->
  <p>This is an XCon widget.</p>
</div>

2. Save the file → Widget auto-refreshes ✨
3. No page reload, only widget updates
4. Source map allows debugging in original HTML

Debugging and Breakpoints

In Chrome DevTools:

1. Open Sources tab
2. Find my-widget.component.html file
3. Set a breakpoint on any line
4. Widget stops at breakpoint when rendered
5. Call stack shows original files

// When error occurs in console:
Error: Something went wrong
    at MyWidget.render (my-widget.component.ts:45:12)  // ✅ Original file
    at WidgetManager.initialize (widget-manager.ts:23:8)

Style Processing and Hot Reload

my-widget.component.css:

.widget-container {
  padding: 20px;
  background: #f5f5f5;
}

.widget-container h1 {
  color: #333;
  font-size: 24px;
}

In Development:

1. Edit the CSS file
2. Save → Styles update instantly
3. No page reload, only CSS applied
4. Style debugging with source maps

Resource Management

Widget decorator resource definitions (as metadata only):

import { Widget } from '@xcons/widget';

@Widget({
  selector: 'my-widget',
  templateUrl: './my-widget.component.html',
  resources: [
    { 
      name: 'chart-lib', 
      type: 'js', 
      url: '/assets/chart.min.js' 
    }
  ]
})
export class MyWidget {}

// Note: resources are used as metadata only
// Plugin doesn't modify this field, only preserves it

🔧 Advanced Usage

Logger Integration

The plugin provides advanced logging using the @xcons/common package:

import xconVitePlugin from '@xcons/vite-plugin';

export default defineConfig({
  plugins: [
    xconVitePlugin({
      logger: {
        enabled: true,
        level: 3,              // 0: ERROR, 1: WARN, 2: INFO, 3: DEBUG, 4: TRACE
        prefix: 'XCON-VITE',
        timestamp: true,
        colors: true
      }
    })
  ]
});

Multiple Widget Project

// vite.config.ts
import xconVitePlugin from '@xcons/vite-plugin';

export default defineConfig({
  plugins: [
    xconVitePlugin({
      development: true,
      sourceMap: true,
      watchFiles: true,
      
      // Process only widget files
      includeFiles: ['widget', 'component'],
      excludeFiles: ['test', 'spec', 'mock'],
      
      // Custom extensions
      templateExtensions: ['.html', '.htm'],
      styleExtensions: ['.css', '.scss', '.less']
    })
  ]
});

File Watching Customization

export default defineConfig({
  plugins: [
    xconVitePlugin({
      watchFiles: true,  // Watch file changes
      
      // File extensions to watch
      fileExtensions: ['.ts', '.js'],
      templateExtensions: ['.html'],
      styleExtensions: ['.css', '.scss'],
      
      // Detailed log for performance
      showProcessedFiles: true
    })
  ]
});

🔍 Debugging

Using Source Maps

The plugin creates precise source maps using magic-string:

# Required for source map support
npm install magic-string --save-dev

export default defineConfig({
  plugins: [
    xconVitePlugin({
      sourceMap: true  // Automatically uses magic-string if available
    })
  ]
});

Benefits:

• ✅ Breakpoints in original HTML/CSS files
• ✅ Error messages show real file locations
• ✅ Call stack shows original source code
• ✅ Console.log shows correct line numbers

Detailed Logging

xconVitePlugin({
  showProcessedFiles: true,  // Show processed files
  logger: {
    enabled: true,
    level: 3,  // DEBUG - Most detailed
    timestamp: true
  }
})

Console Output

[XCon Plugin] 🚀 XCon Vite Plugin started
[XCon Plugin] 🔧 Configuration: { 
  development: true, 
  sourceMap: true, 
  watchFiles: true 
}
[XCon Plugin] 🔄 Processed: my-widget.component.ts
[XCon Plugin] 📄 Loaded HTML template: my-widget.component.html (1.2KB)
[XCon Plugin] 🎨 Loaded style: my-widget.component.css (856B)
[XCon Plugin] 🗺️  Source map generated for debugging
[XCon Plugin] ✅ XCon Vite Plugin finished

Common Issues

Problem: Hot reload not working

// Solution: Enable watchFiles
xconVitePlugin({
  watchFiles: true,  // ✅ This is REQUIRED
  development: true
})

Problem: Breakpoints not working

# Solution 1: Install magic-string
npm install magic-string --save-dev

# Solution 2: Enable source maps
# vite.config.ts
xconVitePlugin({
  sourceMap: true  // ✅ This is REQUIRED
})

Problem: Template not found

// ✅ Correct: Use relative path
templateUrl: './my-widget.component.html'

// ❌ Wrong: Without relative path
templateUrl: 'my-widget.component.html'

Problem: Incompatibility with @xcons/widget

# Solution: Use latest versions of both packages
npm install @xcons/widget@latest
npm install @xcons/vite-plugin@latest --save-dev

📦 Dependencies

Installation (Recommended)

# Widget package (production dependency)
npm install @xcons/widget

# Development plugin
npm install @xcons/vite-plugin --save-dev

# For source map support (RECOMMENDED)
npm install magic-string --save-dev

# For advanced logging (optional)
npm install @xcons/common --save-dev

package.json Example

{
  "dependencies": {
    "@xcons/widget": "^1.2.1"
  },
  "devDependencies": {
    "@xcons/vite-plugin": "^1.2.1",
    "vite": "^7.1.5",
    "magic-string": "^0.30.18",
    "@xcons/common": "^2.0.7",
    "typescript": "^5.5.2"
  }
}

Note: Use specific version numbers (with ^). Using "latest" can lead to unexpected incompatibilities.

🧪 Testing and Development

Development Server

# Start development server in your widget project
npm run dev

# Plugin automatically:
# - Watches template changes
# - Applies style updates
# - Refreshes widgets with hot reload
# - Generates source maps

Example Project Structure

my-widget-project/
├── src/
│   ├── widgets/
│   │   ├── my-widget/
│   │   │   ├── my-widget.component.ts       # @xcons/widget
│   │   │   ├── my-widget.component.html     # Template
│   │   │   └── my-widget.component.css      # Styles
│   └── main.ts
├── vite.config.ts                            # Plugin configuration
└── package.json

Development Workflow

1. Create widget (with @xcons/widget)

import { Widget } from '@xcons/widget';

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

2. Start dev server

npm run dev

3. Develop and debug

• Edit template → Auto refresh
• Change CSS → Instant update
• Set breakpoint → Debug with source maps

4. Production build (without plugin)

npm run build

📄 License

MIT © XCon Studio

🔗 Links

• NPM Package
• @xcons/widget Package
• GitHub Repository
• XCon Studio
• Documentation
• Issues

⭐ Support

If this project helped you, give it a ⭐️!

Made with ❤️ by XCon Studio