Docs: Document Official Vite Plugin (vite-plugin-avenx) Integration and Hot Module Replacement (HMR)

[nathanschmid08]

Summary & Feature Context

The vite-plugin-avenx plugin (vite-plugin-avenx/src/index.js) provides native Vite integration for Avenx-JS projects. It enforces pre-transform hooks (enforce: 'pre'), parses Single File Component (.component.js) and page (.page.js) files via ComponentParser, compiles component scoped styles (.component.css and .page.css) using StyleProcessor, wraps class exports with HMR helpers (wrapComponent, wrapPage), and triggers full/partial HMR reloads via handleAvenxHotUpdate.

Currently, the official documentation site (docs/src/content/docs/) lacks a dedicated guide for vite-plugin-avenx. This issue requests a comprehensive integration and tooling reference guide.

Detailed Scope of Work

1. Installation & Plugin Configuration

• Package Installation: Document how to install vite-plugin-avenx alongside vite.
• vite.config.js Setup: Document importing avenxPlugin and registering it inside plugins: [avenxPlugin(options)].
• Plugin Options:
  • debug (boolean, default: false): Enables debug logging in the Vite dev server ([vite-plugin-avenx] Compile Component...).
  • style (object): Options passed directly to StyleProcessor (e.g., preprocessor configs, scoping options).

2. SFC & Page Compilation Lifecycle

• Detail how isComponentFile(id) and isPageFile(id) identify .component.js and .page.js files based on naming conventions (utils.js).
• Explain class name derivation in createCompiler: file paths like components/user-card.component.js automatically compile into class name UserCard.
• Explain how loadStyle(id) handles inline and linked stylesheets (isComponentStyle(id) / isPageStyle(id)).

3. Hot Module Replacement (HMR) Architecture

• Detail how handleHotUpdate(ctx) processes file updates during development.
• Document the WebSocket reload event sent by server.ws.send({ type: 'full-reload' }) when .component.js, .page.js, or .css files change.
• Compare Vite-based development vs. the standalone avenx dev CLI server dashboard.

4. Code Examples & Troubleshooting Guide

• Provide a full vite.config.js boilerplate for multi-page or SPA Avenx apps.
• Include a troubleshooting section addressing:
  • Component naming mismatches when file paths lack .component.js suffixes.
  • CSS scoping resolution in Vite's asset pipeline.
  • Resolving virtual imports and module IDs.

Target Location in Docs Site

• New page: docs/src/content/docs/cli-reference/vite-plugin.md or section in docs/src/content/docs/getting-started/configuration.md.